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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.18.0
+Version: 0.18.2
 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.2}/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.2"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.18.0 → athena_python_docx-0.18.2}/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.2}/docx/table.py

@@ -384,6 +384,11 @@ class Table:
         # ``table-auto-…`` id, followed by ``ValidationError: Cell (r,c)
         # not found`` when a cell access hit the wrong table.
         self._doc_index: int | None = doc_index
+        # Set True once any cell merge is applied through this proxy. The
+        # positional cell-id fast path (``_Cell._positional_cell_id``) is only
+        # valid on a uniform grid, so a merged table must fall back to the
+        # query/walk-back path that aliases secondary slots to the master.
+        self._has_merges: bool = False
         # Header/footer part identity. ``_header_footer_ref_id`` is the
         # relationship id (e.g. ``"rId9"``) returned by
         # ``header_footers.parts.create`` that points the section sectPr
@@ -1490,7 +1495,48 @@ class _Cell:
             return None
         return None
 
+    def _positional_cell_id(self) -> str | None:
+        """Compute the docx-editor cell id (``tc:tableIndex:row:col``)
+        client-side, or return ``None`` to fall back to the query path.
+
+        docx-editor cell ids are purely positional — a function of the
+        table's ``t:N`` id plus grid position — so a cell-format op
+        (``set_shading`` / ``set_borders`` / cell properties) can build its
+        address WITHOUT a ``tables.get_cells`` round-trip. On docx-editor
+        every such query is a full Y.Doc reload (no session pool), so resolving
+        ~one per cell is what makes a styled table slow; this mirrors how
+        athena-python-pptx addresses shapes by client-assigned id so the whole
+        build buffers into one batch.
+
+        Reads the proxy's stored ``_node_id`` with NO round-trip. SuperDoc
+        tables carry real (non-``t:N``) node ids → returns ``None`` so the
+        caller queries (SuperDoc is pooled, so that read is cheap anyway). A
+        freshly-created docx-editor table still holds a client UUID until its
+        create flushes, so the first cell op falls back to the query (which
+        flushes + rotates ``_node_id`` to ``t:N``) and every subsequent cell
+        op fast-paths.
+
+        Gated to a **known uniform grid**: the table must have been created
+        via :meth:`Document.add_table` (so ``_doc_index`` is set and the full
+        structure is known) AND have no merge applied (``_has_merges``). A
+        merge aliases each secondary slot back to the top-left master — the
+        ``_cell_info`` walk-back is what performs that mapping — so a merged
+        table, or a read-loaded table whose merge state is unknown
+        (``_doc_index is None``, possible template merges we can't see), must
+        fall back to the query path to stay address-correct.
+        """
+        table = self._table
+        if getattr(table, "_doc_index", None) is None or getattr(table, "_has_merges", False):
+            return None
+        nid = getattr(table, "_node_id", None)
+        if isinstance(nid, str) and nid.startswith("t:") and nid[2:].isdigit():
+            return f"tc:{nid[2:]}:{self._row}:{self._col}"
+        return None
+
     def _cell_id(self) -> str:
+        positional = self._positional_cell_id()
+        if positional is not None:
+            return positional
         info = self._cell_info()
         if info is None:
             raise ValidationError(
@@ -2115,6 +2161,11 @@ class _Cell:
                 },
             ),
         )
+        # A merge breaks the uniform-grid assumption the positional cell-id
+        # fast path relies on, so force every subsequent cell address on this
+        # table through the query/walk-back path that aliases secondary slots
+        # to the master.
+        self._table._has_merges = True
         # Return the top-left cell. If self is already the top-left,
         # return self so we keep cached state; otherwise build a fresh
         # _Cell at the top-left address.

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.18.0"
+version = "0.18.2"
 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.2}/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.2}/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

athena_python_docx-0.18.2/tests/test_positional_cell_id.py

