athena-python-docx 0.23.0__tar.gz → 0.24.0__tar.gz

{athena_python_docx-0.23.0 → athena_python_docx-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.23.0
+Version: 0.24.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.23.0 → athena_python_docx-0.24.0}/docx/__init__.py

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

athena_python_docx-0.24.0/docx/_run_order.py

@@ -0,0 +1,217 @@
+"""Run order of a paragraph, as ``Paragraph.add_run`` created its runs.
+
+A picture takes no text offset, so two runs can end at the same offset:
+``r1 = p.add_run("A"); r2 = p.add_run(); r2.add_picture(img)`` puts ``r2`` and
+its picture at offset 1, where ``r1`` ends. The offset alone cannot tell the
+server whether content for ``r1`` goes before or after that picture. The SDK
+knows: ``add_run`` appends each run to the end of its paragraph.
+
+This module keeps a record of each such run (its range and the pictures that
+its ``add_picture`` added), in creation order, and gives:
+
+- the run identity of a run-end insert (:func:`run_ref`): the first picture
+  that a later run holds at the same offset (for a read segment that ends
+  inside its run, also the run's own picture there). The server puts the
+  content in front of it; without it, after the pictures at the offset.
+- current ranges: when a run grows or shrinks, its pictures and the runs after
+  it move (:func:`note_length_change`), and so do the live run proxies. A
+  replace cuts every record that it touches.
+
+A record lives as long as its paragraph proxy, not as long as its run proxy,
+so ``p.add_run().add_picture(img)`` keeps the picture's place. The records of
+every paragraph proxy of one block (``doc.paragraphs`` makes new ones) are one
+order. A read run (``paragraph.runs``) stands for the recorded run that holds
+its last character; a read run over text that no recorded run holds counts as
+a run before all of them. The order lives in the SDK process only; the
+document stores none of it.
+"""
+
+from __future__ import annotations
+
+import itertools
+import weakref
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from docx.text.run import Run
+
+_SEQ = itertools.count()
+
+
+@dataclass(eq=False)
+class RunRecord:
+    """One run that ``add_run`` created."""
+
+    seq: int
+    range: tuple[int, int]
+    run: "weakref.ref[Run]"
+    # ``(picture id, offset)`` of each picture that the run's ``add_picture`` added.
+    pictures: list[tuple[str, int]] = field(default_factory=list)
+
+
+# Paragraph proxy -> the records of the runs its ``add_run`` created. A record
+# holds no reference to the paragraph or session, so an entry goes with its
+# paragraph proxy. Keyed by the proxy, not by its id: the first flush moves a
+# new paragraph from its client id to the server id, and the runs created
+# before that keep the client id.
+_ORDERS: "weakref.WeakKeyDictionary[Any, list[RunRecord]]" = weakref.WeakKeyDictionary()
+
+
+def _records_of(run: "Run") -> list[RunRecord]:
+    paragraph = getattr(run, "_paragraph", None)
+    ids = {run._block_id}
+    if paragraph is not None:
+        ids.add(paragraph._node_id)
+    records: list[RunRecord] = []
+    for owner, owner_records in list(_ORDERS.items()):
+        if owner is paragraph or (owner._session is run._session and owner._node_id in ids):
+            records.extend(owner_records)
+    records.sort(key=lambda record: record.seq)
+    return records
+
+
+def register_run(run: "Run") -> None:
+    """Record ``run`` as the last run of its paragraph (``Paragraph.add_run``)."""
+    record = RunRecord(seq=next(_SEQ), range=run._range, run=weakref.ref(run))
+    _ORDERS.setdefault(run._paragraph, []).append(record)
+    run._run_record = record
+
+
+def forget_paragraph(paragraph: Any) -> None:
+    """Drop the order of a paragraph whose runs are gone (``Paragraph.text = ...``)."""
+    for owner in list(_ORDERS.keys()):
+        if owner is paragraph or (owner._session is paragraph._session and owner._node_id == paragraph._node_id):
+            _ORDERS.pop(owner, None)
+
+
+def _place(
+    run: "Run", span: tuple[int, int], records: list[RunRecord] | None = None
+) -> tuple[RunRecord | None, list[RunRecord]]:
+    """The record of ``run`` (over ``span``), if any, and the records after it."""
+    if records is None:
+        records = _records_of(run)
+    # The run itself, or the text that its ``add_text`` returned.
+    own = getattr(run, "_run_record", None) or getattr(run, "_owner_record", None)
+    for index, record in enumerate(records):
+        if record is own:
+            return record, records[index + 1 :]
+    # ``paragraph.runs`` makes a new proxy of a kept run: over the same range,
+    # or over a part of it (a read splits a run at a tab, a break or a change
+    # of format). The proxy stands for the run that holds its last character.
+    if span[0] != span[1]:
+        last = span[1] - 1
+        for index, record in enumerate(records):
+            if record.range[0] <= last < record.range[1]:
+                return record, records[index + 1 :]
+    return None, records
+
+
+def _set_range(record: RunRecord, value: tuple[int, int]) -> None:
+    record.range = value
+    proxy = record.run()
+    if proxy is not None:
+        proxy._range = value
+
+
+def note_length_change(
+    run: "Run",
+    at: int,
+    delta: int,
+    *,
+    replaced: tuple[int, int] | None = None,
+    before: str | None = None,
+) -> None:
+    """``run`` (already over its new range) changed its text by ``delta`` units.
+
+    Without ``replaced``: an insert of ``delta`` units at ``at`` (the end of
+    ``run``), in front of the picture ``before`` when the command named one
+    (else after the pictures at ``at``). With ``replaced``: ``Run.text``
+    replaced the old range ``replaced``; the server keeps the pictures at its
+    start and end and removes the ones inside.
+
+    The text belongs to the record of ``run`` (see :func:`_place`). Every
+    record that the replaced range touches is cut; the records and pictures
+    after the change move.
+    """
+    if delta == 0 and replaced is None:
+        return
+    records = _records_of(run)
+    if replaced is None:
+        start = end = at
+        inserted = delta
+        old_span = (run._range[0], run._range[1] - delta)
+    else:
+        start, end = replaced
+        inserted = (end - start) + delta
+        old_span = replaced
+    owner = _place(run, old_span, records)[0]
+    owner_index = records.index(owner) if owner is not None else -1
+    removed = end - start
+
+    def cut(x: int) -> int:
+        return x if x <= start else start if x < end else x - removed
+
+    # The pictures at ``at`` that an insert goes in front of: ``before`` and
+    # the ones after it, in document order (records in order, then the
+    # pictures of each record in order).
+    moved_at: set[str] = set()
+    if replaced is None and before is not None:
+        order = [pid for record in records for pid, off in record.pictures if off == at]
+        if before in order:
+            moved_at = set(order[order.index(before) :])
+
+    for index, record in enumerate(records):
+        rec_start, rec_end = cut(record.range[0]), cut(record.range[1])
+        if record is owner:
+            rec_end += inserted
+        elif index > owner_index and rec_start >= start:
+            rec_start, rec_end = rec_start + inserted, rec_end + inserted
+        _set_range(record, (rec_start, rec_end))
+        pictures: list[tuple[str, int]] = []
+        for pid, off in record.pictures:
+            if replaced is None:
+                pictures.append((pid, off + delta if off > at or pid in moved_at else off))
+            elif off <= start:
+                pictures.append((pid, off))
+            elif off >= end:
+                pictures.append((pid, off + delta))
+        # The moves keep document order; a stable sort by offset keeps it so.
+        pictures.sort(key=lambda item: item[1])
+        record.pictures = pictures
+
+
+def note_picture(run: "Run", picture_id: str, offset: int, *, before: str | None = None) -> None:
+    """``run.add_picture`` put the picture ``picture_id`` at ``offset``, in front of ``before``.
+
+    A record keeps its pictures in document order: the new one goes in front
+    of ``before``, else after the pictures at ``offset`` and before the ones
+    after it (the server puts a picture after the pictures at its offset).
+    """
+    record = _place(run, run._range)[0]
+    if record is None:
+        return
+    ids = [pid for pid, _ in record.pictures]
+    if before in ids:
+        index = ids.index(before)
+    else:
+        index = next((i for i, (_, off) in enumerate(record.pictures) if off > offset), len(ids))
+    record.pictures.insert(index, (picture_id, offset))
+
+
+def run_ref(run: "Run") -> dict[str, str] | None:
+    """``{"beforeImageId": id}``: the picture that an insert at the end of ``run`` goes in front of.
+
+    The first picture of a later run where ``run`` ends. A read segment that
+    ends inside its run (a picture of the run between two of its texts) also
+    puts the insert in front of the run's own picture there, right after the
+    segment's text.
+    """
+    end = run._range[1]
+    record, later = _place(run, run._range)
+    candidates = ([record] if record is not None and end < record.range[1] else []) + later
+    for candidate in candidates:
+        for picture_id, offset in candidate.pictures:
+            if offset == end:
+                return {"beforeImageId": picture_id}
+    return None

