athena-python-docx 0.16.0__tar.gz → 0.16.1__tar.gz

{athena_python_docx-0.16.0 → athena_python_docx-0.16.1}/PKG-INFO

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

{athena_python_docx-0.16.0 → athena_python_docx-0.16.1}/docx/__init__.py

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

{athena_python_docx-0.16.0 → athena_python_docx-0.16.1}/docx/_buffer.py

@@ -130,6 +130,21 @@ if TYPE_CHECKING:
 _PTC_EMIT_TOOLS: frozenset[str] = frozenset({"CreateParagraph", "CreateHeading", "CreateTable"})
 
 
+def _should_emit_ptc(cmd: Command) -> bool:
+    """Whether ``cmd`` should produce a PTC sub-tool-card.
+
+    Only allow-listed block creates emit, and only when they target the
+    **body** story. Creates carrying an ``in_`` story locator (header,
+    footer, footnote, …) are skipped: the frontend locate affordance
+    scans the body editor only, so a header/footer card would highlight
+    an unrelated body block or nothing at all. Skip until the frontend
+    can route by ``args.in``.
+    """
+    if type(cmd).__name__ not in _PTC_EMIT_TOOLS:
+        return False
+    return getattr(cmd, "in_", None) is None
+
+
 def _ptc_emit_end_batch(cmds: list[Command], *, is_error: bool) -> None:
     """Emit a PTC ``end`` event for every cmd that received a ``begin``.
 
@@ -414,7 +429,7 @@ class CommandBuffer:
         # commands still flow through the buffer (and through the batched
         # HTTP POST), they just don't produce a sub-tool-card. ``emit_end``
         # is automatically skipped because no ``_ptc_call_id`` was set.
-        if type(cmd).__name__ in _PTC_EMIT_TOOLS:
+        if _should_emit_ptc(cmd):
             try:
                 cmd._ptc_call_id = _ptc.emit_begin(  # type: ignore[attr-defined]
                     type(cmd).__name__,

{athena_python_docx-0.16.0 → athena_python_docx-0.16.1}/docx/commands.py

@@ -519,6 +519,11 @@ class ImagesGet(Command):
 class BlocksList(Command):
     node_types: list[str] | None = None
     include_text: bool | None = None
+    # Ask the server to inline each paragraph/heading block's run breakdown
+    # (``paragraph.inlines``) so ``Document.paragraphs`` can hydrate
+    # ``Paragraph.text``/``.runs``/``.style`` from one list instead of a
+    # ``get_node_by_id`` per paragraph. Serialized to ``includeRuns`` on the wire.
+    include_runs: bool | None = None
 
 
 @dataclass

{athena_python_docx-0.16.0 → athena_python_docx-0.16.1}/docx/document.py

@@ -359,12 +359,23 @@ class Document:
         # Include "heading" too so iterating over paragraphs covers both —
         # python-docx does not distinguish headings from paragraphs at the
         # Document.paragraphs level either (they're all Paragraph instances).
+        # ``includeRuns`` asks the server to inline each block's run breakdown
+        # (``paragraph.inlines``) so we can hydrate every returned proxy's
+        # ``.text`` / ``.runs`` / ``.style`` from this single list — instead of
+        # one ``get_node_by_id`` round-trip per paragraph per property. A
+        # read-heavy restyle loop over a large doc drops from ~N×3 round-trips
+        # to 1. See ``docx-studio/PERFORMANCE_BATCHING_ANALYSIS.md``.
         raw: object = run_sync(
             self._session.doc.blocks.list(
-                {"nodeTypes": ["paragraph", "heading"], "includeText": False},
+                {
+                    "nodeTypes": ["paragraph", "heading"],
+                    "includeText": True,
+                    "includeRuns": True,
+                },
             ),
         )
-        # Real shape: {"blocks": [{"kind":"block","nodeType":..,"nodeId":..}], ...}
+        # Real shape: {"blocks": [{"kind":"block","nodeType":..,"nodeId":..,
+        # "styleId":..,"text":..,"paragraph":{"inlines":[..]}}], ...}
         if isinstance(raw, dict):
             blocks_obj: object = raw.get("blocks", [])
             blocks: list = blocks_obj if isinstance(blocks_obj, list) else []
@@ -380,11 +391,20 @@ class Document:
             if node_id:
                 nt_raw = b.get("nodeType")
                 nt: str = nt_raw if isinstance(nt_raw, str) and nt_raw else "paragraph"
+                # Seed the read cache when the server inlined this block's runs.
+                # The snapshot is ``get_node_by_id``-shaped so
+                # ``Paragraph._node_info`` and the text/runs/style getters consume
+                # it unchanged. Blocks without an ``inlines`` payload (e.g.
+                # tables) fall back to live queries.
+                snapshot: dict | None = (
+                    {"node": b} if isinstance(b.get("paragraph"), dict) else None
+                )
                 out.append(
                     Paragraph(
                         session=self._session,
                         node_id=node_id,
                         node_type=nt,
+                        node_info_snapshot=snapshot,
                     ),
                 )
         return out

{athena_python_docx-0.16.0 → athena_python_docx-0.16.1}/docx/text/paragraph.py

@@ -226,6 +226,7 @@ class Paragraph:
         in_cell: bool = False,
         cell_ooxml_address: "tuple[str | None, int, int, int, int] | None" = None,
         cell: "object | None" = None,
+        node_info_snapshot: dict | None = None,
     ) -> None:
         self._session: "Session" = session
         self._node_id: str = node_id
@@ -272,6 +273,36 @@ class Paragraph:
         # — defensive for paragraph proxies built outside the _Cell
         # construction paths.
         self._cell: object | None = cell
+        # Prefetched ``get_node_by_id``-shaped snapshot
+        # (``{"node": {..., "paragraph": {"inlines": [...]}}}``) seeded by
+        # ``Document.paragraphs`` via the bulk ``blocks.list(includeRuns=True)``
+        # read. When present, ``text`` / ``runs`` / ``style`` read it instead of
+        # issuing a per-property ``get_node_by_id`` round-trip. It is a
+        # point-in-time snapshot (consistent with ``Document.paragraphs`` already
+        # returning a snapshot list) and is dropped by ``_invalidate_node_info``
+        # the moment this proxy mutates its own content.
+        self._node_info_snapshot: dict | None = node_info_snapshot
+
+    def _node_info(self) -> object:
+        """Return this paragraph's ``get_node_by_id``-shaped node info.
+
+        Served from the prefetch snapshot when one was seeded (one bulk
+        ``blocks.list`` for the whole document instead of one
+        ``get_node_by_id`` per ``.text`` / ``.runs`` / ``.style`` access);
+        otherwise a live query. ``_invalidate_node_info`` clears the snapshot
+        after a content mutation so the next read re-queries.
+        """
+        snapshot = self._node_info_snapshot
+        if snapshot is not None:
+            return snapshot
+        return run_sync(
+            self._session.doc.get_node_by_id({"id": self._node_id}),
+        )
+
+    def _invalidate_node_info(self) -> None:
+        """Drop the prefetched node snapshot after a content mutation, so the
+        next ``text`` / ``runs`` / ``style`` read reflects the new state."""
+        self._node_info_snapshot = None
 
     def _check_cell_inner(self, op: str, **format_props: Any) -> bool:
         """Return ``True`` if this paragraph is inside a table cell and
