Style-related objects

A style is used to collect a set of formatting properties under a single name and apply those properties to a content object all at once. This promotes formatting consistency throughout a document and across related documents and allows formatting changes to be made globally by changing the definition in the appropriate style.

Styles objects

class docx.styles.styles.Styles

Provides access to the styles defined in a document.

Accessed using the Document.styles property. Supports len(), iteration, and dictionary-style access by style name.

add_style(name, style_type, builtin=False)

Return a newly added style object of style_type and identified by name. A builtin style can be defined by passing True for the optional builtin argument.

default(style_type)

Return the default style for style_type or None if no default is defined for that type (not common).

element

The lxml element proxied by this object.

latent_styles

A LatentStyles object providing access to the default behaviors for latent styles and the collection of _LatentStyle objects that define overrides of those defaults for a particular named latent style.

BaseStyle objects

class docx.styles.style.BaseStyle

Base class for the various types of style object, paragraph, character, table, and numbering. These properties and methods are inherited by all style objects.

builtin

Read-only. True if this style is a built-in style. False indicates it is a custom (user-defined) style. Note this value is based on the presence of a customStyle attribute in the XML, not on specific knowledge of which styles are built into Word.

delete()

Remove this style definition from the document. Note that calling this method does not remove or change the style applied to any document content. Content items having the deleted style will be rendered using the default style, as is any content with a style not defined in the document.

element

The lxml element proxied by this object.

hidden

True if display of this style in the style gallery and list of recommended styles is suppressed. False otherwise. In order to be shown in the style gallery, this value must be False and quick_style must be True.

locked

Read/write Boolean. True if this style is locked. A locked style does not appear in the styles panel or the style gallery and cannot be applied to document content. This behavior is only active when formatting protection is turned on for the document (via the Developer menu).

name

The UI name of this style.

priority

The integer sort key governing display sequence of this style in the Word UI. None indicates no setting is defined, causing Word to use the default value of 0. Style name is used as a secondary sort key to resolve ordering of styles having the same priority value.

quick_style

True if this style should be displayed in the style gallery when hidden is False. Read/write Boolean.

type

Member of WD_STYLE_TYPE corresponding to the type of this style, e.g. WD_STYLE_TYPE.PARAGRAPH.

unhide_when_used

True if an application should make this style visible the next time it is applied to content. False otherwise. Note that python-docx does not automatically unhide a style having True for this attribute when it is applied to content.

_CharacterStyle objects

class docx.styles.style._CharacterStyle

Bases: docx.styles.style.BaseStyle

A character style. A character style is applied to a Run object and primarily provides character-level formatting via the Font object in its font property.

base_style

Style object this style inherits from or None if this style is not based on another style.

builtin

Read-only. True if this style is a built-in style. False indicates it is a custom (user-defined) style. Note this value is based on the presence of a customStyle attribute in the XML, not on specific knowledge of which styles are built into Word.

delete()

Remove this style definition from the document. Note that calling this method does not remove or change the style applied to any document content. Content items having the deleted style will be rendered using the default style, as is any content with a style not defined in the document.

font

The Font object providing access to the character formatting properties for this style, such as font name and size.

hidden

True if display of this style in the style gallery and list of recommended styles is suppressed. False otherwise. In order to be shown in the style gallery, this value must be False and quick_style must be True.

locked

Read/write Boolean. True if this style is locked. A locked style does not appear in the styles panel or the style gallery and cannot be applied to document content. This behavior is only active when formatting protection is turned on for the document (via the Developer menu).

name

The UI name of this style.

priority

The integer sort key governing display sequence of this style in the Word UI. None indicates no setting is defined, causing Word to use the default value of 0. Style name is used as a secondary sort key to resolve ordering of styles having the same priority value.

quick_style

True if this style should be displayed in the style gallery when hidden is False. Read/write Boolean.

unhide_when_used

True if an application should make this style visible the next time it is applied to content. False otherwise. Note that python-docx does not automatically unhide a style having True for this attribute when it is applied to content.

_ParagraphStyle objects

class docx.styles.style._ParagraphStyle

Bases: docx.styles.style._CharacterStyle

A paragraph style. A paragraph style provides both character formatting and paragraph formatting such as indentation and line-spacing.

base_style

Style object this style inherits from or None if this style is not based on another style.

builtin

Read-only. True if this style is a built-in style. False indicates it is a custom (user-defined) style. Note this value is based on the presence of a customStyle attribute in the XML, not on specific knowledge of which styles are built into Word.

delete()

Remove this style definition from the document. Note that calling this method does not remove or change the style applied to any document content. Content items having the deleted style will be rendered using the default style, as is any content with a style not defined in the document.

font

The Font object providing access to the character formatting properties for this style, such as font name and size.

hidden

True if display of this style in the style gallery and list of recommended styles is suppressed. False otherwise. In order to be shown in the style gallery, this value must be False and quick_style must be True.

locked

Read/write Boolean. True if this style is locked. A locked style does not appear in the styles panel or the style gallery and cannot be applied to document content. This behavior is only active when formatting protection is turned on for the document (via the Developer menu).

name

The UI name of this style.

next_paragraph_style

_ParagraphStyle object representing the style to be applied automatically to a new paragraph inserted after a paragraph of this style. Returns self if no next paragraph style is defined. Assigning None or self removes the setting such that new paragraphs are created using this same style.