{athena_python_docx-0.23.0 → athena_python_docx-0.24.0}/docx/commands.py

@@ -109,12 +109,19 @@ class CreateTable(Command):
     client_node_id: str | None = None
 
 
+# Run identity of a run-end insert (``Run.add_text`` / ``add_tab`` /
+# ``add_break`` / ``add_picture``, ``Run.text`` on an empty run):
+# ``{"beforeImageId": <picture id>}``, the first picture that a later run
+# holds at the same offset (see ``docx._run_order``). The server puts the
+# content in front of it. ``None`` (not sent): after the pictures there.
+# ``Insert``, ``InsertTab`` and ``InsertLineBreak`` carry it too.
 @dataclass
 class CreateImage(Command):
     src: str
     size: dict[str, Any]
     at: dict[str, Any]
     client_node_id: str | None = None
+    run: dict[str, Any] | None = None
 
 
 @dataclass
@@ -142,6 +149,7 @@ class Insert(Command):
     inherit_marks: bool | None = None
     placement: str | None = None
     content: dict[str, Any] | None = None
+    run: dict[str, Any] | None = None
 
 
 @dataclass
@@ -181,12 +189,14 @@ class Replace(Command):
 class InsertLineBreak(Command):
     block_id: str
     offset: int
+    run: dict[str, Any] | None = None
 
 
 @dataclass
 class InsertTab(Command):
     block_id: str
     offset: int
