Initial commit (Clean history)

path/to/venv/lib/python3.12/site-packages/docx/styles/__init__.py

@@ -0,0 +1,40 @@
+"""Sub-package module for docx.styles sub-package."""
+
+from __future__ import annotations
+
+from typing import Dict
+
+
+class BabelFish:
+    """Translates special-case style names from UI name (e.g. Heading 1) to
+    internal/styles.xml name (e.g. heading 1) and back."""
+
+    style_aliases = (
+        ("Caption", "caption"),
+        ("Footer", "footer"),
+        ("Header", "header"),
+        ("Heading 1", "heading 1"),
+        ("Heading 2", "heading 2"),
+        ("Heading 3", "heading 3"),
+        ("Heading 4", "heading 4"),
+        ("Heading 5", "heading 5"),
+        ("Heading 6", "heading 6"),
+        ("Heading 7", "heading 7"),
+        ("Heading 8", "heading 8"),
+        ("Heading 9", "heading 9"),
+    )
+
+    internal_style_names: Dict[str, str] = dict(style_aliases)
+    ui_style_names = {item[1]: item[0] for item in style_aliases}
+
+    @classmethod
+    def ui2internal(cls, ui_style_name: str) -> str:
+        """Return the internal style name corresponding to `ui_style_name`, such as
+        'heading 1' for 'Heading 1'."""
+        return cls.internal_style_names.get(ui_style_name, ui_style_name)
+
+    @classmethod
+    def internal2ui(cls, internal_style_name: str) -> str:
+        """Return the user interface style name corresponding to `internal_style_name`,
+        such as 'Heading 1' for 'heading 1'."""
+        return cls.ui_style_names.get(internal_style_name, internal_style_name)

path/to/venv/lib/python3.12/site-packages/docx/styles/latent.py

@@ -0,0 +1,198 @@
+"""Latent style-related objects."""
+
+from docx.shared import ElementProxy
+from docx.styles import BabelFish
+
+
+class LatentStyles(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."""
+
+    def __getitem__(self, key):
+        """Enables dictionary-style access to a latent style by name."""
+        style_name = BabelFish.ui2internal(key)
+        lsdException = self._element.get_by_name(style_name)
+        if lsdException is None:
+            raise KeyError("no latent style with name '%s'" % key)
+        return _LatentStyle(lsdException)
+
+    def __iter__(self):
+        return (_LatentStyle(ls) for ls in self._element.lsdException_lst)
+
+    def __len__(self):
+        return len(self._element.lsdException_lst)
+
+    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)
+
+    @property
+    def default_priority(self):
+        """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.
+        """
+        return self._element.defUIPriority
+
+    @default_priority.setter
+    def default_priority(self, value):
+        self._element.defUIPriority = value
+
+    @property
+    def default_to_hidden(self):
+        """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.
+        """
+        return self._element.bool_prop("defSemiHidden")
+
+    @default_to_hidden.setter
+    def default_to_hidden(self, value):
+        self._element.set_bool_prop("defSemiHidden", value)
+
+    @property
+    def default_to_locked(self):
+        """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).
+        """
+        return self._element.bool_prop("defLockedState")
+
+    @default_to_locked.setter
+    def default_to_locked(self, value):
+        self._element.set_bool_prop("defLockedState", value)
+
+    @property
+    def default_to_quick_style(self):
+        """Boolean specifying whether the default behavior for latent styles is to
+        appear in the style gallery when not hidden."""
+        return self._element.bool_prop("defQFormat")
+
+    @default_to_quick_style.setter
+    def default_to_quick_style(self, value):
+        self._element.set_bool_prop("defQFormat", value)
+
+    @property
+    def default_to_unhide_when_used(self):
+        """Boolean specifying whether the default behavior for latent styles is to be
+        unhidden when first applied to content."""
+        return self._element.bool_prop("defUnhideWhenUsed")
+
+    @default_to_unhide_when_used.setter
+    def default_to_unhide_when_used(self, value):
+        self._element.set_bool_prop("defUnhideWhenUsed", value)
+
+    @property
+    def load_count(self):
+        """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.
+        """
+        return self._element.count
+
+    @load_count.setter
+    def load_count(self, value):
+        self._element.count = value
+
+
+class _LatentStyle(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.
+    """
+
+    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
+
+    @property
+    def hidden(self):
+        """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.
+        """
+        return self._element.on_off_prop("semiHidden")
+
+    @hidden.setter
+    def hidden(self, value):
+        self._element.set_on_off_prop("semiHidden", value)
+
+    @property
+    def locked(self):
+        """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).
+        """
+        return self._element.on_off_prop("locked")
+
+    @locked.setter
+    def locked(self, value):
+        self._element.set_on_off_prop("locked", value)
+
+    @property
+    def name(self):
+        """The name of the built-in style this exception applies to."""
+        return BabelFish.internal2ui(self._element.name)
+
+    @property
+    def priority(self):
+        """The integer sort key for this latent style in the Word UI."""
+        return self._element.uiPriority
+
+    @priority.setter
+    def priority(self, value):
+        self._element.uiPriority = value
+
+    @property
+    def quick_style(self):
+        """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.
+        """
+        return self._element.on_off_prop("qFormat")
+
+    @quick_style.setter
+    def quick_style(self, value):
+        self._element.set_on_off_prop("qFormat", value)
+
+    @property
+    def unhide_when_used(self):
+        """Tri-state value specifying whether this style should have its :attr:`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.
+        """
+        return self._element.on_off_prop("unhideWhenUsed")
+
+    @unhide_when_used.setter
+    def unhide_when_used(self, value):
+        self._element.set_on_off_prop("unhideWhenUsed", value)

path/to/venv/lib/python3.12/site-packages/docx/styles/style.py

@@ -0,0 +1,254 @@
+"""Style object hierarchy."""
+
+from __future__ import annotations
+
+from typing import Type
+
+from docx.enum.style import WD_STYLE_TYPE
+from docx.oxml.styles import CT_Style
+from docx.shared import ElementProxy
+from docx.styles import BabelFish
+from docx.text.font import Font
+from docx.text.parfmt import ParagraphFormat
+
+
+def StyleFactory(style_elm: CT_Style) -> 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)
+
+
+class BaseStyle(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.
+    """
+
+    def __init__(self, style_elm: CT_Style):
+        super().__init__(style_elm)
+        self._style_elm = style_elm
+
+    @property
+    def builtin(self):
+        """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.
+        """
+        return not self._element.customStyle
+
+    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
+
+    @property
+    def hidden(self):
+        """|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 :attr:`.quick_style` must be |True|.
+        """
+        return self._element.semiHidden_val
+
+    @hidden.setter
+    def hidden(self, value):
+        self._element.semiHidden_val = value
+
+    @property
+    def locked(self):
+        """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).
+        """
+        return self._element.locked_val
+
+    @locked.setter
+    def locked(self, value):
+        self._element.locked_val = value
+
+    @property
+    def name(self):
+        """The UI name of this style."""
+        name = self._element.name_val
+        if name is None:
+            return None
+        return BabelFish.internal2ui(name)
+
+    @name.setter
+    def name(self, value):
+        self._element.name_val = value
+
+    @property
+    def priority(self):
+        """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.
+        """
+        return self._element.uiPriority_val
+
+    @priority.setter
+    def priority(self, value):
+        self._element.uiPriority_val = value
+
+    @property
+    def quick_style(self):
+        """|True| if this style should be displayed in the style gallery when
+        :attr:`.hidden` is |False|.
+
+        Read/write Boolean.
+        """
+        return self._element.qFormat_val
+
+    @quick_style.setter
+    def quick_style(self, value):
+        self._element.qFormat_val = value
+
+    @property
+    def style_id(self) -> 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.
+        """
+        return self._style_elm.styleId
+
+    @style_id.setter
+    def style_id(self, value):
+        self._element.styleId = value
+
+    @property
+    def type(self):
+        """Member of :ref:`WdStyleType` corresponding to the type of this style, e.g.
+        ``WD_STYLE_TYPE.PARAGRAPH``."""
+        type = self._style_elm.type
+        if type is None:
+            return WD_STYLE_TYPE.PARAGRAPH
+        return type
+
+    @property
+    def unhide_when_used(self):
+        """|True| if an application should make this style visible the next time it is
+        applied to content.
+
+        False otherwise. Note that |docx| does not automatically unhide a style having
+        |True| for this attribute when it is applied to content.
+        """
+        return self._element.unhideWhenUsed_val
+
+    @unhide_when_used.setter
+    def unhide_when_used(self, value):
+        self._element.unhideWhenUsed_val = value
+
+
+class CharacterStyle(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 :attr:`.font` property.
+    """
+
+    @property
+    def base_style(self):
+        """Style object this style inherits from or |None| if this style is not based on
+        another style."""
+        base_style = self._element.base_style
+        if base_style is None:
+            return None
+        return StyleFactory(base_style)
+
+    @base_style.setter
+    def base_style(self, style):
+        style_id = style.style_id if style is not None else None
+        self._element.basedOn_val = style_id
+
+    @property
+    def font(self):
+        """The |Font| object providing access to the character formatting properties for
+        this style, such as font name and size."""
+        return Font(self._element)
+
+
+# -- just in case someone uses the old name in an extension function --
+_CharacterStyle = CharacterStyle
+
+
+class ParagraphStyle(CharacterStyle):
+    """A paragraph style.
+
+    A paragraph style provides both character formatting and paragraph formatting such
+    as indentation and line-spacing.
+    """
+
+    def __repr__(self):
+        return "_ParagraphStyle('%s') id: %s" % (self.name, id(self))
+
+    @property
+    def next_paragraph_style(self):
+        """|_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.
+        """
+        next_style_elm = self._element.next_style
+        if next_style_elm is None:
+            return self
+        if next_style_elm.type != WD_STYLE_TYPE.PARAGRAPH:
+            return self
+        return StyleFactory(next_style_elm)
+
+    @next_paragraph_style.setter
+    def next_paragraph_style(self, style):
+        if style is None or style.style_id == self.style_id:
+            self._element._remove_next()
+        else:
+            self._element.get_or_add_next().val = style.style_id
+
+    @property
+    def paragraph_format(self):
+        """The |ParagraphFormat| object providing access to the paragraph formatting
+        properties for this style such as indentation."""
+        return ParagraphFormat(self._element)
+
+
+# -- just in case someone uses the old name in an extension function --
+_ParagraphStyle = ParagraphStyle
+
+
+class _TableStyle(ParagraphStyle):
+    """A table style.
+
+    A table style provides character and paragraph formatting for its contents as well
+    as special table formatting properties.
+    """
+
+    def __repr__(self):
+        return "_TableStyle('%s') id: %s" % (self.name, id(self))
+
+
+class _NumberingStyle(BaseStyle):
+    """A numbering style.
+
+    Not yet implemented.
+    """

path/to/venv/lib/python3.12/site-packages/docx/styles/styles.py

@@ -0,0 +1,136 @@
+"""Styles object, container for all objects in the styles part."""
+
+from __future__ import annotations
+
+from warnings import warn
+
+from docx.enum.style import WD_STYLE_TYPE
+from docx.oxml.styles import CT_Styles
+from docx.shared import ElementProxy
+from docx.styles import BabelFish
+from docx.styles.latent import LatentStyles
+from docx.styles.style import BaseStyle, StyleFactory
+
+
+class Styles(ElementProxy):
+    """Provides access to the styles defined in a document.
+
+    Accessed using the :attr:`.Document.styles` property. Supports ``len()``, iteration,
+    and dictionary-style access by style name.
+    """
+
+    def __init__(self, styles: CT_Styles):
+        super().__init__(styles)
+        self._element = styles
+
+    def __contains__(self, name):
+        """Enables `in` operator on style name."""
+        internal_name = BabelFish.ui2internal(name)
+        return any(style.name_val == internal_name for style in self._element.style_lst)
+
+    def __getitem__(self, key: str):
+        """Enables dictionary-style access by UI name.
+
+        Lookup by style id is deprecated, triggers a warning, and will be removed in a
+        near-future release.
+        """
+        style_elm = self._element.get_by_name(BabelFish.ui2internal(key))
+        if style_elm is not None:
+            return StyleFactory(style_elm)
+
+        style_elm = self._element.get_by_id(key)
+        if style_elm is not None:
+            msg = "style lookup by style_id is deprecated. Use style name as key instead."
+            warn(msg, UserWarning, stacklevel=2)
+            return StyleFactory(style_elm)
+
+        raise KeyError("no style with name '%s'" % key)
+
+    def __iter__(self):
+        return (StyleFactory(style) for style in self._element.style_lst)
+
+    def __len__(self):
+        return len(self._element.style_lst)
+
+    def add_style(self, 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.
+        """
+        style_name = BabelFish.ui2internal(name)
+        if style_name in self:
+            raise ValueError("document already contains style '%s'" % name)
+        style = self._element.add_style_of_type(style_name, style_type, builtin)
+        return StyleFactory(style)
+
+    def default(self, style_type: WD_STYLE_TYPE):
+        """Return the default style for `style_type` or |None| if no default is defined
+        for that type (not common)."""
+        style = self._element.default_for(style_type)
+        if style is None:
+            return None
+        return StyleFactory(style)
+
+    def get_by_id(self, style_id: str | None, style_type: WD_STYLE_TYPE):
+        """Return the style of `style_type` matching `style_id`.
+
+        Returns the default for `style_type` if `style_id` is not found or is |None|, or
+        if the style having `style_id` is not of `style_type`.
+        """
+        if style_id is None:
+            return self.default(style_type)
+        return self._get_by_id(style_id, style_type)
+
+    def get_style_id(self, style_or_name, style_type):
+        """Return the id of the style corresponding to `style_or_name`, or |None| if
+        `style_or_name` is |None|.
+
+        If `style_or_name` is not a style object, the style is looked up using
+        `style_or_name` as a style name, raising |ValueError| if no style with that name
+        is defined. Raises |ValueError| if the target style is not of `style_type`.
+        """
+        if style_or_name is None:
+            return None
+        elif isinstance(style_or_name, BaseStyle):
+            return self._get_style_id_from_style(style_or_name, style_type)
+        else:
+            return self._get_style_id_from_name(style_or_name, style_type)
+
+    @property
+    def latent_styles(self):
+        """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."""
+        return LatentStyles(self._element.get_or_add_latentStyles())
+
+    def _get_by_id(self, style_id: str | None, style_type: WD_STYLE_TYPE):
+        """Return the style of `style_type` matching `style_id`.
+
+        Returns the default for `style_type` if `style_id` is not found or if the style
+        having `style_id` is not of `style_type`.
+        """
+        style = self._element.get_by_id(style_id) if style_id else None
+        if style is None or style.type != style_type:
+            return self.default(style_type)
+        return StyleFactory(style)
+
+    def _get_style_id_from_name(self, style_name: str, style_type: WD_STYLE_TYPE) -> str | None:
+        """Return the id of the style of `style_type` corresponding to `style_name`.
+
+        Returns |None| if that style is the default style for `style_type`. Raises
+        |ValueError| if the named style is not found in the document or does not match
+        `style_type`.
+        """
+        return self._get_style_id_from_style(self[style_name], style_type)
+
+    def _get_style_id_from_style(self, style: BaseStyle, style_type: WD_STYLE_TYPE) -> str | None:
+        """Id of `style`, or |None| if it is the default style of `style_type`.
+
+        Raises |ValueError| if style is not of `style_type`.
+        """
+        if style.type != style_type:
+            raise ValueError("assigned style is type %s, need type %s" % (style.type, style_type))
+        if style == self.default(style_type):
+            return None
+        return style.style_id