docs: update styles to indicate exception raised on style not defined

[micabot]

Whenever I add a custom style to the template default.docx and try to create a document I get the following error:

Traceback (most recent call last):
  File "helloworld.py", line 9, in <module>
    document.add_heading('smiling having fun', 2)
  File "/usr/lib/python2.7/site-packages/docx/document.py", line 43, in add_heading
    return self.add_paragraph(text, style)
  File "/usr/lib/python2.7/site-packages/docx/document.py", line 63, in add_paragraph
    return self._body.add_paragraph(text, style)
  File "/usr/lib/python2.7/site-packages/docx/blkcntnr.py", line 38, in add_paragraph
    paragraph.style = style
  File "/usr/lib/python2.7/site-packages/docx/text/paragraph.py", line 111, in style
    style_or_name, WD_STYLE_TYPE.PARAGRAPH
  File "/usr/lib/python2.7/site-packages/docx/parts/document.py", line 75, in get_style_id
    return self.styles.get_style_id(style_or_name, style_type)
  File "/usr/lib/python2.7/site-packages/docx/styles/styles.py", line 113, in get_style_id
    return self._get_style_id_from_name(style_or_name, style_type)
  File "/usr/lib/python2.7/site-packages/docx/styles/styles.py", line 143, in _get_style_id_from_name
    return self._get_style_id_from_style(self[style_name], style_type)
  File "/usr/lib/python2.7/site-packages/docx/styles/styles.py", line 57, in __getitem__
    raise KeyError("no style with name '%s'" % key)
KeyError: u"no style with name 'Heading 2'"

This happens with python 2.7 using python-docx 0.8.5, and it didn't happend with 0.7.4.
The code I'm using to generate the document is:

#!/usr/bin/env python2.7
import os
import os.path
from docx import Document

PATH = os.path.dirname(os.path.realpath(__file__)) + '/'

document = Document(os.path.join(PATH, 'default.docx'))
document.add_heading('smiling having fun', 2)
document.add_paragraph('hello world?')
document.save('helloworld.docx')

[scanny]

Does it work if you don't specify a path to the Document() call?

Make sure you understand this section in the documentation:
http://python-docx.readthedocs.org/en/latest/user/styles-understanding.html#why-doesn-t-the-style-i-applied-show-up

[micabot]

Yes, it works if I call Document() with no params. But that's the same as using the unmodified template.
I read the documentation several times, but from what I understand if I use a style that is not in the styles.xml it shouldn't throw an error, right?

If you apply a style using python-docx that’s not defined in your file (in the styles.xml part if you’re curious), Word just ignores it. It doesn’t complain, it just doesn’t change how things are formatted. I’m sure there’s a good reason for this. But it can present as a bit of a puzzle if you don’t understand how Word works that way.

Although that paragraph mentions Word not complaining about it, not python-docx.
And also, when I edit the template I'm not removing default styles, I'm just adding a new one, I don't see how that could make a difference. In fact, after editing the template I can see the "Heading 2" definition in the styles.xml and I still get the error.
However, it seems the problem appears only when I edit the template with LibreOffice. Just tried the same using Word and it worked fine.
Should I close this or is this something to be concerned about?

[scanny]

Well, since the recent additions to styles capability in release 0.8.0, I should probably revisit that documentation passage. It does rather imply that nothing will happen when applying a non-existent style.

Your suspicion is correct. Word won't complain, but now python-docx does if you attempt to assign a style that isn't defined.

I'm not sure what style definition you're seeing for Heading 2 in your styles.xml, but I suspect it is a latent style definition. You can read about those in the documentation here:
http://python-docx.readthedocs.org/en/latest/user/styles-understanding.html#latent-styles

and here:
http://python-docx.readthedocs.org/en/latest/user/styles-using.html#working-with-latent-styles

In short, they only define the UI behaviors for a built-in style, like whether it should appear in the styles gallery, when that style isn't defined in the document yet. Word will add the explicity built-in style definition to the styles.xml part as a <w:style>.. element (not a <w:lsdException> element) the first time it is used.

In general, what you would want to do is either define Heading 2 in your starting document if you wanted to use it in the document you're building, or define it explicitly in your code using .add_style() before calling .add_heading().

You can add it to your starting document simply by creating a paragraph, assigning the Heading 2 paragraph style to it, and then deleting the paragraph. The style will be retained in the file once used, even if what it was applied to is now gone.