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

{athena_python_docx-0.35.0 → athena_python_docx-0.37.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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.35.0
+Version: 0.37.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.35.0 → athena_python_docx-0.37.0}/docx/__init__.py

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

{athena_python_docx-0.35.0 → athena_python_docx-0.37.0}/docx/_proxy.py

@@ -1,11 +1,35 @@
 """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."""
+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 typing import Any
+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:

{athena_python_docx-0.35.0 → athena_python_docx-0.37.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
@@ -561,10 +565,17 @@ class SetSectionLinkToPrevious(Command):
 
 @dataclass
 class TablesInsertRow(Command):
+    """``grid_row`` is python-docx's ``Table.add_row()``: the row goes after
+    the table's last one, with a cell for each grid column as wide as the
+    column, holding one empty paragraph, and nothing of the rows above.
+    Without it, the row is Word's Insert Row next to ``row_index``. A
+    docx-studio that predates the field ignores it."""
+
     node_id: str
     row_index: int
     position: str  # "above" | "below"
     count: int = 1
+    grid_row: bool | None = None
 
 
 @dataclass

{athena_python_docx-0.35.0 → athena_python_docx-0.37.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.35.0 → athena_python_docx-0.37.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")

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

@@ -35,6 +35,7 @@ from docx._batching import run_sync
 from docx._buffer import writes_unapplied
 from docx._proxy import (
     ElementProxyEquality,
+    IdentityWeakSet,
     style_definition,
     style_deleted,
     style_element,
@@ -910,11 +911,13 @@ class _StyleParagraphFormat(ElementProxyEquality):
 
 _TAB_STOPS_REASON = "does not write this style's tab stops: it predates styleTabStops, or does not write the style's formatting"
 
-# Session -> style id -> every live tab stop of that style, read or added: a
-# write moves the others to their new places in the style's list
-# (``_StyleTabStops._moved``), as python-docx's are elements that a change to
-# another does not move. The sets hold them weakly.
-_LIVE_TAB_STOPS: "weakref.WeakKeyDictionary[Any, dict[str, weakref.WeakSet[_StyleTabStop]]]" = (
+# Session -> style definition (``style_element``) -> every live tab stop of
+# that style, read or added: a write moves the others to their new places in
+# the style's list (``_StyleTabStops._moved``), as python-docx's are elements
+# that a change to another does not move. By the definition, not the id: a
+# renamed style keeps its stops, and one made after a style of its id was
+# deleted holds none of the deleted one's. The sets hold them weakly.
+_LIVE_TAB_STOPS: "weakref.WeakKeyDictionary[Any, dict[tuple[object, ...], IdentityWeakSet[_StyleTabStop]]]" = (
     weakref.WeakKeyDictionary()
 )
 
@@ -926,7 +929,7 @@ _REMOVED = "removed"
 _CLEARED = "cleared"
 
 
-class _StyleTabStop:
+class _StyleTabStop(ElementProxyEquality):
     """One tab stop of a style's ``w:tabs``, as python-docx's ``TabStop``
     reads it: ``position`` a ``Length``, ``alignment`` a
     ``WD_TAB_ALIGNMENT`` (a cleared tab's is ``CLEAR``), ``leader`` a
@@ -938,7 +941,7 @@ class _StyleTabStop:
     to another tab stop moves, as python-docx's ``w:tab`` element stays itself;
     one the style no longer holds writes nothing, as a removed element."""
 
-    __slots__ = ("__weakref__", "_detached", "_entry", "_index", "_owner")
+    __slots__ = ("__weakref__", "_detached", "_element", "_entry", "_index", "_owner")
 
     def __init__(
         self, entry: dict[str, Any], owner: "_StyleTabStops | None" = None, index: int | None = None
@@ -947,9 +950,19 @@ class _StyleTabStop:
         self._owner: "_StyleTabStops | None" = owner
         self._index: int | None = index
         self._detached: str | None = None
+        # The w:tab it held once out of the style, which its other objects hold too.
+        self._element: object | None = None
         if owner is not None and index is not None:
             owner._track(self)
 
+    def _proxy_element(self) -> tuple[object, ...]:
+        # python-docx's TabStop wraps its w:tab: a stop at its place in the
+        # style's list is that w:tab; one out of the style is the w:tab taken
+        # out, as are its other objects.
+        if self._owner is not None and self._index is not None and not self._detached:
+            return ("w:tab", *style_element(self._owner._style), self._index)
+        return ("w:tab", self._element if self._element is not None else id(self))
+
     def _wire(self) -> dict[str, Any]:
         """This tab stop as ``SetStyleFormatting``'s ``tabStops`` takes it."""
         leader = self._entry.get("leader")
@@ -1010,7 +1023,7 @@ class _StyleTabStop:
         )
 
 
-class _StyleTabStops:
+class _StyleTabStops(ElementProxyEquality):
     """``ParagraphStyle.paragraph_format.tab_stops``: python-docx's
     ``TabStops`` over the style's own ``w:tabs``.
 
@@ -1030,6 +1043,10 @@ class _StyleTabStops:
     def __init__(self, style: "BaseStyle") -> None:
         self._style: "BaseStyle" = style
 
+    def _proxy_element(self) -> tuple[object, ...]:
+        # python-docx's TabStops wraps the style's w:pPr (its paragraph format wraps the w:style).
+        return ("w:pPr", *style_element(self._style))
+
     def _stashed(self) -> list:
         kept = self._style._overrides
         if "parfmt.tab_stops" not in kept:
@@ -1052,7 +1069,7 @@ class _StyleTabStops:
             styles = _LIVE_TAB_STOPS.setdefault(self._style._session, {})
         except TypeError:  # no session, or one that takes no weak reference
             return
-        styles.setdefault(self._style.style_id, weakref.WeakSet()).add(stop)
+        styles.setdefault(style_element(self._style), IdentityWeakSet()).add(stop)
 
     def _moved(
         self,
@@ -1066,15 +1083,17 @@ class _StyleTabStops:
         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)
+            live = (_LIVE_TAB_STOPS.get(self._style._session) or {}).get(style_element(self._style))
         except TypeError:
             return
+        gone: dict[int, object] = {}
         for stop in list(live or ()):
             if stop._detached or stop._index is None:
                 continue
             new = place(stop._index)
             if new is None:
                 stop._detached = why
+                stop._element = gone.setdefault(stop._index, object())
                 continue
             stop._index = new
             if entries and new in entries:

{athena_python_docx-0.35.0 → athena_python_docx-0.37.0}/docx/table.py

@@ -321,6 +321,7 @@ if TYPE_CHECKING:
         WD_TABLE_ALIGNMENT,
         WD_TABLE_DIRECTION,
     )
+    from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
     from docx.styles.style import ParagraphStyle, _TableStyle
     from docx.text.paragraph import Paragraph
 
@@ -1052,6 +1053,11 @@ class Table:
         }
         if source_index is not None:
             params["copyFormatFrom"] = source_index
+        else:
+            # python-docx's row: a cell for each grid column, as wide as the
+            # column, and nothing of the last row (its height, grid skips,
+            # header flag or cell formatting).
+            params["gridRow"] = True
         run_sync(self._session.doc.tables.insert_row(params))
         # Keep the bounds-check cache current so the next ``cell()``
         # access still hits the fast path.
@@ -1224,14 +1230,17 @@ class Table:
         run_sync(self._session.doc.tables.set_style(params))
 
     @property
-    def alignment(self) -> "WD_TABLE_ALIGNMENT | None":
-        from docx.enum.table import WD_TABLE_ALIGNMENT
+    def alignment(self) -> "WD_PARAGRAPH_ALIGNMENT | None":
+        """The table's ``w:jc``, as python-docx 1.2.0 reads it: through the
+        paragraph ``CT_Jc``, so a member of ``WD_PARAGRAPH_ALIGNMENT``, which
+        compares equal to the ``WD_TABLE_ALIGNMENT`` member of its value."""
+        from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
 
         info: object = run_sync(
             self._session.doc.tables.get_properties({"nodeId": self._fresh_node_id()}),
         )
         if isinstance(info, dict):
-            return WD_TABLE_ALIGNMENT.from_docx_studio(info.get("alignment"))
+            return WD_PARAGRAPH_ALIGNMENT.from_docx_studio(info.get("alignment"))
         return None
 
     @alignment.setter

{athena_python_docx-0.35.0 → athena_python_docx-0.37.0}/docx/text/paragraph.py

@@ -245,9 +245,15 @@ def _node_text(session: "Session", node_id: str, *, final: bool = False) -> str:
 
 def _picture_run_data(inline: dict, drawing: dict) -> dict:
     """The run data of a picture's inline (``{drawing}``): its ``w:r`` holds the
-    picture and no text, and the rendered page breaks docx-studio reads in it,
-    which stand before its drawing (``renderedPageBreaks``)."""
-    data: dict = {"text": "", "drawing": drawing}
+    picture and no text, the rendered page breaks docx-studio reads in it,
+    which stand before its drawing (``renderedPageBreaks``), and the run's
+    formatting it reads (its ``w:rPr``, which python-docx reads beside the
+    ``w:drawing``)."""
+    from docx.text.run import _RUN_READ_KEYS
+
+    data: dict = {key: value for key, value in inline.items() if key in _RUN_READ_KEYS}
+    data["text"] = ""
+    data["drawing"] = drawing
     breaks: object = inline.get("renderedPageBreaks")
     if isinstance(breaks, list):
         data["renderedPageBreaks"] = breaks