+    run: dict[str, Any] | None = None
 
 
 @dataclass
@@ -490,10 +500,15 @@ class SetImageSize(Command):
 class SetImageAltText(Command):
     """Set alt-text on an inline image. Mirrors DOCX Studio's
     ``doc.images.setAltText``. Used by accessibility flows that need
-    a text alternative for screen readers."""
+    a text alternative for screen readers.
+
+    ``alt_text`` is Word's description (``wp:docPr/@descr``). ``title`` is
+    Word's title (``wp:docPr/@title``); ``None`` leaves it unchanged, and an
+    older docx-studio ignores the field."""
 
     image_id: str
     alt_text: str
+    title: str | None = None
 
 
 @dataclass
@@ -551,7 +566,9 @@ class GetNode(Command):
 
 @dataclass
 class ImagesList(Command):
-    pass
+    # ``False`` leaves out each picture's ``src`` (a data URI can be MBs); an
+    # older docx-studio ignores the field and sends ``src``.
+    include_src: bool | None = None
 
 
 @dataclass

{athena_python_docx-0.23.0 → athena_python_docx-0.24.0}/docx/shape.py

@@ -65,6 +65,19 @@ def _strip_data_uri(src: str) -> tuple[bytes, str | None]:
         return b"", mime
 
 
+def _picture_id_parts(node_id: str) -> tuple[str, str, str | None]:
+    """``(paraId, fingerprint, persisted id)`` of a picture id.
+
+    A picture id is ``<paraId>:<index>:<fingerprint>``, with a fourth part
+    ``:<persisted id>`` when the room stores one; an older docx-studio gives
+    only ``<paraId>`` or ``<paraId>:<index>``.
+    """
+    parts = node_id.split(":")
+    fingerprint = parts[2] if len(parts) > 2 else ""
+    persisted = parts[3] if len(parts) > 3 else None
+    return parts[0], fingerprint, persisted
+
+
 class InlineShape:
     """An inline image/shape in the document."""
 
@@ -177,15 +190,75 @@ class InlineShape:
     @alt_text.setter
     @athena_extension(issue="PR#1530", description="InlineShape.alt_text setter.")
     def alt_text(self, value: str | None) -> None:
+        text = "" if value is None else str(value)
+        if self._can_address(stacklevel=3):
+            self._send_alt_text(alt_text=text, title=None)
+            self._info["altText"] = text
+
+    def _can_address(self, *, stacklevel: int) -> bool:
+        """``False`` (with a warning) for a shape that has no id.
+
+        A listed picture on an older docx-studio, whose ``ImagesList`` sends
+        no ``nodeId``, cannot be addressed, and an empty ``imageId`` fails the
+        whole batch there. The setter then sends nothing and keeps the old
+        value, so the shape does not report a change that the document does
+        not have.
+        """
+        from docx.errors import DocxUnsupportedCommandWarning
+
+        if self._node_id:
+            return True
+        warnings.warn(
+            "InlineShape alt text / title / decorative was not set: this picture has "
+            "no id. Read the shape again from doc.inline_shapes after "
+            "docx-studio is updated.",
+            DocxUnsupportedCommandWarning,
+            stacklevel=stacklevel + 1,
+        )
+        return False
+
+    def _send_alt_text(self, *, alt_text: str, title: str | None) -> None:
         from docx.commands import SetImageAltText
 
-        text = "" if value is None else str(value)
         run_sync(
             self._session.send_command(
-                SetImageAltText(image_id=self._node_id, alt_text=text),
+                SetImageAltText(image_id=self._node_id, alt_text=alt_text, title=title),
             ),
         )
-        self._info["altText"] = text
+
+    def _stored_alt_text(self) -> str:
+        """The description that the document stores for this picture now.
+
+        Another shape for the same picture can change the description after
+        this shape read it. ``ImagesList`` gives the current value, without
+        the image data; the cached value is the fallback when the list does
+        not name the picture (an older docx-studio). The read flushes pending
+        commands first, so a client id is the real id after it.
+        """
+        rows = InlineShapes(session=self._session)._items(include_src=False)
+        node_id = self._node_id
+        para_id, fingerprint, persisted = _picture_id_parts(node_id)
+        same: list[dict] = []
+        for row in rows:
+            row_id = str(row.get("nodeId") or "")
+            if row_id == node_id:
+                same = [row]
+                break
+            row_para, row_fingerprint, row_persisted = _picture_id_parts(row_id)
+            # A persisted id names one picture, in any paragraph and position.
+            if persisted is not None and row_persisted is not None:
+                if row_persisted == persisted:
+                    same = [row]
+                    break
+                continue
+            # A room without persisted ids (an older editor removed them):
+            # the paragraph and the fingerprint, as the server does.
+            if row_para != para_id:
+                continue
+            if ":" not in node_id or (fingerprint and row_fingerprint == fingerprint):
+                same.append(row)
+        stored = same[0].get("altText") if len(same) == 1 else None
+        return stored if isinstance(stored, str) else self.alt_text
 
     @property
     @athena_extension(issue="PR#1530", description="InlineShape.title — image title.")
@@ -202,14 +275,15 @@ class InlineShape:
     @title.setter
     @athena_extension(issue="PR#1530", description="InlineShape.title setter.")
     def title(self, value: str | None) -> None:
-        from docx.commands import SetImageAltText
-
         text = "" if value is None else str(value)
-        run_sync(
-            self._session.send_command(
-                SetImageAltText(image_id=self._node_id, alt_text=text),
-            ),
-        )
+        if not self._can_address(stacklevel=3):
+            return
+        # The command always carries the description: an older docx-studio
+        # requires ``altText`` and ignores ``title``. Sending the stored
+        # description keeps it; before, the title text replaced it.
+        alt_text = self._stored_alt_text()
+        self._send_alt_text(alt_text=alt_text, title=text)
+        self._info["altText"] = alt_text
         self._info["title"] = text
 
     @property
@@ -228,6 +302,8 @@ class InlineShape:
     def decorative(self, value: bool) -> None:
         from docx.commands import SetImageDecorative
 
+        if not self._can_address(stacklevel=3):
+            return
         run_sync(
             self._session.send_command(
                 SetImageDecorative(image_id=self._node_id, decorative=bool(value)),
@@ -283,8 +359,9 @@ class InlineShapes:
     def __init__(self, *, session: "Session") -> None:
         self._session: "Session" = session
 
-    def _items(self) -> list[dict]:
-        info: object = run_sync(self._session.doc.images.list({}))
+    def _items(self, *, include_src: bool = True) -> list[dict]:
+        params: dict = {} if include_src else {"includeSrc": False}
+        info: object = run_sync(self._session.doc.images.list(params))
         if isinstance(info, dict):
             items: object = info.get("items") or info.get("images") or []
             if isinstance(items, list):

{athena_python_docx-0.23.0 → athena_python_docx-0.24.0}/docx/text/paragraph.py

@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING, Any
 
 from docx._athena_extension import athena_extension
 from docx._batching import run_sync
+from docx._run_order import forget_paragraph, register_run
 
 if TYPE_CHECKING:
     from docx._references import AssetReference
@@ -431,6 +432,8 @@ class Paragraph:
         # We just replaced the entire paragraph contents with ``value``;
         # the new text-address length is simply ``len(value)``.
         self._text_len = len(value)
+        # The runs of the paragraph are gone, as in python-docx.
+        forget_paragraph(self)
         # Content changed — drop the prefetched snapshot so a follow-up
         # ``.text`` / ``.runs`` read reflects the replacement.
         self._invalidate_node_info()
@@ -1232,6 +1235,12 @@ class Paragraph:
             in_cell=self._in_cell,
             cell_ooxml_address=self._cell_ooxml_address,
         )
+        # The paragraph's run order, so a run-end insert at an offset that two
+        # runs share goes to the right run (see ``docx._run_order``).
+        register_run(run_obj)
+        # A new empty run has no formatting of its own yet: its first text
+        # does not take the formatting of the run before it.
+        run_obj._fresh = not text_str
         if style is not None:
             style_id: str = (
                 style.style_id if isinstance(style, CharacterStyle) else style