style

style

Style object hierarchy.

BaseStyle

BaseStyle(
    style_elm: CT_Style, part: DocumentPart | None = None
)

Bases: ElementProxy

Base class for the various types of style object, paragraph, character, table, and numbering.

These properties and methods are inherited by all style objects.

Source code in src/docx/styles/style.py

def __init__(self, style_elm: CT_Style, part: DocumentPart | None = None):
    super().__init__(style_elm)
    self._style_elm = style_elm
    self._doc_part = part

document_part property

document_part: DocumentPart | None

The DocumentPart this style belongs to, None when it is not known.

A style reached through Document.styles knows its document, which is what lets a style copied out of it carry its numbering with it. One constructed directly from an element does not.

builtin property

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.

in_use property

in_use: bool

True when this style is reachable from the document's content.

"Reachable" is the closure Styles.usage computes, so a style used only as the w:basedOn of a used style counts, as does a w:default="1" style that nothing names outright:

>>> [s.name for s in document.styles if s.in_use]
['Normal', 'Heading 1', 'Hyperlink']

Reading this on every style of a document recomputes the closure each time; use Styles.usage for more than a handful.

Always False for a style whose document part is unknown — one constructed directly from an element rather than reached through Document.styles — because there is no content to be reachable from.

hidden property writable

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 property writable

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 property writable

name

The UI name of this style.

priority property writable

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 property writable

quick_style

True if this style should be displayed in the style gallery when hidden is False.

Read/write Boolean.

style_id property writable

style_id: str

The unique key name (string) for this style.

This value is subject to rewriting by Word and should generally not be changed unless you are familiar with the internals involved.

type property

type

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

unhide_when_used property writable

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.

delete

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.

Source code in src/docx/styles/style.py

def delete(self):
    """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.
    """
    self._element.delete()
    self._element = None

CharacterStyle

CharacterStyle(
    style_elm: CT_Style, part: DocumentPart | None = None
)

Bases: 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.

Source code in src/docx/styles/style.py

def __init__(self, style_elm: CT_Style, part: DocumentPart | None = None):
    super().__init__(style_elm)
    self._style_elm = style_elm
    self._doc_part = part

base_style property writable

base_style

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

font property

font

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

ParagraphStyle

ParagraphStyle(
    style_elm: CT_Style, part: DocumentPart | None = None
)

Bases: CharacterStyle

A paragraph style.

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

Source code in src/docx/styles/style.py

def __init__(self, style_elm: CT_Style, part: DocumentPart | None = None):
    super().__init__(style_elm)
    self._style_elm = style_elm
    self._doc_part = part

next_paragraph_style property writable

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 property

paragraph_format

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

_TableStyle

_TableStyle(
    style_elm: CT_Style, part: DocumentPart | None = None
)

Bases: ParagraphStyle

A table style.

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

Source code in src/docx/styles/style.py

def __init__(self, style_elm: CT_Style, part: DocumentPart | None = None):
    super().__init__(style_elm)
    self._style_elm = style_elm
    self._doc_part = part

_NumberingStyle

_NumberingStyle(
    style_elm: CT_Style, part: DocumentPart | None = None
)

Bases: BaseStyle

A numbering style.

Not yet implemented.

Source code in src/docx/styles/style.py

def __init__(self, style_elm: CT_Style, part: DocumentPart | None = None):
    super().__init__(style_elm)
    self._style_elm = style_elm
    self._doc_part = part

StyleFactory

StyleFactory(
    style_elm: CT_Style, part: DocumentPart | None = None
) -> BaseStyle

Return Style object of appropriate BaseStyle subclass for style_elm.

Source code in src/docx/styles/style.py

def StyleFactory(style_elm: CT_Style, part: DocumentPart | None = None) -> BaseStyle:
    """Return `Style` object of appropriate |BaseStyle| subclass for `style_elm`."""
    style_cls: Type[BaseStyle] = {
        WD_STYLE_TYPE.PARAGRAPH: ParagraphStyle,
        WD_STYLE_TYPE.CHARACTER: CharacterStyle,
        WD_STYLE_TYPE.TABLE: _TableStyle,
        WD_STYLE_TYPE.LIST: _NumberingStyle,
    }[style_elm.type]

    return style_cls(style_elm, part)