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

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

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

{athena_python_docx-0.17.0 → athena_python_docx-0.18.0}/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

{athena_python_docx-0.17.0 → athena_python_docx-0.18.0}/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.0}/pyproject.toml

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

@@ -133,6 +133,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