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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.17.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.17.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.17.0"
+__version__ = "0.18.1"
 
 from docx.api import Document
 from docx._buffer import flush_all

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

@@ -386,10 +386,18 @@ class Document:
         for b in blocks:
             if not isinstance(b, dict):
                 continue
+            nt_raw = b.get("nodeType")
+            nt: str = nt_raw if isinstance(nt_raw, str) and nt_raw else "paragraph"
+            # Tables belong to ``Document.tables``, never ``Document.paragraphs``
+            # (python-docx parity). The server honors the ``nodeTypes`` filter,
+            # but defend against an unfiltered response too: skip table blocks so
+            # they never surface here as Paragraph proxies (each would otherwise
+            # cost 3 live reads in a paragraph loop). Denylist, not allowlist, so
+            # we don't drop paragraph-like types we don't explicitly know.
+            if nt == "table":
+                continue
             node_id: str = str(b.get("nodeId", ""))
             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
@@ -455,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,
                 },
             ),
         )
@@ -480,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
@@ -2202,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.17.0 → athena_python_docx-0.18.1}/docx/text/run.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 from typing import TYPE_CHECKING, Any, BinaryIO
 
 from docx._athena_extension import athena_extension
@@ -9,6 +10,14 @@ from docx._batching import run_sync
 from docx.enum.text import WD_BREAK
 from docx.shared import Length, Pt, RGBColor  # noqa: F401
 
