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

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

@@ -121,6 +121,21 @@ pinned by focused tests and documented in
   `horz_dpi`, `width`, `scaled_dimensions`, …). A picture in a table cell or
   a header has no id to read its image by, so `.image` raises `ValueError`;
   an older docx-studio does not report pictures, so they are not runs there.
+  `Run.add_picture` puts the picture in that run, as python-docx appends the
+  `w:drawing` to its `w:r`: after what the run holds, and text `add_text`
+  adds goes after it. Against a docx-studio that reports
+  `capabilities.pictureRuns`, `CreateImage` carries `runEdge: "append"` (the
+  run's identity as `add_text` names it), the run's record holds the picture
+  (`pictureRun`), and the run reads as one run whose pictures stand at their
+  places in its text (`pictures`), so `iter_inner_content()` yields its text
+  and each `Drawing` in order (with Word's rendered page breaks where the read
+  places them among the pictures, `afterPictures`), a whole-run format takes
+  its pictures too, and `run.text = ...` takes every one of them out
+  (`wholeRun`). A picture's run (no text) formats its picture at once, named
+  by its identity (`laterRuns`), so `r = p.add_run(); r.bold = True;
+  r.add_picture(img)` writes the bold `w:rPr` beside the `w:drawing`. An older
+  docx-studio puts the picture in a run of its own (`tests/test_drawing_image.py`,
+  battery `ab_probe/picture_runs.py`).
 - **A run holding only a page or column break yields `""` from
   `Run.iter_inner_content()`,** as python-docx reads a `w:br` of type `page`
   or `column` as empty text; an empty run (a comment reference's) yields
@@ -1255,31 +1270,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.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.34.0
+Version: 0.36.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.36.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.36.0"
 
 from docx.api import Document
 from docx._buffer import discard_all, flush_all

{athena_python_docx-0.34.0 → athena_python_docx-0.36.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.36.0/docx/_proxy.py

@@ -0,0 +1,109 @@
+"""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, tab
+stops and the latent styles."""
+
+from __future__ import annotations
+
+import weakref
+from collections.abc import Iterator
+from typing import Any, Generic, TypeVar
+
+_T = TypeVar("_T")
+
+
+class IdentityWeakSet(Generic[_T]):
+    """A set of objects held weakly, by identity: a ``weakref.WeakSet`` hashes
+    its members, and a proxy that compares by its element
+    (:class:`ElementProxyEquality`) is not hashable, as in python-docx."""
+
+    __slots__ = ("_members",)
+
+    def __init__(self) -> None:
+        self._members: "weakref.WeakValueDictionary[int, _T]" = weakref.WeakValueDictionary()
+
+    def add(self, item: _T) -> None:
+        self._members[id(item)] = item
+
+    def __iter__(self) -> Iterator[_T]:
+        return iter(list(self._members.values()))
+
+    def __len__(self) -> int:
+        return len(self._members)
+
+
+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.36.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.36.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.36.0}/docx/commands.py

@@ -140,6 +140,10 @@ class CreateImage(Command):
     at: dict[str, Any]
     client_node_id: str | None = None
     run: dict[str, Any] | None = None
+    # ``"append"`` (``Run.add_picture`` against a docx-studio that reports
+    # ``capabilities.pictureRuns``): the picture ends the run that ends at the
+    # anchor's offset, in that run's ``w:r``, as python-docx appends it.
+    run_edge: str | None = None
 
 
 @dataclass

{athena_python_docx-0.34.0 → athena_python_docx-0.36.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.36.0}/docx/oxml/__init__.py

@@ -92,6 +92,7 @@ _XML_ELEMENT_ATTRS: frozenset[str] = frozenset(
         "_tc",         # _Cell._tc
         "_tbl",        # Table._tbl
         "_tr",         # _Row._tr
+        "_t",          # _Text._t (the ``w:t`` Run.add_text added)
         "element",     # Run.element / Paragraph.element / Document.element
         "_element",    # private alias used by some python-docx forks
     },

{athena_python_docx-0.34.0 → athena_python_docx-0.36.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.36.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.36.0}/docx/styles/latent.py

@@ -23,6 +23,7 @@ import warnings
 import weakref
 from typing import TYPE_CHECKING, Any, Iterator
 
+from docx._proxy import ElementProxyEquality, IdentityWeakSet
 from docx.styles import BabelFish
 
 if TYPE_CHECKING:
@@ -52,12 +53,12 @@ _XML_INCOMPATIBLE_MESSAGE = (
 # Session -> every live ``_LatentStyle``, read or added: deleting one moves the
 # others of its name after it up one place (:func:`_removed`), as python-docx's
 # are elements a deletion elsewhere does not move. The sets hold them weakly.
-_LIVE: "weakref.WeakKeyDictionary[Any, weakref.WeakSet[_LatentStyle]]" = weakref.WeakKeyDictionary()
+_LIVE: "weakref.WeakKeyDictionary[Any, IdentityWeakSet[_LatentStyle]]" = weakref.WeakKeyDictionary()
 
 
 def _track(latent_style: "_LatentStyle") -> None:
     try:
-        _LIVE.setdefault(latent_style._session, weakref.WeakSet()).add(latent_style)
+        _LIVE.setdefault(latent_style._session, IdentityWeakSet()).add(latent_style)
     except TypeError:  # no session, or one that takes no weak reference
         return
 
@@ -67,6 +68,7 @@ def _removed(deleted: "_LatentStyle", name: Any) -> None:
     that name after it move up one place, and another object of the same
     exception is out of the document, writing nothing to it, as python-docx's
     removed element is."""
+    deleted._element = removed = object()
     try:
         live = _LIVE.get(deleted._session)
     except TypeError:
@@ -78,6 +80,7 @@ def _removed(deleted: "_LatentStyle", name: Any) -> None:
             continue
         if other._occurrence == deleted._occurrence:
             other._detached = True
+            other._element = removed
         elif other._occurrence > deleted._occurrence:
             other._occurrence -= 1
 
@@ -140,13 +143,17 @@ def _int(text: object) -> int | None:
         return None
 
 
-class LatentStyles:
+class LatentStyles(ElementProxyEquality):
     """The default behaviors for latent styles in this document, and the
     |_LatentStyle| objects that override them for a named latent style."""
 
     def __init__(self, *, session: "Session | None" = None) -> None:
         self._session: "Session | None" = session
 
+    def _proxy_element(self) -> tuple[object, ...]:
+        # python-docx's LatentStyles wraps the styles part's w:latentStyles.
+        return ("w:latentStyles", self._session)
+
     def _read(self, prop: str | None) -> dict[str, Any]:
         """The latent styles docx-studio reports; a read of ``prop`` from one
         that reports none warns (iterating, an empty collection, does not)."""
@@ -246,7 +253,7 @@ class LatentStyles:
         self._set_default("load_count", "count", None if value is None else int(value))
 
 
-class _LatentStyle:
+class _LatentStyle(ElementProxyEquality):
     """A ``w:lsdException``: display behaviors for a built-in style the
     document does not define yet, overriding the |LatentStyles| defaults."""
 
@@ -260,8 +267,18 @@ class _LatentStyle:
         #: Removed through another object of the same exception: like
         #: python-docx's element out of the part, it writes nothing to the document.
         self._detached = False
+        #: The exception it held once removed, which its other objects hold too.
+        self._element: object | None = None
         _track(self)
 
+    def _proxy_element(self) -> tuple[object, ...]:
+        # python-docx's _LatentStyle wraps its w:lsdException: the exception
+        # of its name at its place among them, or, removed, that exception, as
+        # its other objects are.
+        if self._detached or self._exception is None:
+            return ("w:lsdException", self._element if self._element is not None else id(self))
+        return ("w:lsdException", self._session, self._exception.get("name"), self._occurrence)
+
     def _target(self) -> dict[str, Any]:
         """The exception's address in ``EditLatentStyles``."""
         name = self._exception.get("name")