styles

styles

Custom element classes related to the styles part.

CT_PPrDefault

Bases: BaseOxmlElement

w:pPrDefault element, wrapping the document-wide default paragraph formatting.

CT_RPrDefault

Bases: BaseOxmlElement

w:rPrDefault element, wrapping the document-wide default run formatting.

CT_DocDefaults

Bases: BaseOxmlElement

w:docDefaults element, the bottom of the formatting inheritance chain.

Whatever is set here applies to the whole document before any style or direct formatting. For many real documents it is the only place the base font and the base paragraph spacing are set.

CT_LatentStyles

Bases: BaseOxmlElement

w:latentStyles element, defining behavior defaults for latent styles and containing w:lsdException child elements that each override those defaults for a named latent style.

bool_prop

bool_prop(attr_name)

Return the boolean value of the attribute having attr_name, or False if not present.

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

def bool_prop(self, attr_name):
    """Return the boolean value of the attribute having `attr_name`, or |False| if
    not present."""
    value = getattr(self, attr_name)
    if value is None:
        return False
    return value

get_by_name

get_by_name(name)

Return the w:lsdException child having name, or None if not found.

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

def get_by_name(self, name):
    """Return the `w:lsdException` child having `name`, or |None| if not found."""
    found = self.xpath("w:lsdException[@w:name=$name]", name=name)
    if not found:
        return None
    return found[0]

set_bool_prop

set_bool_prop(attr_name, value)

Set the on/off attribute having attr_name to value.

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

def set_bool_prop(self, attr_name, value):
    """Set the on/off attribute having `attr_name` to `value`."""
    setattr(self, attr_name, bool(value))

CT_LsdException

Bases: BaseOxmlElement

<w:lsdException> element, defining override visibility behaviors for a named latent style.

delete

delete()

Remove this w:lsdException element from the XML document.

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

def delete(self):
    """Remove this `w:lsdException` element from the XML document."""
    self.getparent().remove(self)

on_off_prop

on_off_prop(attr_name)

Return the boolean value of the attribute having attr_name, or None if not present.

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

def on_off_prop(self, attr_name):
    """Return the boolean value of the attribute having `attr_name`, or |None| if
    not present."""
    return getattr(self, attr_name)

set_on_off_prop

set_on_off_prop(attr_name, value)

Set the on/off attribute having attr_name to value.

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

def set_on_off_prop(self, attr_name, value):
    """Set the on/off attribute having `attr_name` to `value`."""
    setattr(self, attr_name, value)

CT_Style

Bases: BaseOxmlElement

A <w:style> element, representing a style definition.

basedOn_val property writable

basedOn_val

Value of w:basedOn/@w:val or None if not present.

base_style property

base_style

Sibling CT_Style element this style is based on or None if no base style or base style not found.

locked_val property writable

locked_val

Value of w:locked/@w:val or False if not present.

name_val property writable

name_val

Value of <w:name> child or None if not present.

link_val property writable

link_val

Value of w:link/@w:val or None if not present.

The id of the paired style of the other kind: a paragraph style's w:link names the character style holding its run formatting, and vice versa. Copying one without the other leaves a dangling pair.

next_val property writable

next_val

Value of w:next/@w:val or None if not present.

numId_val property writable

numId_val: int | None

Value of ./w:pPr/w:numPr/w:numId/@w:val, or None if not present.

A numbering reference points into the numbering part, so it means nothing on its own in another document.

next_style property

next_style

Sibling CT_Style element identified by the value of w:name/@w:val or None if no value is present or no style with that style id is found.

qFormat_val property writable

qFormat_val

Value of w:qFormat/@w:val or False if not present.

semiHidden_val property writable

semiHidden_val

Value of <w:semiHidden> child or False if not present.

uiPriority_val property writable

uiPriority_val

Value of <w:uiPriority> child or None if not present.

unhideWhenUsed_val property writable

unhideWhenUsed_val

