This page uses concepts developed in the prior page without introduction. If a term is unfamiliar, consult the prior page :ref:`understanding_styles` for a definition.
Styles are accessed using the :attr:`.Document.styles` attribute:
>>> document = Document() >>> styles = document.styles >>> styles <docx.styles.styles.Styles object at 0x10a7c4f50>
The |Styles| object provides dictionary-style access to defined styles by name:
>>> styles['Normal'] <docx.styles.style._ParagraphStyle object at <0x10a7c4f6b>
Note
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'. Because |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 names: http://www.thedoctools.com/index.php?show=mt_create_style_name_list
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.
The |Styles| object is also iterable. By using the identification properties on |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
The |Paragraph|, |Run|, and |Table| objects each have a :attr:`style` attribute. Assigning a style object to this attribute applies that 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 |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'
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)
Use the :attr:`~.BaseStyle.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 :meth:`~.BaseStyle.delete` method:
>>> styles = document.styles >>> len(styles) 10 >>> styles['Citation'].delete() >>> len(styles) 9
Note
The :meth:`.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.
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.
Each of these three style types have a :attr:`~._CharacterStyle.font` attribute providing access to a |Font| object. A style's |Font| object provides properties for getting and setting the character formatting for that style.
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|, |False|, and |None|. |True| means the property is "on", |False| means 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 list:
>>> 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 most common. |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 :ref:`WdUnderline` enumeration:
>>> font.underline None >>> font.underline = True >>> # or perhaps >>> font.underline = WD_UNDERLINE.DOT_DASH
Both a paragraph style and a table style allow paragraph formatting to be specified. These styles provide access to a |ParagraphFormat| object via their :attr:`~._ParagraphStyle.paragraph_format` property.
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 |ParagraphFormat| object.
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
A paragraph style has a :attr:`~._ParagraphStyle.next_paragraph_style` 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'
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:
- :attr:`~.BaseStyle.hidden`
- :attr:`~.BaseStyle.unhide_when_used`
- :attr:`~.BaseStyle.priority`
- :attr:`~.BaseStyle.quick_style`
- :attr:`~.BaseStyle.locked`
See the :ref:`style_behavior` section in :ref:`understanding_styles` for a description of how these behavioral properties interact to determine when and where a style appears in the Word UI.
The :attr:`priority` property takes an integer value. The other four style behavior properties are tri-state, meaning they can take the value |True| (on), |False| (off), or |None| (inherit).
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
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
See the :ref:`builtin_styles` and :ref:`latent_styles` sections in :ref:`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.
The latent styles in a document are accessed from the styles object:
>>> document = Document() >>> latent_styles = document.styles.latent_styles
A |LatentStyles| object supports :meth:`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
The |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 |_LatentStyle| 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
A new latent style can be added using the :meth:`~.LatentStyles.add_latent_style` method on |LatentStyles|. This code adds a new latent style for the builtin style 'List Bullet', setting it to appear in the style gallery:
>>> 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
A latent style definition can be deleted by calling its :meth:`~.LatentStyle.delete` method:
>>> 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'