@@ -356,7 +387,7 @@ class Paragraph:
     @property
     def text(self) -> str:
         """Return the plain-text content of this paragraph."""
-        return _node_text(self._session, self._node_id)
+        return _extract_text(self._node_info())
 
     @text.setter
     def text(self, value: str) -> None:
@@ -399,6 +430,9 @@ 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)
+        # Content changed — drop the prefetched snapshot so a follow-up
+        # ``.text`` / ``.runs`` read reflects the replacement.
+        self._invalidate_node_info()
 
     @property
     def runs(self) -> list["Run"]:
@@ -413,9 +447,7 @@ class Paragraph:
         """
         from docx.text.run import Run
 
-        info: object = run_sync(
-            self._session.doc.get_node_by_id({"id": self._node_id}),
-        )
+        info: object = self._node_info()
         inlines: list[dict] = _walk_inlines(info)
         runs: list["Run"] = []
         offset: int = 0
@@ -479,9 +511,7 @@ class Paragraph:
         from docx.styles.style import ParagraphStyle
         from docx.enum.style import WD_STYLE_TYPE
 
-        info: object = run_sync(
-            self._session.doc.get_node_by_id({"id": self._node_id}),
-        )
+        info: object = self._node_info()
         if not isinstance(info, dict):
             return None
         node: object = info.get("node")
@@ -537,6 +567,10 @@ class Paragraph:
                 },
             ),
         )
+        # Style changed — drop the prefetched snapshot so a follow-up ``.style``
+        # read reflects the new style instead of the stale prefetched value
+        # (the restyle-loop read-after-write this PR's prefetch targets).
+        self._invalidate_node_info()
 
     @property
     def alignment(self) -> "WD_ALIGN_PARAGRAPH | None":
@@ -1227,6 +1261,9 @@ class Paragraph:
                 )
             offset += 1
             i = j + 1
+        # Inserted content — drop the prefetched node snapshot so a follow-up
+        # ``.text`` / ``.runs`` read on this proxy reflects the new runs.
+        self._invalidate_node_info()
 
     @athena_extension(
         issue=74,
@@ -1397,6 +1434,11 @@ class Paragraph:
         )
         run_sync(self._session.send_command(cmd))
         self._text_len = end_offset
+        # Appended a hyperlink run — drop the prefetched snapshot so a follow-up
+        # ``.text`` / ``.runs`` read reflects the new content. This path fires
+        # ``CreateHyperlink`` directly via ``send_command`` (it bypasses
+        # ``_insert_run_text_segments``), so it needs its own invalidation.
+        self._invalidate_node_info()
 
         run_dict = {"text": text, "hyperlink": {"url": url, "target": url}}
         return Hyperlink(

{athena_python_docx-0.16.0 → athena_python_docx-0.16.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.16.0"
+version = "0.16.1"
 description = "Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack"
 readme = "README.md"
 license = "MIT"

{athena_python_docx-0.16.0 → athena_python_docx-0.16.1}/tests/fidelity/fake_session.py

@@ -296,6 +296,7 @@ class FakeDocState:
 
         if op == "blocks.list":
             types = params.get("nodeTypes") or None
+            include_runs = bool(params.get("includeRuns"))
             out_blocks: list[dict] = []
             for b in self.blocks:
                 if types and b.node_type not in types:
@@ -307,6 +308,12 @@ class FakeDocState:
                     "styleId": b.style_id,
                     "alignment": b.alignment,
                 }
+                # Mirror the real server: when runs are requested, inline each
+                # paragraph/heading block's run breakdown so the SDK hydrates
+                # Paragraph.text/.runs/.style from this one list (no per-node read).
+                if include_runs and b.node_type in ("paragraph", "heading"):
+                    entry["text"] = b.text
+                    entry["paragraph"] = {"inlines": list(b.inlines)}
                 out_blocks.append(entry)
             # Mirror real SuperDoc: when "table" is in the requested
             # nodeTypes, top-level tables come back too. The fake doesn't

{athena_python_docx-0.16.0 → athena_python_docx-0.16.1}/tests/test_iter_inner_content.py

@@ -35,15 +35,22 @@ def test_document_iter_inner_content_yields_paragraphs_then_table() -> None:
     assert all(isinstance(i, (Paragraph, Table)) for i in items)
 
 
-def test_document_paragraphs_uses_lightweight_block_listing() -> None:
+def test_document_paragraphs_prefetches_runs_in_one_listing() -> None:
+    """``Document.paragraphs`` issues ONE rich ``blocks.list(includeRuns=True)``
+    and hydrates every proxy's text/style/runs from it — so iterating and reading
+    per-paragraph properties costs no extra ``getNodeById`` round-trips (the old
+    hot path was one query per property per paragraph). See
+    ``docx-studio/PERFORMANCE_BATCHING_ANALYSIS.md``."""
     install_fake_session()
     from docx import Document
 
     doc = Document("asset_fake")
     doc.add_paragraph("Intro")
+    doc.add_heading("Section A", level=1)
 
-    _ = doc.paragraphs
+    paras = doc.paragraphs
 
+    # paragraphs() asked the server to inline the run breakdown.
     block_list_calls = [
         params
         for op, params in doc._session.calls()
@@ -51,7 +58,62 @@ def test_document_paragraphs_uses_lightweight_block_listing() -> None:
         and params.get("nodeTypes") == ["paragraph", "heading"]
     ]
     assert block_list_calls
-    assert block_list_calls[-1]["includeText"] is False
+    assert block_list_calls[-1]["includeRuns"] is True
+
+    # Reading text/style/runs off the prefetched proxies issues NO per-paragraph
+    # getNodeById round-trips.
+    calls_before: int = len(doc._session.calls())
+    for p in paras:
+        _ = p.text
+        _ = p.style
+        _ = list(p.runs)
+    extra_node_reads = [
+        op for op, _ in doc._session.calls()[calls_before:] if op == "getNodeById"
+    ]
+    assert extra_node_reads == []
+
+
+def test_paragraph_text_mutation_invalidates_prefetch_snapshot() -> None:
+    """A content mutation on a prefetched paragraph drops its snapshot, so the
+    next read reflects the new state instead of the stale prefetched value."""
+    install_fake_session()
+    from docx import Document
+
+    doc = Document("asset_fake")
+    doc.add_paragraph("Original")
+
+    p = doc.paragraphs[0]
+    assert p.text == "Original"  # served from the prefetch snapshot
+
+    p.text = "Replaced"  # content mutation → snapshot invalidated
+
+    calls_before: int = len(doc._session.calls())
+    assert p.text == "Replaced"  # re-read reflects the mutation
+    # The fresh read went back to the server (the stale snapshot was dropped).
+    assert any(
+        op == "getNodeById" for op, _ in doc._session.calls()[calls_before:]
+    )
+
+
+def test_paragraph_style_set_invalidates_prefetch_snapshot() -> None:
+    """Setting ``.style`` on a prefetched paragraph drops its snapshot, so the
+    next ``.style`` read returns the new style — the restyle-loop read-after-write
+    (``for p in doc.paragraphs: p.style = ...``) the prefetch optimizes for."""
+    install_fake_session()
+    from docx import Document
+
+    doc = Document("asset_fake")
+    doc.add_paragraph("Body")
+
+    p = doc.paragraphs[0]
+    _ = p.style  # prime the prefetch snapshot
+
+    p.style = "Heading1"  # style mutation → snapshot must be invalidated
+
+    style_after = p.style
+    assert style_after is not None
+    # Re-read reflects the new style instead of the stale prefetched value.
+    assert style_after.name == "Heading1"
 
 
 def test_document_tables_uses_lightweight_block_listing() -> None:

{athena_python_docx-0.16.0 → athena_python_docx-0.16.1}/tests/test_ptc.py

@@ -524,6 +524,46 @@ def test_buffer_emits_for_create_table(monkeypatch: Any) -> None:
     assert calls["end"][0]["is_error"] is False
 
 
+def test_buffer_skips_ptc_for_non_body_creates(monkeypatch: Any) -> None:
+    """Allow-listed creates that target a non-body story (header/footer/
+    footnote via ``in_``) do NOT emit a PTC card: the frontend locate
+    affordance scans the body editor only, so a header/footer card would
+    highlight an unrelated body block or nothing. Body creates still emit."""
+    from docx._buffer import CommandBuffer
+    from docx.commands import CreateTable
+
+    calls = _stub_ptc(monkeypatch)
+    client = _FakeHttpClient()
+    buf = CommandBuffer(client, asset_id="asset-1", auto_flush_seconds=0)
+
+    # Header/footer table → carries an ``in_`` story locator → no card.
+    buf.call(
+        CreateTable(
+            rows=2,
+            columns=2,
+            at={"kind": "documentEnd"},
+            in_={"kind": "story", "storyType": "headerFooterPart", "refId": "r1"},
+            client_node_id="t_header",
+        )
+    )
+    assert len(calls["begin"]) == 0
+
+    # Body table (no ``in_``) → still emits.
+    buf.call(
+        CreateTable(
+            rows=2,
+            columns=2,
+            at={"kind": "documentEnd"},
+            client_node_id="t_body",
+        )
+    )
+    assert len(calls["begin"]) == 1
+
+    buf.flush()
+    # Only the body create that received a begin gets an end.
+    assert len(calls["end"]) == 1
+
+
 def test_buffer_emits_end_with_error_on_flush_failure(monkeypatch: Any) -> None:
     """End events fire with ``is_error=True`` when the batch raises.