+# docx-editor addresses cell-inner paragraphs by the cell's synthetic id
+# (``tc:tableIndex:row:col``) because cell paragraphs carry no paraId. Its
+# applier routes a ``FormatApply`` against such an id to a positional
+# whole-cell mark, so cell-inner run formatting can apply live. SuperDoc cell
+# ids are not ``tc:``-shaped, so this discriminator leaves the SuperDoc
+# warn-and-skip path (post-export OOXML rewrite only) untouched.
+_DOCX_EDITOR_CELL_ID_RE = re.compile(r"^tc:\d+:\d+:\d+$")
+
 
 class PendingBreakDegradationWarning(UserWarning):
     """Emitted when ``Run.add_break`` is called with a break type that
@@ -970,12 +979,27 @@ class Run:
         # has text — see ``_pending_inline`` in ``__init__`` for the
         # python-docx parity rationale.
         if getattr(self, "_in_cell", False):
-            # Cell-inner runs cannot apply formatting at the live wire
-            # layer (SuperDoc 1.8.1 rejects ``doc.format.apply`` for
-            # paragraphs nested inside ``tableCell``). Stash for the
-            # post-export OOXML rewrite BEFORE we emit the warning so
-            # the formatting still lands in the exported ``.docx``.
+            # Stash for the post-export OOXML rewrite FIRST so the formatting
+            # lands in the exported ``.docx`` regardless of engine (and is the
+            # only path on the legacy SuperDoc engine, which rejects
+            # ``doc.format.apply`` for paragraphs nested inside ``tableCell``).
             self._stash_cell_inner_run_format(kwargs)
+            # docx-editor CAN apply cell-inner formatting live: it addresses
+            # the cell paragraph by the cell's synthetic id and routes a
+            # ``FormatApply`` against that id to a positional whole-cell mark.
+            # Ship it so collaborators see the change immediately instead of
+            # only at export. The ``tc:``-shape discriminator keeps the
+            # SuperDoc warn-and-skip path intact (its cell ids differ).
+            block_id = getattr(self, "_block_id", "")
+            if isinstance(block_id, str) and _DOCX_EDITOR_CELL_ID_RE.match(
+                block_id,
+            ):
+                run_sync(
+                    self._session.doc.format.apply(
+                        {"target": self._text_range, "inline": kwargs},
+                    ),
+                )
+                return
             self._check_cell_inner(
                 "font/format (bold/italic/font.size/etc.)",
             )

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

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

@@ -121,6 +121,11 @@ class FakeDocState:
         self.sections: list[_Section] = [_Section("sec_1")]
         self.images: list[dict] = []
         self.calls: list[tuple[str, dict]] = []
+        # When True, ``blocks.list`` ignores the requested ``nodeTypes`` and
+        # returns every block (tables included), simulating the docx-editor
+        # server before it honored the filter. Lets tests verify the SDK's own
+        # table denylist in ``Document.paragraphs``.
+        self.blocks_list_ignore_node_types: bool = False
 
     def _new_id(self, prefix: str) -> str:
         return f"{prefix}_{next(self._ids)}"
@@ -296,6 +301,10 @@ class FakeDocState:
 
         if op == "blocks.list":
             types = params.get("nodeTypes") or None
+            # Simulate the pre-fix docx-editor server that ignored the filter and
+            # returned every block (tables included), to exercise the SDK denylist.
+            if self.blocks_list_ignore_node_types:
+                types = None
             include_runs = bool(params.get("includeRuns"))
             out_blocks: list[dict] = []
             for b in self.blocks:

{athena_python_docx-0.17.0 → athena_python_docx-0.18.1}/tests/test_cell_inner_run_format_stash.py

@@ -281,3 +281,82 @@ def test_paragraph_add_run_returns_run_carrying_cell_ooxml_address(
         r = p.add_run("hello")
     assert r._in_cell is True
     assert r._cell_ooxml_address == (None, 5, 2, 1, 0)
+
+
+# ---- docx-editor live-ship path (block_id is a `tc:` synthetic cell id) ----
+
+
+def _make_docx_editor_cell_run(
+    mock_session: Any,
+    *,
+    cell_ooxml_address: tuple[int | None, int, int, int, int] | None = None,
+) -> Any:
+    """A cell-inner Run whose ``block_id`` is the docx-editor synthetic cell
+    id (``tc:table:row:col``) — the shape ``cell.paragraphs[].runs`` produce
+    on the docx-editor engine, where cell paragraphs have no paraId."""
+    from docx.text.run import Run
+
+    return Run(
+        session=mock_session,
+        block_id="tc:0:1:2",
+        range_=(0, 5),
+        in_cell=True,
+        cell_ooxml_address=cell_ooxml_address,
+    )
+
+
+def test_docx_editor_cell_run_font_size_ships_format_apply_live(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    """On docx-editor, setting ``run.font.size`` on a cell-inner run ships a
+    live ``format.apply`` targeting the cell's synthetic id — no warn-and-skip.
+    The applier routes that target to a positional whole-cell mark."""
+    from docx.shared import Pt
+
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always", CellInnerFormatNotSupportedWarning)
+        r = _make_docx_editor_cell_run(mock_session)
+        r.font.size = Pt(9)
+        warned = [
+            x for x in w if issubclass(x.category, CellInnerFormatNotSupportedWarning)
+        ]
+    # No warn-and-skip on docx-editor — it applies live.
+    assert warned == []
+    format_apply_ops = [c for c in fake_sd_methods.calls if c[0] == "format.apply"]
+    assert len(format_apply_ops) == 1
+    _, params = format_apply_ops[0]
+    assert params["target"]["blockId"] == "tc:0:1:2"
+    assert params["target"]["range"] == {"start": 0, "end": 5}
+    assert params["inline"] == {"fontSize": 9.0}
+
+
+def test_docx_editor_cell_run_bold_ships_format_apply_live(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    r = _make_docx_editor_cell_run(mock_session)
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", CellInnerFormatNotSupportedWarning)
+        r.bold = True
+    format_apply_ops = [c for c in fake_sd_methods.calls if c[0] == "format.apply"]
+    assert len(format_apply_ops) == 1
+    assert format_apply_ops[0][1]["inline"] == {"bold": True}
+
+
+def test_docx_editor_cell_run_still_stashes_for_export_when_addressable(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    """When the parent table was created in-session (cell_ooxml_address set),
+    the run both ships live AND stashes for the post-export OOXML rewrite, so
+    ``export_docx`` carries the formatting too."""
+    from docx.shared import Pt
+
+    ops = _attach_real_post_export_ops(mock_session)
+    r = _make_docx_editor_cell_run(mock_session, cell_ooxml_address=(None, 0, 1, 2, 0))
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", CellInnerFormatNotSupportedWarning)
+        r.font.size = Pt(9)
+    # Live wire call shipped.
+    assert any(c[0] == "format.apply" for c in fake_sd_methods.calls)
+    # AND stashed for export fidelity.
+    addr = CellAddress(table_doc_index=0, row=1, col=2, paragraph_index=0)
+    assert ops._cell_run_format_ops[addr]["font_size_pt"] == 9.0

{athena_python_docx-0.17.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.17.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
@@ -133,6 +170,31 @@ def test_document_tables_uses_lightweight_block_listing() -> None:
     assert not any(op == "find" and params == {"type": "table"} for op, params in calls)
 
 
+def test_document_paragraphs_excludes_tables_even_if_server_unfiltered() -> None:
+    """``Document.paragraphs`` must never return tables (python-docx parity).
+    The docx-editor server now honors the ``nodeTypes`` filter, but the SDK also
+    denylists table blocks defensively — verified here by simulating the pre-fix
+    server that returned every block regardless of the requested ``nodeTypes``."""
+    install_fake_session()
+    from docx import Document
+    from docx.text.paragraph import Paragraph
+
+    doc = Document("asset_fake")
+    doc.add_paragraph("Body one")
+    doc.add_paragraph("Body two")
+    doc.add_table(rows=2, cols=2)
+
+    # Simulate the unfiltered docx-editor server (tables leak into the response).
+    doc._session.state().blocks_list_ignore_node_types = True
+
+    paras = doc.paragraphs
+    # Every returned item is a Paragraph and NONE is a table block.
+    assert all(isinstance(p, Paragraph) for p in paras)
+    assert all(p._node_type != "table" for p in paras)
+    # Exactly the two body paragraphs — the table is excluded.
+    assert len(paras) == 2
+
+
 def test_paragraph_iter_inner_content_yields_runs() -> None:
     install_fake_session()
     from docx import Document