athena-python-docx 0.18.0__tar.gz → 0.18.1__tar.gz

{athena_python_docx-0.18.0 → athena_python_docx-0.18.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.18.0
+Version: 0.18.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.18.0 → athena_python_docx-0.18.1}/docx/__init__.py

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

{athena_python_docx-0.18.0 → athena_python_docx-0.18.1}/docx/document.py

@@ -463,11 +463,17 @@ class Document:
         from docx.text.paragraph import Paragraph
 
         self._ensure_open()
+        # Request the inlined run breakdown so each yielded Paragraph serves
+        # ``.text`` / ``.runs`` / ``.style`` from the one ``blocks.list`` instead
+        # of a ``get_node_by_id`` per item — without this, iterating and reading
+        # N blocks is N round-trips (each a full Y.Doc reload on docx-editor).
+        # Same prefetch as ``Document.paragraphs``; see PERFORMANCE_BATCHING_ANALYSIS.md.
         raw: object = run_sync(
             self._session.doc.blocks.list(
                 {
                     "nodeTypes": ["paragraph", "heading", "table"],
-                    "includeText": False,
+                    "includeText": True,
+                    "includeRuns": True,
                 },
             ),
         )
@@ -488,10 +494,18 @@ class Document:
             if nt == "table":
                 yield Table(session=self._session, node_id=node_id)
             else:
+                # Seed the read cache when the server inlined this block's runs
+                # (get_node_by_id-shaped snapshot, consumed unchanged by
+                # Paragraph._node_info). Tables / un-inlined blocks fall back to
+                # live queries.
+                snapshot: dict | None = (
+                    {"node": b} if isinstance(b.get("paragraph"), dict) else None
+                )
                 yield Paragraph(
                     session=self._session,
                     node_id=node_id,
                     node_type=nt if isinstance(nt, str) else "paragraph",
+                    node_info_snapshot=snapshot,
                 )
 
     @property
@@ -2210,10 +2224,17 @@ def _extract_inserted_node_id(result: dict, *, expected_type: str) -> str:
                 if block_id:
                     return block_id
 
-    # Shape 3 — top-level blockId or target.blockId.
+    # Shape 3 — top-level blockId / nodeId, or target.blockId. The docx-editor
+    # engine returns a flat ``{"changed": True, "nodeId": "<paraId>"}`` for
+    # create ops (no SuperDoc-style nesting), so accept a top-level ``nodeId``
+    # too — otherwise response-bearing creates (insert_paragraph_before,
+    # add_caption) raise "did not return nodeId" even though the block was made.
     top_block: object = result.get("blockId")
     if isinstance(top_block, str) and top_block:
         return top_block
+    top_node: object = result.get("nodeId")
+    if isinstance(top_node, str) and top_node:
+        return top_node
     top_target: object = result.get("target")
     if isinstance(top_target, dict):
         tb: str = str(top_target.get("blockId", ""))

{athena_python_docx-0.18.0 → athena_python_docx-0.18.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.18.0"
+version = "0.18.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.18.0 → athena_python_docx-0.18.1}/tests/test_commands.py

@@ -268,6 +268,16 @@ def test_extract_inserted_node_id_shapes() -> None:
     }
     assert _extract_inserted_node_id(r3, expected_type="paragraph") == "nX"
 
+    # docx-editor engine shape — flat top-level ``nodeId`` (no SuperDoc nesting).
+    # This is what ``CreateParagraph`` returns on docx-editor; before the fix it
+    # fell through to "" and ``insert_paragraph_before`` raised on success.
+    r4 = {"changed": True, "nodeId": "87753FA6"}
+    assert _extract_inserted_node_id(r4, expected_type="paragraph") == "87753FA6"
+
+    # docx-editor also (post server-fix) emits the nested type-keyed shape.
+    r5 = {"changed": True, "nodeId": "AB12CD34", "paragraph": {"nodeId": "AB12CD34"}}
+    assert _extract_inserted_node_id(r5, expected_type="paragraph") == "AB12CD34"
+
     # Unparseable — returns empty string
     assert _extract_inserted_node_id({}, expected_type="paragraph") == ""
     assert _extract_inserted_node_id("not a dict", expected_type="paragraph") == ""  # type: ignore[arg-type]

{athena_python_docx-0.18.0 → athena_python_docx-0.18.1}/tests/test_iter_inner_content.py

@@ -35,6 +35,43 @@ def test_document_iter_inner_content_yields_paragraphs_then_table() -> None:
     assert all(isinstance(i, (Paragraph, Table)) for i in items)
 
 
+def test_iter_inner_content_prefetches_runs_no_per_item_reads() -> None:
+    """``iter_inner_content`` requests ``includeRuns`` and seeds each yielded
+    Paragraph's snapshot, so reading ``.text`` / ``.runs`` / ``.style`` per item
+    costs no extra ``getNodeById`` — the slow path was one query per block (each a
+    full Y.Doc reload on docx-editor). Mirrors ``Document.paragraphs``."""
+    install_fake_session()
+    from docx import Document
+    from docx.text.paragraph import Paragraph
+
+    doc = Document("asset_fake")
+    doc.add_paragraph("Intro")
+    doc.add_heading("Section A", level=1)
+    doc.add_paragraph("Body")
+
+    items = list(doc.iter_inner_content())
+
+    # The listing asked the server to inline runs.
+    block_list_calls = [
+        params
+        for op, params in doc._session.calls()
+        if op == "blocks.list" and params.get("includeRuns") is True
+    ]
+    assert block_list_calls
+
+    # Reading text/style/runs off the iterated paragraphs issues NO per-item reads.
+    calls_before: int = len(doc._session.calls())
+    for item in items:
+        if isinstance(item, Paragraph):
+            _ = item.text
+            _ = item.style
+            _ = list(item.runs)
+    extra_node_reads = [
+        op for op, _ in doc._session.calls()[calls_before:] if op == "getNodeById"
+    ]
+    assert extra_node_reads == []
+
+
 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