paragraph_format

The ParagraphFormat object providing access to the paragraph formatting properties for this style such as indentation.

priority

The integer sort key governing display sequence of this style in the Word UI. None indicates no setting is defined, causing Word to use the default value of 0. Style name is used as a secondary sort key to resolve ordering of styles having the same priority value.

quick_style

True if this style should be displayed in the style gallery when hidden is False. Read/write Boolean.

unhide_when_used

True if an application should make this style visible the next time it is applied to content. False otherwise. Note that python-docx does not automatically unhide a style having True for this attribute when it is applied to content.

_TableStyle objects

class docx.styles.style._TableStyle

Bases: docx.styles.style._ParagraphStyle

A table style. A table style provides character and paragraph formatting for its contents as well as special table formatting properties.

base_style

Style object this style inherits from or None if this style is not based on another style.

builtin

Read-only. True if this style is a built-in style. False indicates it is a custom (user-defined) style. Note this value is based on the presence of a customStyle attribute in the XML, not on specific knowledge of which styles are built into Word.

delete()

Remove this style definition from the document. Note that calling this method does not remove or change the style applied to any document content. Content items having the deleted style will be rendered using the default style, as is any content with a style not defined in the document.

font

The Font object providing access to the character formatting properties for this style, such as font name and size.

hidden

True if display of this style in the style gallery and list of recommended styles is suppressed. False otherwise. In order to be shown in the style gallery, this value must be False and quick_style must be True.

locked

Read/write Boolean. True if this style is locked. A locked style does not appear in the styles panel or the style gallery and cannot be applied to document content. This behavior is only active when formatting protection is turned on for the document (via the Developer menu).

name

The UI name of this style.

next_paragraph_style

_ParagraphStyle object representing the style to be applied automatically to a new paragraph inserted after a paragraph of this style. Returns self if no next paragraph style is defined. Assigning None or self removes the setting such that new paragraphs are created using this same style.

paragraph_format

The ParagraphFormat object providing access to the paragraph formatting properties for this style such as indentation.

priority

The integer sort key governing display sequence of this style in the Word UI. None indicates no setting is defined, causing Word to use the default value of 0. Style name is used as a secondary sort key to resolve ordering of styles having the same priority value.

quick_style

True if this style should be displayed in the style gallery when hidden is False. Read/write Boolean.

unhide_when_used

True if an application should make this style visible the next time it is applied to content. False otherwise. Note that python-docx does not automatically unhide a style having True for this attribute when it is applied to content.

_NumberingStyle objects

class docx.styles.style._NumberingStyle

A numbering style. Not yet implemented.

LatentStyles objects

class docx.styles.latent.LatentStyles

Provides access to the default behaviors for latent styles in this document and to the collection of _LatentStyle objects that define overrides of those defaults for a particular named latent style.

add_latent_style(name)

Return a newly added _LatentStyle object to override the inherited defaults defined in this latent styles object for the built-in style having name.

default_priority

Integer between 0 and 99 inclusive specifying the default sort order for latent styles in style lists and the style gallery. None if no value is assigned, which causes Word to use the default value 99.

default_to_hidden

Boolean specifying whether the default behavior for latent styles is to be hidden. A hidden style does not appear in the recommended list or in the style gallery.

default_to_locked

Boolean specifying whether the default behavior for latent styles is to be locked. A locked style does not appear in the styles panel or the style gallery and cannot be applied to document content. This behavior is only active when formatting protection is turned on for the document (via the Developer menu).

default_to_quick_style

Boolean specifying whether the default behavior for latent styles is to appear in the style gallery when not hidden.

default_to_unhide_when_used

Boolean specifying whether the default behavior for latent styles is to be unhidden when first applied to content.

element

The lxml element proxied by this object.

load_count

Integer specifying the number of built-in styles to initialize to the defaults specified in this LatentStyles object. None if there is no setting in the XML (very uncommon). The default Word 2011 template sets this value to 276, accounting for the built-in styles in Word 2010.

_LatentStyle objects

class docx.styles.latent._LatentStyle

Proxy for an w:lsdException element, which specifies display behaviors for a built-in style when no definition for that style is stored yet in the styles.xml part. The values in this element override the defaults specified in the parent w:latentStyles element.

delete()

Remove this latent style definition such that the defaults defined in the containing LatentStyles object provide the effective value for each of its attributes. Attempting to access any attributes on this object after calling this method will raise AttributeError.

element

The lxml element proxied by this object.

hidden

Tri-state value specifying whether this latent style should appear in the recommended list. None indicates the effective value is inherited from the parent <w:latentStyles> element.

locked

Tri-state value specifying whether this latent styles is locked. A locked style does not appear in the styles panel or the style gallery and cannot be applied to document content. This behavior is only active when formatting protection is turned on for the document (via the Developer menu).

name

The name of the built-in style this exception applies to.

priority

The integer sort key for this latent style in the Word UI.

quick_style

Tri-state value specifying whether this latent style should appear in the Word styles gallery when not hidden. None indicates the effective value should be inherited from the default values in its parent LatentStyles object.

unhide_when_used

Tri-state value specifying whether this style should have its hidden attribute set False the next time the style is applied to content. None indicates the effective value should be inherited from the default specified by its parent LatentStyles object.