Value of w:unhideWhenUsed/@w:val or False if not present.

delete

delete()

Remove this w:style element from its parent w:styles element.

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

def delete(self):
    """Remove this `w:style` element from its parent `w:styles` element."""
    self.getparent().remove(self)

CT_Styles

Bases: BaseOxmlElement

<w:styles> element, the root element of a styles part, i.e. styles.xml.

add_style_of_type

add_style_of_type(name, style_type, builtin)

Return a newly added w:style element having name and style_type.

w:style/@customStyle is set based on the value of builtin.

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

def add_style_of_type(self, name, style_type, builtin):
    """Return a newly added `w:style` element having `name` and `style_type`.

    `w:style/@customStyle` is set based on the value of `builtin`.
    """
    style = self.add_style()
    style.type = style_type
    style.customStyle = None if builtin else True
    style.styleId = styleId_from_name(name)
    style.name_val = name
    return style

default_for

default_for(style_type)

Return w:style[@w:type="*{style_type}*][-1] or None if not found.

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

def default_for(self, style_type):
    """Return `w:style[@w:type="*{style_type}*][-1]` or |None| if not found."""
    default_styles_for_type = [
        s for s in self._iter_styles() if s.type == style_type and s.default
    ]
    if not default_styles_for_type:
        return None
    # spec calls for last default in document order
    return default_styles_for_type[-1]

get_by_id

get_by_id(styleId: str) -> CT_Style | None

w:style child where @styleId = styleId.

None if not found.

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

def get_by_id(self, styleId: str) -> CT_Style | None:
    """`w:style` child where @styleId = `styleId`.

    |None| if not found.
    """
    return next(iter(self.xpath("w:style[@w:styleId=$style_id]", style_id=styleId)), None)

get_by_name

get_by_name(name: str) -> CT_Style | None

w:style child with w:name grandchild having value name.

Matched exactly first, then case-insensitively. Word treats style names as case-insensitive, and a built-in style has two spellings — the UI name ("Heading 1") and the internal name Word stores ("heading 1"). Documents written by other generators routinely store the UI casing, and without the second pass the style is present but unreachable.

The exact pass runs first so that a document containing both spellings resolves to the one asked for rather than to whichever comes first.

None if not found.

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

def get_by_name(self, name: str) -> CT_Style | None:
    """`w:style` child with `w:name` grandchild having value `name`.

    Matched exactly first, then case-insensitively. Word treats style names as
    case-insensitive, and a built-in style has two spellings — the UI name
    ("Heading 1") and the internal name Word stores ("heading 1"). Documents
    written by other generators routinely store the UI casing, and without the
    second pass the style is present but unreachable.

    The exact pass runs first so that a document containing both spellings resolves
    to the one asked for rather than to whichever comes first.

    |None| if not found.
    """
    exact = next(iter(self.xpath("w:style[w:name/@w:val=$name]", name=name)), None)
    if exact is not None:
        return exact

    # -- no XPath 1.0 lower-case function, so fold in Python. Only reached when the
    # -- exact match fails, which for a Word-authored document is never. --
    folded = name.lower()
    for style in self.xpath("w:style"):
        style_name = style.name_val
        if style_name is not None and style_name.lower() == folded:
            return style
    return None

styleId_from_name

styleId_from_name(name)

Return the style id corresponding to name, taking into account special-case names such as 'Heading 1'.

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

def styleId_from_name(name):
    """Return the style id corresponding to `name`, taking into account special-case
    names such as 'Heading 1'."""
    return {
        "caption": "Caption",
        "heading 1": "Heading1",
        "heading 2": "Heading2",
        "heading 3": "Heading3",
        "heading 4": "Heading4",
        "heading 5": "Heading5",
        "heading 6": "Heading6",
        "heading 7": "Heading7",
        "heading 8": "Heading8",
        "heading 9": "Heading9",
    }.get(name, name.replace(" ", ""))