Working with Styles¶
This page uses concepts developed in the prior page without introduction. If a term is unfamiliar, consult the prior page Understanding Styles for a definition.
Access a style¶
Styles are accessed using the
>>> document = Document() >>> styles = document.styles >>> styles <docx.styles.styles.Styles object at 0x10a7c4f50>
Styles object provides dictionary-style access to defined styles by
>>> styles['Normal'] <docx.styles.style._ParagraphStyle object at <0x10a7c4f6b>
Built-in styles are stored in a WordprocessingML file using their
English name, e.g. ‘Heading 1’, even though users working on a localized
version of Word will see native language names in the UI, e.g. ‘Kop 1’.
python-docx operates on the WordprocessingML file, style lookups must
use the English name. A document available on this external site allows
you to create a mapping between local language names and English style
User-defined styles, also known as custom styles, are not localized and are accessed with the name exactly as it appears in the Word UI.
Styles object is also iterable. By using the identification properties
BaseStyle, various subsets of the defined styles can be generated. For
example, this code will produce a list of the defined paragraph styles:
>>> from docx.enum.style import WD_STYLE_TYPE >>> styles = document.styles >>> paragraph_styles = [ ... s for s in styles if s.type == WD_STYLE_TYPE.PARAGRAPH ... ] >>> for style in paragraph_styles: ... print(style.name) ... Normal Body Text List Bullet
Apply a style¶
>>> document = Document() >>> paragraph = document.add_paragraph() >>> paragraph.style <docx.styles.style._ParagraphStyle object at <0x11a7c4c50> >>> paragraph.style.name 'Normal' >>> paragraph.style = document.styles['Heading 1'] >>> paragraph.style.name 'Heading 1'
A style name can also be assigned directly, in which case
python-docx will do the
lookup for you:
>>> paragraph.style = 'List Bullet' >>> paragraph.style <docx.styles.style._ParagraphStyle object at <0x10a7c4f84> >>> paragraph.style.name 'List Bullet'
A style can also be applied at creation time using either the style object or its name:
>>> paragraph = document.add_paragraph(style='Body Text') >>> paragraph.style.name 'Body Text' >>> body_text_style = document.styles['Body Text'] >>> paragraph = document.add_paragraph(style=body_text_style) >>> paragraph.style.name 'Body Text'
Add or delete a style¶
A new style can be added to the document by specifying a unique name and a style type:
>>> from docx.enum.style import WD_STYLE_TYPE >>> styles = document.styles >>> style = styles.add_style('Citation', WD_STYLE_TYPE.PARAGRAPH) >>> style.name 'Citation' >>> style.type PARAGRAPH (1)
base_style property to specify a style the new
style should inherit formatting settings from:
>>> style.base_style None >>> style.base_style = styles['Normal'] >>> style.base_style <docx.styles.style._ParagraphStyle object at 0x10a7a9550> >>> style.base_style.name 'Normal'
A style can be removed from the document simply by calling its
>>> styles = document.styles >>> len(styles) 10 >>> styles['Citation'].delete() >>> len(styles) 9
Style.delete() method removes the style’s definition
from the document. It does not affect content in the document to which
that style is applied. Content having a style not defined in the document
is rendered using the default style for that content object, e.g.
‘Normal’ in the case of a paragraph.
Define character formatting¶
Character, paragraph, and table styles can all specify character formatting to be applied to content with that style. All the character formatting that can be applied directly to text can be specified in a style. Examples include font typeface and size, bold, italic, and underline.
Several examples are provided here. For a complete set of the available
properties, see the
Font API documentation.
The font for a style can be accessed like this:
>>> from docx import Document >>> document = Document() >>> style = document.styles['Normal'] >>> font = style.font
Typeface and size are set like this:
>>> from docx.shared import Pt >>> font.name = 'Calibri' >>> font.size = Pt(12)
Many font properties are tri-state, meaning they can take the values
True means the property is “on”,
it is “off”. Conceptually, the
None value means “inherit”. Because a style
exists in an inheritance hierarchy, it is important to have the ability to
specify a property at the right place in the hierarchy, generally as far up
the hierarchy as possible. For example, if all headings should be in the
Arial typeface, it makes more sense to set that property on the Heading 1
style and have Heading 2 inherit from Heading 1.
Bold and italic are tri-state properties, as are all-caps, strikethrough,
superscript, and many others. See the
Font API documentation for a full
>>> font.bold, font.italic (None, None) >>> font.italic = True >>> font.italic True >>> font.italic = False >>> font.italic False >>> font.italic = None >>> font.italic None
Underline is a bit of a special case. It is a hybrid of a tri-state property
and an enumerated value property.
True means single underline, by far the
False means no underline, but more often
None is the right
choice if no underlining is wanted since it is rare to inherit it from a base
style. The other forms of underlining, such as double or dashed, are
specified with a member of the WD_UNDERLINE enumeration:
>>> font.underline None >>> font.underline = True >>> # or perhaps >>> font.underline = WD_UNDERLINE.DOT_DASH
Define paragraph formatting¶
Paragraph formatting includes layout behaviors such as justification,
indentation, space before and after, page break before, and widow/orphan
control. For a complete list of the available properties, consult the API
documentation page for the
Here’s an example of how you would create a paragraph style having hanging indentation of 1/4 inch, 12 points spacing above, and widow/orphan control:
>>> from docx.enum.style import WD_STYLE_TYPE >>> from docx.shared import Inches, Pt >>> document = Document() >>> style = document.styles.add_style('Indent', WD_STYLE_TYPE.PARAGRAPH) >>> paragraph_format = style.paragraph_format >>> paragraph_format.left_indent = Inches(0.25) >>> paragraph_format.first_line_indent = Inches(-0.25) >>> paragraph_format.space_before = Pt(12) >>> paragraph_format.widow_control = True
Use paragraph-specific style properties¶
A paragraph style has a
property that specifies the style to be applied to new paragraphs inserted
after a paragraph of that style. This is most useful when the style would
normally appear only once in a sequence, such as a heading. In that case, the
paragraph style can automatically be set back to a body style after
completing the heading.
In the most common case (body paragraphs), subsequent paragraphs should receive the same style as the current paragraph. The default handles this case well by applying the same style if a next paragraph style is not specified.
Here’s an example of how you would change the next paragraph style of the Heading 1 style to Body Text:
>>> from docx import Document >>> document = Document() >>> styles = document.styles >>> styles['Heading 1'].next_paragraph_style = styles['Body Text']
The default behavior can be restored by assigning
None or the style itself:
>>> heading_1_style = styles['Heading 1'] >>> heading_1_style.next_paragraph_style.name 'Body Text' >>> heading_1_style.next_paragraph_style = heading_1_style >>> heading_1_style.next_paragraph_style.name 'Heading 1' >>> heading_1_style.next_paragraph_style = None >>> heading_1_style.next_paragraph_style.name 'Heading 1'
Control how a style appears in the Word UI¶
The properties of a style fall into two categories, behavioral properties and formatting properties. Its behavioral properties control when and where the style appears in the Word UI. Its formatting properties determine the formatting of content to which the style is applied, such as the size of the font and its paragraph indentation.
There are five behavioral properties of a style:
priority property takes an integer value. The other four style
behavior properties are tri-state, meaning they can take the value
False (off), or
Display a style in the style gallery¶
The following code will cause the ‘Body Text’ paragraph style to appear first in the style gallery:
>>> from docx import Document >>> document = Document() >>> style = document.styles['Body Text'] >>> style.hidden = False >>> style.quick_style = True >>> style.priorty = 1
Remove a style from the style gallery¶
This code will remove the ‘Normal’ paragraph style from the style gallery, but allow it to remain in the recommended list:
>>> style = document.styles['Normal'] >>> style.hidden = False >>> style.quick_style = False
Working with Latent Styles¶
See the Built-in styles and Latent styles sections in Understanding Styles for a description of how latent styles define the behavioral properties of built-in styles that are not yet defined in the styles.xml part of a .docx file.
Access the latent styles in a document¶
The latent styles in a document are accessed from the styles object:
>>> document = Document() >>> latent_styles = document.styles.latent_styles
LatentStyles object supports
len(), iteration, and dictionary-style
access by style name:
>>> len(latent_styles) 161 >>> latent_style_names = [ls.name for ls in latent_styles] >>> latent_style_names ['Normal', 'Heading 1', 'Heading 2', ... 'TOC Heading'] >>> latent_quote = latent_styles['Quote'] >>> latent_quote <docx.styles.latent.LatentStyle object at 0x10a7c4f50> >>> latent_quote.priority 29
Change latent style defaults¶
LatentStyles object also provides access to the default behavioral
properties for built-in styles in the current document. These defaults
provide the value for any undefined attributes of the
definitions and to all behavioral properties of built-in styles having no
explicit latent style definition. See the API documentation for the
LatentStyles object for the complete set of available properties:
>>> latent_styles.default_to_locked False >>> latent_styles.default_to_locked = True >>> latent_styles.default_to_locked True
Add a latent style definition¶
>>> latent_style = latent_styles['List Bullet'] KeyError: no latent style with name 'List Bullet' >>> latent_style = latent_styles.add_latent_style('List Bullet') >>> latent_style.hidden = False >>> latent_style.priority = 2 >>> latent_style.quick_style = True
Delete a latent style definition¶
A latent style definition can be deleted by calling its
>>> latent_styles['Light Grid'] <docx.styles.latent.LatentStyle object at 0x10a7c4f50> >>> latent_styles['Light Grid'].delete() >>> latent_styles['Light Grid'] KeyError: no latent style with name 'Light Grid'