Repository navigation
docs: update styles to indicate exception raised on style not defined #170
Description
Activity
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-upYes, 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?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 2in 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-stylesand here:
http://python-docx.readthedocs.org/en/latest/user/styles-using.html#working-with-latent-stylesIn 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.xmlpart 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 2in 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 2paragraph 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.Reacted by albcunha- changed the title
[-]Custom styles[/-][+]docs: update styles to indicate exception raised on style not defined[/+]on Apr 2, 2015
Whenever I add a custom style to the template default.docx and try to create a document I get the following error:
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: