athena-python-docx 0.34.0__tar.gz → 0.35.0__tar.gz

{athena_python_docx-0.34.0 → athena_python_docx-0.35.0}/AGENTS.md

@@ -1255,31 +1255,33 @@ architecture or a DOCX Studio constraint:
   exported file. Against a docx-studio that predates `fieldRun` reads, a
   field reads as no runs and no text, as before (`tests/test_field_runs.py`).
 
-- **A run that holds a page number block refuses two whole-run formats.** A
-  page number block (`w:pgNum`) reads as a run with no text, and a run that
-  holds text and blocks (or two blocks) reads as python-docx's one run. A
-  whole-run format (`run.bold = True`, `run.font.*`, a format of a block's
-  run) formats every piece of it, as python-docx formats its `w:rPr`. Two
-  formats are refused while a block of the run has a node. A link's block
-  has none, and takes both as the run's text does. The first is a tracked
-  format (`track_revisions`), which raises `DocxError` naming
-  `TrackedChangesUnsupported`, because docx-studio records no tracked change
-  on a block. The second is the on/off properties no editor mark holds
+- **A run that holds a page number block refuses a tracked whole-run format
+  and two text writes.** A page number block (`w:pgNum`) reads as a run with
+  no text, and a run that holds text and blocks (or two blocks) reads as
+  python-docx's one run. A whole-run format (`run.bold = True`, `run.font.*`,
+  a format of a block's run) formats every piece of it, as python-docx formats
+  its `w:rPr`, the on/off properties no editor mark holds included
   (`font.no_proof`, `snap_to_grid`, `web_hidden`, `spec_vanish`, `math`,
-  `complex_script`, `cs_bold`, `cs_italic`), in any format that reaches a
-  block, which warn (`DocxUnsupportedCommandWarning`), because a block keeps
-  its source run's.
-  python-docx writes both into the run's `w:rPr`. Made on the run's text
-  alone, either would leave the run half formatted and split it in two
+  `complex_script`, `cs_bold`, `cs_italic`). A tracked format
+  (`track_revisions`) is refused while a block of the run has a node, and
+  raises `DocxError` naming `TrackedChangesUnsupported`, because docx-studio
+  records no tracked change on a block. A link's block has none, and takes it
+  as the run's text does. In a document imported before docx-studio gave a
+  block's node its run's properties (in October 2026, between the release that
+  first read `w:pgNum` and the next), and in a comment, the on/off properties
+  are refused too, in any format that reaches a block, and warn
+  (`DocxUnsupportedCommandWarning`), because there a block keeps its source
+  run's. python-docx writes both into the run's `w:rPr`. Made on the run's
+  text alone, either would leave the run half formatted and split it in two
   (`DOCX_STUDIO_LIMITATIONS.md` § 27). `run.text = …` and `clear()` replace
   all of such a run, its blocks too, as upstream does: the SDK declares
   `wholeRunPieces`, and renumbers the field runs it holds of the paragraph,
   since each field after the blocks is numbered one lower for each
   (`tests/test_run_page_number_blocks.py`). Two text writes are refused and
-  warn (`DocxUnsupportedCommandWarning`), where upstream replaces the
-  blocks: text written to a block's run (a run of blocks alone, or a lone
-  block), which would move the text offsets the SDK keeps, and the text of a
-  link's run that holds a block, which has no node to take out.
+  warn (`DocxUnsupportedCommandWarning`), where upstream replaces the blocks:
+  text written to a block's run (a run of blocks alone, or a lone block),
+  which would move the text offsets the SDK keeps, and the text of a link's
+  run that holds a block, which has no node to take out.
 
 - **`Font.name = "…"` also clears the theme fonts of the two slots it
   sets.** python-docx writes the name to `w:rFonts`' `w:ascii` and `w:hAnsi`

{athena_python_docx-0.34.0 → athena_python_docx-0.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.34.0
+Version: 0.35.0
 Summary: Drop-in replacement for python-docx that connects to Athena's DOCX Studio collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>

{athena_python_docx-0.34.0 → athena_python_docx-0.35.0}/docx/__init__.py

@@ -6,7 +6,7 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.34.0"
+__version__ = "0.35.0"
 
 from docx.api import Document
 from docx._buffer import discard_all, flush_all

{athena_python_docx-0.34.0 → athena_python_docx-0.35.0}/docx/_buffer.py

@@ -43,6 +43,7 @@ from docx._execution import (
     is_stale_execution,
 )
 from docx._timeouts import timeout_for_commands
+from docx._xml_text import check_command_text
 from docx.commands import (
     Command,
     GetNodeById,
@@ -596,6 +597,11 @@ class CommandBuffer:
         proxy's ``_node_id`` in-place.
         """
         self.ensure_usable()
+        # A write whose text holds a character XML does not allow raises
+        # python-docx's ValueError here, before anything is sent: every command
+        # comes through, a path-proxy op's and a direct ``send_command``'s.
+        if not is_query(cmd):
+            check_command_text(cmd.to_dict())
 
         # A read of the node the last command read, with nothing sent or
         # buffered since and within READ_REUSE_SECONDS of it, answers from

athena_python_docx-0.35.0/docx/_proxy.py

@@ -0,0 +1,85 @@
+"""python-docx's ``ElementProxy`` equality, for the SDK's proxies of the
+objects python-docx wraps in one: styles, the styles part, settings, a
+paragraph's or a style's paragraph format, a run's or a style's font."""
+
+from __future__ import annotations
+
+import weakref
+from typing import Any
+
+
+class ElementProxyEquality:
+    """python-docx's ``docx.shared.ElementProxy`` equality: two proxies of the
+    same element are equal (``paragraph.style == doc.styles["Heading 1"]``),
+    a proxy of another element or anything else is not, and, as python-docx
+    defines ``__eq__`` there, a proxy is not hashable.
+
+    The element is :meth:`_proxy_element`: the docx-studio object it stands
+    for, named as the XML element python-docx's proxy wraps (a style's
+    ``w:style``, so a style, its font and its paragraph format are equal, as
+    they are in python-docx).
+    """
+
+    __slots__ = ()
+
+    def _proxy_element(self) -> tuple[object, ...]:
+        raise NotImplementedError
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ElementProxyEquality):
+            return False
+        return self._proxy_element() == other._proxy_element()
+
+    def __ne__(self, other: object) -> bool:
+        return not self.__eq__(other)
+
+    __hash__ = None  # type: ignore[assignment]
+
+
+# Session -> style id -> the style definition that id names in the session's
+# document now (:func:`style_definition`). Held weakly by session, as the
+# run order is (``docx._run_order``); the document stores none of it.
+_STYLE_DEFINITIONS: "weakref.WeakKeyDictionary[Any, dict[str, object]]" = weakref.WeakKeyDictionary()
+
+
+def _definitions(session: object) -> "dict[str, object] | None":
+    if session is None:
+        return None
+    try:
+        return _STYLE_DEFINITIONS.setdefault(session, {})
+    except TypeError:  # a session that takes no weak reference
+        return None
+
+
+def style_definition(session: object, style_id: str) -> object:
+    """The style definition (its ``w:style`` element) that ``style_id`` names in
+    ``session``'s document now, which a style proxy holds from its first read:
+    the same one after a rename (:func:`style_renamed`), another for a style
+    made after one of that id was deleted (:func:`style_deleted`)."""
+    definitions = _definitions(session)
+    if definitions is None:
+        return ("w:styleId", style_id)
+    return definitions.setdefault(style_id, object())
+
+
+def style_renamed(session: object, old: str, new: str) -> None:
+    """``style_id`` renamed the definition ``old`` named to ``new``."""
+    definitions = _definitions(session)
+    if definitions is not None:
+        definitions[new] = definitions.pop(old, None) or object()
+
+
+def style_deleted(session: object, style_id: str) -> None:
+    """``delete`` removed the definition ``style_id`` named."""
+    definitions = _definitions(session)
+    if definitions is not None:
+        definitions.pop(style_id, None)
+
+
+def style_element(style: object) -> tuple[object, ...]:
+    """The ``w:style`` element of ``style`` (a ``BaseStyle``): its document and
+    its definition (:func:`style_definition`), which a rename keeps."""
+    definition = getattr(style, "_definition", None)
+    if definition is None:
+        definition = ("w:styleId", getattr(style, "_style_id", None))
+    return ("w:style", getattr(style, "_session", None), definition)

athena_python_docx-0.35.0/docx/_xml_text.py

@@ -0,0 +1,46 @@
+"""What lxml refuses in XML text and attribute values, where python-docx meets it.
+
+python-docx writes every string it is given into an lxml element, and lxml
+raises ``ValueError`` for a character XML does not allow: C0 controls other
+than tab, LF and CR, the noncharacters U+FFFE / U+FFFF, and lone surrogates.
+So ``run.text = "a\\x0bb"`` (a vertical tab, Word's line break in its object
+model) raises there, before anything is written. docx-studio would take the
+text, and a part holding it is one Word refuses to open.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+XML_INCOMPATIBLE_CHARACTER = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\ud800-\udfff￾￿]")
+XML_INCOMPATIBLE_MESSAGE = (
+    "All strings must be XML compatible: Unicode or ASCII, no NULL bytes or control characters"
+)
+
+
+def check_xml_compatible(value: Any) -> None:
+    """Raise python-docx's ``ValueError`` (lxml's) when a string in ``value``,
+    a command's params (strings, lists, dicts), holds a character XML does
+    not allow."""
+    if isinstance(value, str):
+        if XML_INCOMPATIBLE_CHARACTER.search(value):
+            raise ValueError(XML_INCOMPATIBLE_MESSAGE)
+    elif isinstance(value, dict):
+        for item in value.values():
+            check_xml_compatible(item)
+    elif isinstance(value, (list, tuple)):
+        for item in value:
+            check_xml_compatible(item)
+
+
+#: Fields of a write that name text to find, not text to write
+#: (``FindReplace.pattern``): a pattern may match what a document already holds.
+_SEARCH_FIELDS: frozenset[str] = frozenset({"pattern"})
+
+
+def check_command_text(command: dict[str, Any]) -> None:
+    """:func:`check_xml_compatible` over a write's wire fields (a command's
+    ``to_dict()``), but for the text it searches for (``_SEARCH_FIELDS``)."""
+    check_xml_compatible({key: value for key, value in command.items() if key not in _SEARCH_FIELDS})
+

{athena_python_docx-0.34.0 → athena_python_docx-0.35.0}/docx/blkcntnr.py

@@ -9,6 +9,8 @@ docx-studio; ``isinstance(cell, BlockItemContainer)`` holds as in python-docx.
 
 from __future__ import annotations
 
+from docx._xml_text import check_xml_compatible
+
 from typing import TYPE_CHECKING, Iterator
 
 if TYPE_CHECKING:
@@ -30,6 +32,7 @@ class BlockItemContainer:
         self, text: str = "", style: "str | ParagraphStyle | None" = None
     ) -> "Paragraph":
         """Return paragraph newly added to the end of the content in this container."""
+        check_xml_compatible(text)
         raise NotImplementedError(f"{type(self).__name__} holds no paragraphs")
 
     def add_table(self, rows: int, cols: int, width: "Length") -> "Table":

{athena_python_docx-0.34.0 → athena_python_docx-0.35.0}/docx/document.py

@@ -14,6 +14,8 @@ Phase 1 supported methods:
 
 from __future__ import annotations
 
+from docx._xml_text import check_xml_compatible
+
 import base64
 import os
 import re
@@ -1789,6 +1791,7 @@ class Document:
         Returns:
             The newly-created Paragraph.
         """
+        check_xml_compatible(text)
         from docx.styles._table import paragraph_style_name
         from docx.styles.style import ParagraphStyle
         from docx.text.paragraph import Paragraph
@@ -2033,6 +2036,7 @@ class Document:
         level: int = 1,
     ) -> "Paragraph":
         """Append a heading via DOCX Studio's canonical `doc.create.heading`."""
+        check_xml_compatible(text)
         from docx.text.paragraph import Paragraph
 
         self._ensure_open()

{athena_python_docx-0.34.0 → athena_python_docx-0.35.0}/docx/section.py

@@ -11,6 +11,8 @@ or twip values depending on the op).
 
 from __future__ import annotations
 
+from docx._xml_text import check_xml_compatible
+
 import warnings
 from collections.abc import Sequence
 from typing import TYPE_CHECKING
@@ -986,6 +988,7 @@ class _HeaderFooter(BlockItemContainer):
         server turns tabs and line breaks in ``text`` into ``<w:tab/>`` /
         ``<w:br/>``, as python-docx's ``Run.text`` does.
         """
+        check_xml_compatible(text)
         from docx.styles.style import ParagraphStyle
 
         style_str: str | None

{athena_python_docx-0.34.0 → athena_python_docx-0.35.0}/docx/settings.py

@@ -21,6 +21,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from docx._batching import run_sync
+from docx._proxy import ElementProxyEquality
 
 if TYPE_CHECKING:
     from docx.client import Session
@@ -38,7 +39,7 @@ class PendingSettingsMutationWarning(UserWarning):
     """
 
 
-class Settings:
+class Settings(ElementProxyEquality):
     def __init__(
         self,
         *,
@@ -49,12 +50,16 @@ class Settings:
         self._document: "Document | None" = document
         self._odd_and_even_pages_header_footer: bool = False
 
+    def _proxy_element(self) -> tuple[object, ...]:
+        return ("w:settings", self._session)
+
     @property
     def odd_and_even_pages_header_footer(self) -> bool:
         """The document's ``w:evenAndOddHeaders`` in ``word/settings.xml``, as
         python-docx reads it (False when absent or off). A docx-studio that
         does not report it (``Info`` without ``settings``) gives the value this
         proxy last set."""
+        self._open()
         info: object = run_sync(self._session.doc.info({"includeSettings": True}))
         settings: object = info.get("settings") if isinstance(info, dict) else None
         reported: object = settings.get("evenAndOddHeaders") if isinstance(settings, dict) else None
@@ -65,6 +70,7 @@ class Settings:
     @odd_and_even_pages_header_footer.setter
     def odd_and_even_pages_header_footer(self, value: bool) -> None:
         enabled = bool(value)
+        self._open()
         run_sync(
             self._session.doc.sections.set_odd_even_headers_footers(
                 {"enabled": enabled},
@@ -72,6 +78,14 @@ class Settings:
         )
         self._odd_and_even_pages_header_footer = enabled
 
+    def _open(self) -> None:
+        """Open the document's session before a read or write of it, as every
+        member of ``Document`` that touches it does (``Document.create()``
+        returns before it opens). ``track_revisions`` needs no session: it
+        stays a local flag until one opens."""
+        if self._document is not None:
+            self._document._ensure_open()
+
     # --- Track changes alias (Athena: forwards to Document.track_revisions) ---
 
     @property

{athena_python_docx-0.34.0 → athena_python_docx-0.35.0}/docx/styles/style.py

@@ -33,6 +33,13 @@ from typing import TYPE_CHECKING, Any, Callable
 
 from docx._batching import run_sync
 from docx._buffer import writes_unapplied
+from docx._proxy import (
+    ElementProxyEquality,
+    style_definition,
+    style_deleted,
+    style_element,
+    style_renamed,
+)
 from docx.enum.style import WD_STYLE_TYPE
 from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_LINE_SPACING, WD_TAB_ALIGNMENT, WD_TAB_LEADER
 from docx.shared import Emu, Length, Pt, Twips
@@ -151,7 +158,7 @@ def _style_by_id(session: Any, style_id: object) -> "BaseStyle | None":
     return _style_of_record(record, session) if record is not None else None
 
 
-class BaseStyle:
+class BaseStyle(ElementProxyEquality):
     """Base for all style kinds. Matches python-docx.styles.style.BaseStyle."""
 
     def __init__(
@@ -168,6 +175,8 @@ class BaseStyle:
         self._style_id: str = style_id or name
         self._type: "WD_STYLE_TYPE" = style_type
         self._session: "Session | None" = session
+        # The definition this proxy stands for, which a rename keeps (equality).
+        self._definition: object = style_definition(session, self._style_id)
         # Writes docx-studio does not take, kept for read-back (see module docstring).
         self._overrides: dict[str, Any] = {}
 
@@ -215,6 +224,9 @@ class BaseStyle:
         self._set_metadata("name", value, name=value)
 
     # ---- style_id ----
+    def _proxy_element(self) -> tuple[object, ...]:
+        return style_element(self)
+
     @property
     def style_id(self) -> str:
         return self._overrides.get("style_id", self._style_id)
@@ -239,6 +251,7 @@ class BaseStyle:
             and server_takes(self._session, "styleIdWrites")
         ):
             self._set_metadata("style_id", value, id=value)
+            style_renamed(self._session, self._style_id, value)
             self._style_id = value
             self._overrides.pop("style_id", None)
             return
@@ -353,6 +366,7 @@ class BaseStyle:
             return
         # Its id as the document holds it: `style_id` may hold a value only this process set.
         run_sync(self._session.doc.styles.delete({"styleId": self._style_id, "styleType": style_type}))
+        style_deleted(self._session, self._style_id)
         forget_style_table(self._session)
 
 
@@ -638,6 +652,16 @@ _MULTIPLE_LINES: dict[WD_LINE_SPACING, int] = {
 }
 
 
+def _alignment_of_jc(jc: object) -> WD_ALIGN_PARAGRAPH | None:
+    """The member of a style's own ``w:jc``, as python-docx reads it: None for
+    none, and ``ValueError`` for a value it has no member for (``start``,
+    ``end``, ``numTab``)."""
+    if not isinstance(jc, str) or not jc:
+        return None
+    member = _ALIGNMENT_OF_JC.get(jc)
+    return member if member is not None else WD_ALIGN_PARAGRAPH.from_xml(jc)
+
+
 def _alignment_of(value: object) -> WD_ALIGN_PARAGRAPH:
     """``value`` as a ``WD_ALIGN_PARAGRAPH`` member, as ``Paragraph.alignment`` takes it."""
     if not isinstance(value, (int, str)):
@@ -675,7 +699,7 @@ def _line_rule_of(own: dict[str, Any]) -> str | None:
     return "auto" if own.get("lineSpacing") is not None else None
 
 
-class _StyleParagraphFormat:
+class _StyleParagraphFormat(ElementProxyEquality):
     """``ParagraphStyle.paragraph_format``: python-docx's ``ParagraphFormat``
     over a style's own ``w:pPr``.
 
@@ -694,6 +718,9 @@ class _StyleParagraphFormat:
     def __init__(self, style: "BaseStyle") -> None:
         self._style: "BaseStyle" = style
 
+    def _proxy_element(self) -> tuple[object, ...]:
+        return style_element(self._style)
+
     def _own(self) -> dict[str, Any] | None:
         """The style's own paragraph properties from the style table; None
         when the table carries none (an older docx-studio)."""
@@ -727,7 +754,7 @@ class _StyleParagraphFormat:
     # ---- alignment ----
     @property
     def alignment(self) -> Any:
-        return self._get("alignment", "alignment", _ALIGNMENT_OF_JC.get)
+        return self._get("alignment", "alignment", _alignment_of_jc)
 
     @alignment.setter
     def alignment(self, value: Any) -> None:
@@ -891,6 +918,13 @@ _LIVE_TAB_STOPS: "weakref.WeakKeyDictionary[Any, dict[str, weakref.WeakSet[_Styl
     weakref.WeakKeyDictionary()
 )
 
+# Why a tab stop is out of its style, as python-docx's ``w:tab`` is: taken out
+# of the ``w:tabs`` (``del``, another object of it given a new position), so a
+# new position finds no list to go back into; or in the ``w:tabs`` that
+# ``clear_all`` took out, where a new position still goes.
+_REMOVED = "removed"
+_CLEARED = "cleared"
+
 
 class _StyleTabStop:
     """One tab stop of a style's ``w:tabs``, as python-docx's ``TabStop``
@@ -912,7 +946,7 @@ class _StyleTabStop:
         self._entry: dict[str, Any] = entry
         self._owner: "_StyleTabStops | None" = owner
         self._index: int | None = index
-        self._detached = False
+        self._detached: str | None = None
         if owner is not None and index is not None:
             owner._track(self)
 
@@ -928,8 +962,9 @@ class _StyleTabStop:
     def _change(self, prop: str, entry: dict[str, Any], *, reorder: bool = False) -> None:
         if self._detached:
             # python-docx's removed w:tab takes a value (the document does
-            # not); a new position finds no w:tabs to go back into.
-            if reorder:
+            # not); a new position finds no w:tabs to go back into, but one
+            # clear_all took out goes back into the w:tabs it took out.
+            if reorder and self._detached != _CLEARED:
                 raise AttributeError("this tab stop is no longer one of the style's")
             self._entry = entry
             return
@@ -1019,10 +1054,17 @@ class _StyleTabStops:
             return
         styles.setdefault(self._style.style_id, weakref.WeakSet()).add(stop)
 
-    def _moved(self, place: Callable[[int], int | None], entries: dict[int, dict[str, Any]] | None = None) -> None:
+    def _moved(
+        self,
+        place: Callable[[int], int | None],
+        entries: dict[int, dict[str, Any]] | None = None,
+        *,
+        why: str = _REMOVED,
+    ) -> None:
         """After a write: each live tab stop of the style at its new place
         (``place`` of its old one), with its new value where ``entries`` (by
-        new place) gives one, or out of the style where ``place`` gives none."""
+        new place) gives one, or out of the style (``why``) where ``place``
+        gives none."""
         try:
             live = (_LIVE_TAB_STOPS.get(self._style._session) or {}).get(self._style.style_id)
         except TypeError:
@@ -1032,7 +1074,7 @@ class _StyleTabStops:
                 continue
             new = place(stop._index)
             if new is None:
-                stop._detached = True
+                stop._detached = why
                 continue
             stop._index = new
             if entries and new in entries:
@@ -1056,19 +1098,24 @@ class _StyleTabStops:
 
     def _replace(self, stop: "_StyleTabStop", entry: dict[str, Any], *, reorder: bool) -> None:
         """Write the style's tab stops with ``stop`` changed to ``entry``: in
-        place, or for a new position (``reorder``) taken out and inserted in
-        position order, as python-docx's ``TabStop.position`` does (a new
-        ``w:tab``, so another object of the old one is out of the style)."""
+        place, or for a new position (``reorder``) inserted where
+        ``insert_tab_in_order`` puts a new one (``stop`` still listed) and
+        taken out of its old place, as python-docx's ``TabStop.position`` does
+        (a new ``w:tab``, so another object of the old one is out of the
+        style); a list out of position order keeps its order around it."""
         stops = list(self._stops())
         at = stop._index
         if at is None or not 0 <= at < len(stops):
             raise ValueError("this tab stop is no longer one of the style's")
         changed = _StyleTabStop(entry, self)
-        del stops[at]
-        to = at
         if reorder:
-            to = next((index for index, kept in enumerate(stops) if kept.position > changed.position), len(stops))
-        stops.insert(to, changed)
+            to = next((index for index, kept in enumerate(stops) if changed.position < kept.position), len(stops))
+            stops.insert(to, changed)
+            del stops[at if at < to else at + 1]
+            to = to - 1 if at < to else to
+        else:
+            stops[at] = changed
+            to = at
         self._write(stops)
 
         def place(index: int) -> int | None:
@@ -1078,7 +1125,7 @@ class _StyleTabStops:
             return index + (index >= to)
 
         self._moved(place, {to: entry})
-        stop._detached = False
+        stop._detached = None
         stop._index = to
         stop._entry = entry
 
@@ -1127,7 +1174,7 @@ class _StyleTabStops:
         """Remove all of the style's tab stops (its ``w:tabs``), as python-docx does."""
         if self._writes():
             self._write([])
-            self._moved(lambda index: None)
+            self._moved(lambda index: None, why=_CLEARED)
             return
         _warn_unwritten(
             "ParagraphStyle.paragraph_format.tab_stops.clear_all",

{athena_python_docx-0.34.0 → athena_python_docx-0.35.0}/docx/styles/styles.py

@@ -13,6 +13,7 @@ import warnings
 from typing import TYPE_CHECKING
 
 from docx._batching import run_sync
+from docx._proxy import ElementProxyEquality
 from docx.enum.style import WD_STYLE_TYPE
 from docx.styles import BabelFish
 from docx.styles.latent import LatentStyles, PendingLatentStylesReadWarning
@@ -110,13 +111,16 @@ def _style_id_from_name(name: str) -> str:
     return _SPECIAL_STYLE_IDS.get(name, name.replace(" ", ""))
 
 
-class Styles:
+class Styles(ElementProxyEquality):
     """Collection of styles. Iterable, len, __getitem__."""
 
     def __init__(self, *, session: "Session") -> None:
         self._session: "Session" = session
         self._added: dict[str, BaseStyle] = {}
 
+    def _proxy_element(self) -> tuple[object, ...]:
+        return ("w:styles", self._session)
+
     def _all(self) -> list[BaseStyle]:
         from docx._table_styles import BUILTIN_TABLE_STYLE_IDS
         from docx.styles._table import builtin_style_id, builtin_style_name, style_table