@@ -0,0 +1,119 @@
+"""docx-editor cell ids are positional (``tc:tableIndex:row:col``) and are
+computed client-side — no ``tables.get_cells`` round-trip. On docx-editor each
+such query is a full Y.Doc reload (no session pool), so a styled table that
+calls ``set_shading`` / ``set_borders`` per cell used to pay one reload per
+cell. SuperDoc tables (real, non-positional node ids) still resolve via the
+query (SuperDoc is pooled, so that read is cheap).
+
+This mirrors how athena-python-pptx addresses shapes by client-assigned id so
+the whole build buffers into one batch instead of interleaving read-backs.
+
+The fast path is gated to a **known uniform grid**: a table created via
+``Document.add_table`` (``_doc_index`` set) with no merge applied
+(``_has_merges`` falsy). A merged table aliases secondary slots back to the
+top-left master and a read-loaded table may carry template merges we can't
+see — both fall back to the ``tables.get_cells`` walk-back path to stay
+address-correct.
+"""
+
+from __future__ import annotations
+
+
+class _CountingGetCells:
+    """Async ``tables.get_cells`` stub that counts invocations."""
+
+    def __init__(self, cell_id: str = "superdoc_real_cell_id") -> None:
+        self.calls = 0
+        self._cell_id = cell_id
+
+    async def __call__(self, params: dict) -> dict:  # noqa: ARG002
+        self.calls += 1
+        return {"cells": [{"nodeId": self._cell_id, "colspan": 1, "rowspan": 1}]}
+
+
+class _TableStub:
+    def __init__(
+        self,
+        node_id: str,
+        get_cells: _CountingGetCells,
+        *,
+        doc_index: int | None = 0,
+        has_merges: bool = False,
+    ) -> None:
+        self._node_id = node_id
+        # A real ``add_table`` grid sets ``_doc_index``; read-loaded tables
+        # (``doc.tables`` / iteration) leave it ``None``. ``_has_merges`` flips
+        # True once ``_Cell.merge`` is applied.
+        self._doc_index = doc_index
+        self._has_merges = has_merges
+        doc = type("_Doc", (), {"tables": type("_T", (), {"get_cells": get_cells})()})()
+        self._session = type("_S", (), {"doc": doc})()
+
+    def _fresh_node_id(self) -> str:
+        return self._node_id
+
+
+def test_docx_editor_cell_id_is_positional_with_no_query() -> None:
+    from docx.table import _Cell
+
+    gc = _CountingGetCells()
+    table = _TableStub("t:0", gc)
+    cell = _Cell(table=table, row=1, col=2)  # type: ignore[arg-type]
+
+    assert cell._cell_id() == "tc:0:1:2"
+    assert gc.calls == 0  # computed client-side, no tables.get_cells round-trip
+
+
+def test_docx_editor_cell_address_shape_no_query() -> None:
+    from docx.table import _Cell
+
+    gc = _CountingGetCells()
+    table = _TableStub("t:3", gc)
+    cell = _Cell(table=table, row=0, col=0)  # type: ignore[arg-type]
+
+    assert cell._cell_address() == {
+        "kind": "block",
+        "nodeType": "tableCell",
+        "nodeId": "tc:3:0:0",
+    }
+    assert gc.calls == 0
+
+
+def test_superdoc_cell_id_falls_back_to_query() -> None:
+    from docx.table import _Cell
+
+    gc = _CountingGetCells(cell_id="superdoc_real_id")
+    # A real (non-``t:N``) node id is the SuperDoc shape → must resolve via query.
+    table = _TableStub("nodeXYZ123", gc)
+    cell = _Cell(table=table, row=0, col=0)  # type: ignore[arg-type]
+
+    assert cell._cell_id() == "superdoc_real_id"
+    assert gc.calls >= 1
+
+
+def test_merged_table_falls_back_to_query() -> None:
+    from docx.table import _Cell
+
+    # A docx-editor ``t:N`` table that has had a merge applied must NOT
+    # fast-path: the positional id of a secondary slot would skip the
+    # walk-back that aliases it to the merge master.
+    gc = _CountingGetCells(cell_id="tc:0:0:0")  # server resolves to the master
+    table = _TableStub("t:0", gc, has_merges=True)
+    cell = _Cell(table=table, row=0, col=1)  # type: ignore[arg-type]
+
+    assert cell._cell_id() == "tc:0:0:0"  # master, via the query walk-back
+    assert gc.calls >= 1
+
+
+def test_read_loaded_table_falls_back_to_query() -> None:
+    from docx.table import _Cell
+
+    # A read-loaded table (``doc.tables`` / iteration → ``_doc_index is None``)
+    # may carry template merges we can't see, so it must query rather than
+    # assume a uniform grid.
+    gc = _CountingGetCells(cell_id="tc:0:0:1")
+    table = _TableStub("t:0", gc, doc_index=None)
+    cell = _Cell(table=table, row=0, col=1)  # type: ignore[arg-type]
+
+    assert cell._cell_id() == "tc:0:0:1"
+    assert gc.calls >= 1