Skip to content

latent

latent

Latent style-related objects.

LatentStyles 

LatentStyles(
    element: BaseOxmlElement,
    parent: ProvidesXmlPart | None = None,
)

Bases: ElementProxy

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.

Source code in src/docx/shared.py 
318
319
320
def __init__(self, element: BaseOxmlElement, parent: t.ProvidesXmlPart | None = None):
    self._element = element
    self._parent = parent

default_priority property writable 

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

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

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

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

default_to_unhide_when_used

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

load_count property writable 

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.

add_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.

Source code in src/docx/styles/latent.py 
26
27
28
29
30
31
def add_latent_style(self, 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`."""
    lsdException = self._element.add_lsdException()
    lsdException.name = BabelFish.ui2internal(name)
    return _LatentStyle(lsdException)

trim 

trim() -> int

Remove every w:lsdException override; return how many went.

The bundled template carries 137 of these, one per built-in style Word might offer, and a generated document needs none of them.

A latent style is a behavior declaration for a style the document does not define: which of Word's built-ins appear in the gallery, in what order, and whether they are hidden until used. Removing one therefore changes what a user sees in Word's style list, not how the document renders — a different risk from removing a style definition, which is why this is a separate operation from Styles.remove_unused.

The defaults on the w:latentStyles element itself are left in place; they are what the overrides were overriding.

Source code in src/docx/styles/latent.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
def trim(self) -> int:
    """Remove every `w:lsdException` override; return how many went.

    The bundled template carries 137 of these, one per built-in style Word might
    offer, and a generated document needs none of them.

    A latent style is a *behavior* declaration for a style the document does not
    define: which of Word's built-ins appear in the gallery, in what order, and
    whether they are hidden until used. Removing one therefore changes what a user
    sees in Word's style list, not how the document renders — a different risk from
    removing a style definition, which is why this is a separate operation from
    :meth:`.Styles.remove_unused`.

    The defaults on the `w:latentStyles` element itself are left in place; they are
    what the overrides were overriding.
    """
    lsdExceptions = self._element.lsdException_lst
    for lsdException in lsdExceptions:
        self._element.remove(lsdException)
    return len(lsdExceptions)

_LatentStyle 

_LatentStyle(
    element: BaseOxmlElement,
    parent: ProvidesXmlPart | None = None,
)

Bases: ElementProxy

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.

Source code in src/docx/shared.py 
318
319
320
def __init__(self, element: BaseOxmlElement, parent: t.ProvidesXmlPart | None = None):
    self._element = element
    self._parent = parent

hidden property writable 

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

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 property 

name

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

priority property writable 

priority

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

quick_style property writable 

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

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.

delete 

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.

Source code in src/docx/styles/latent.py 
140
141
142
143
144
145
146
147
148
149
def delete(self):
    """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|.
    """
    self._element.delete()
    self._element = None