athena-python-docx 0.21.1__tar.gz → 0.21.2__tar.gz

{athena_python_docx-0.21.1 → athena_python_docx-0.21.2}/PKG-INFO

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

{athena_python_docx-0.21.1 → athena_python_docx-0.21.2}/docx/__init__.py

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

{athena_python_docx-0.21.1 → athena_python_docx-0.21.2}/docx/_citations.py

@@ -53,6 +53,11 @@ def normalize_citation_string(citation_string: str) -> str:
 
     if not parsed.scheme and value.startswith("/"):
         relative = urlparse(value)
+        if relative.netloc:
+            raise ValueError(
+                "protocol-relative Athena Spaces citation URLs are not allowed; "
+                "use an absolute Athena host"
+            )
         if relative.path.rstrip("/") == "/dashboard/spaces":
             asset_ids = parse_qs(relative.query).get("asset_ids")
             if asset_ids and asset_ids[0]:

{athena_python_docx-0.21.1 → athena_python_docx-0.21.2}/docx/table.py

@@ -108,6 +108,37 @@ def _normalize_border_spec(spec: "dict | str | None", *, edge: str) -> "dict | N
     )
 
 
+def _table_node_id_from_item(item: object) -> str | None:
+    if not isinstance(item, dict):
+        return None
+    addr = item.get("address")
+    if isinstance(addr, dict):
+        nid = addr.get("nodeId")
+        if isinstance(nid, str) and nid:
+            return nid
+    nid = item.get("nodeId")
+    if isinstance(nid, str) and nid:
+        return nid
+    return None
+
+
+def _table_items_from_blocks_list_result(result: object) -> list[dict]:
+    if isinstance(result, dict):
+        blocks_obj: object = result.get("blocks", [])
+        blocks = blocks_obj if isinstance(blocks_obj, list) else []
+    elif isinstance(result, list):
+        blocks = result
+    else:
+        blocks = []
+    return [
+        block
+        for block in blocks
+        if isinstance(block, dict)
+        and block.get("nodeType") == "table"
+        and _table_node_id_from_item(block)
+    ]
+
+
 if TYPE_CHECKING:
     from docx.client import Session
     from docx.enum.table import (
@@ -474,25 +505,33 @@ class Table:
                 return self._node_id, info
         except Exception:
             pass
-        # Fallback: scan top-level tables via doc.find. The find result is
-        # in document order, so a Table created by ``Document.add_table``
-        # — which always appends to ``documentEnd`` — can be located by
-        # its stored ``_doc_index`` (the position it had at creation
-        # time, captured from the in-session counter at append time).
-        # That preserves the 1:1 mapping between proxy and server table
-        # across rotations, instead of the pre-0.11.4 "take the last
-        # item" heuristic that collapsed N rotated proxies onto one
-        # target.
-        find_result: object = run_sync(
-            self._session.doc.find({"type": "table"}),
-        )
-        items_obj: object = find_result.get("items", []) if isinstance(find_result, dict) else []
-        items: list = items_obj if isinstance(items_obj, list) else []
+        # Fallback: scan top-level tables in document order. Prefer
+        # ``blocks.list`` because docx-editor supports it on the same engine
+        # path used by ``Document.tables``; ``doc.find({"type": "table"})`` is
+        # not implemented by older docx-editor appliers and caused immediate
+        # failures when agents styled a freshly-created table cell. Keep
+        # ``doc.find`` only as a compatibility fallback for transports that
+        # do not expose ``blocks.list``.
+        items: list = []
+        try:
+            blocks_result: object = run_sync(
+                self._session.doc.blocks.list(
+                    {"nodeTypes": ["table"], "includeText": False},
+                ),
+            )
+            items = _table_items_from_blocks_list_result(blocks_result)
+        except Exception as exc:  # noqa: BLE001
+            _log_debug(f"table rotation lookup via blocks.list failed: {type(exc).__name__}: {exc}")
+        if not items:
+            find_result: object = run_sync(
+                self._session.doc.find({"type": "table"}),
+            )
+            items_obj: object = find_result.get("items", []) if isinstance(find_result, dict) else []
+            raw_items: list = items_obj if isinstance(items_obj, list) else []
+            items = [item for item in raw_items if isinstance(item, dict)]
         for item in items:
-            if not isinstance(item, dict):
-                continue
-            addr = item.get("address", {})
-            if isinstance(addr, dict) and addr.get("nodeId") == self._node_id:
+            nid = _table_node_id_from_item(item)
+            if nid == self._node_id:
                 info_obj = run_sync(
                     self._session.doc.tables.get({"nodeId": self._node_id}),
                 )
@@ -522,17 +561,15 @@ class Table:
         ):
             pos = len(items) - session_count + self._doc_index
             cand = items[pos]
-            if isinstance(cand, dict):
-                ca = cand.get("address", {})
-                if isinstance(ca, dict) and ca.get("nodeId"):
-                    rotated_addr = ca
+            cand_id = _table_node_id_from_item(cand)
+            if cand_id:
+                rotated_addr = {"nodeId": cand_id}
         elif len(items) == 1:
             # Unambiguous: only one table in the doc.
             cand = items[0]
-            if isinstance(cand, dict):
-                ca = cand.get("address", {})
-                if isinstance(ca, dict) and ca.get("nodeId"):
-                    rotated_addr = ca
+            cand_id = _table_node_id_from_item(cand)
+            if cand_id:
+                rotated_addr = {"nodeId": cand_id}
         else:
             # Multi-table doc, ``_doc_index`` unknown (proxy resolved
             # via iteration / find rather than ``Document.add_table``)

{athena_python_docx-0.21.1 → athena_python_docx-0.21.2}/pyproject.toml

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

{athena_python_docx-0.21.1 → athena_python_docx-0.21.2}/tests/fidelity/firm_templates/test_pw_corpus.py

@@ -52,8 +52,7 @@ class CorpusDoc:
 
 # Per-doc captured scorecards. Captured 2026-05-17 from the corpus
 # source files via ``extractor.py``; these values pin the round-trip
-# output too (the bytes-in == bytes-out guarantee for everything
-# except Purchase_Agreement, which is xfailed below).
+# output too (the bytes-in == bytes-out guarantee for everything).
 CORPUS: list[CorpusDoc] = [
     CorpusDoc(
         label="AI_Research_Digest",
@@ -246,15 +245,6 @@ CORPUS: list[CorpusDoc] = [
             paragraph_style_defs=119, character_style_defs=54,
             table_style_defs=2, custom_style_defs=118, image_files=0,
         ),
-        xfail_reason=(
-            "DOCX Studio § 18 strips REF field codes on import: 1989 → 1974 "
-            "bookmarks (15 _9kMxxx co-author bookmarks dropped) AND every "
-            "REF cross-reference's visible result text disappears, leaving "
-            'definitions like "Estimated Cash shall have the meaning set forth in" '
-            "without their trailing Section reference. Pinned strict so a DOCX Studio "
-            "fix surfaces as UNEXPECTED PASS. See docs/PW_CORPUS_FIDELITY_ASSESSMENT.md "
-            "§ 3 and DOCX_STUDIO_LIMITATIONS.md § 18."
-        ),
     ),
 ]
 
@@ -335,9 +325,7 @@ def test_round_trip_preserves_scorecard(
 ) -> None:
     """The DOCX Studio round-trip must preserve the per-doc scorecard.
 
-    Docs in the ``xfail_reason`` regime are marked ``xfail(strict=True)``
-    — currently only the Harvey Purchase Agreement, which loses all 301
-    REF field result texts (see DOCX Studio upstream § 18).
+    Docs in the ``xfail_reason`` regime are marked ``xfail(strict=True)``.
     """
     # Make sure bun + corpus are available; otherwise skip with a clean
     # reason. ``require_case`` raises a pytest.skip on missing source.

{athena_python_docx-0.21.1 → athena_python_docx-0.21.2}/tests/test_citations.py

@@ -279,6 +279,7 @@ def test_add_citation_rejects_non_reference_source() -> None:
         "mailto:source@example.com",
         "https://",
         "https://example.com/dashboard/spaces/?asset_ids=asset_pdf",
+        "//evil.com/dashboard/spaces/?asset_ids=asset_pdf",
     ):
         with pytest.raises(ValueError, match="citation_string|asset_ids|Athena host"):
             paragraph.add_citation(source)  # type: ignore[arg-type]

{athena_python_docx-0.21.1 → athena_python_docx-0.21.2}/tests/test_positional_cell_id.py

@@ -19,6 +19,15 @@ address-correct.
 from __future__ import annotations
 
 
+class _RecordingSession:
+    def __init__(self) -> None:
+        self.commands: list[object] = []
+
+    async def send_command(self, command: object) -> dict:
+        self.commands.append(command)
+        return {}
+
+
 class _CountingGetCells:
     """Async ``tables.get_cells`` stub that counts invocations."""
 
@@ -31,6 +40,42 @@ class _CountingGetCells:
         return {"cells": [{"nodeId": self._cell_id, "colspan": 1, "rowspan": 1}]}
 
 
+class _CountingTablesGet:
+    """Async ``tables.get`` stub that records node-id lookups."""
+
+    def __init__(self, table_info_by_id: dict[str, dict] | None = None) -> None:
+        self.calls: list[dict] = []
+        self._table_info_by_id = table_info_by_id or {}
+
+    async def __call__(self, params: dict) -> dict:
+        self.calls.append(params)
+        node_id = params.get("nodeId")
+        if isinstance(node_id, str):
+            return self._table_info_by_id.get(node_id, {})
+        return {}
+
+
+class _CountingBlocksList:
+    """Async ``blocks.list`` stub used by table rotation fallback tests."""
+
+    def __init__(self, blocks: list[dict]) -> None:
+        self.calls: list[dict] = []
+        self._blocks = blocks
+
+    async def __call__(self, params: dict) -> dict:
+        self.calls.append(params)
+        return {"blocks": list(self._blocks)}
+
+
+class _FailingFind:
+    def __init__(self) -> None:
+        self.calls = 0
+
+    async def __call__(self, params: dict) -> dict:  # noqa: ARG002
+        self.calls += 1
+        raise AssertionError("doc.find should not be used when blocks.list resolves tables")
+
+
 class _TableStub:
     def __init__(
         self,
@@ -117,3 +162,63 @@ def test_read_loaded_table_falls_back_to_query() -> None:
 
     assert cell._cell_id() == "tc:0:0:1"
     assert gc.calls >= 1
+
+
+def test_unflushed_client_table_uses_blocks_list_not_find_for_cell_id() -> None:
+    from docx.table import Table, _Cell
+
+    get_cells = _CountingGetCells(cell_id="tc:0:0:0")
+    tables_get = _CountingTablesGet(
+        table_info_by_id={
+            "t:0": {"nodeId": "t:0", "rows": 2, "columns": 2},
+        },
+    )
+    blocks_list = _CountingBlocksList(
+        blocks=[
+            {"nodeType": "table", "nodeId": "t:0"},
+        ],
+    )
+    failing_find = _FailingFind()
+    doc = type(
+        "_Doc",
+        (),
+        {
+            "tables": type(
+                "_Tables",
+                (),
+                {"get": tables_get, "get_cells": get_cells},
+            )(),
+            "blocks": type("_Blocks", (), {"list": blocks_list})(),
+            "find": failing_find,
+        },
+    )()
+    session = type("_S", (), {"doc": doc})()
+    table = Table(session=session, node_id="t_client_uuid", rows=2, columns=2, doc_index=0)
+    cell = _Cell(table=table, row=0, col=0)
+
+    assert cell._cell_id() == "tc:0:0:0"
+    assert table._node_id == "t:0"
+    assert blocks_list.calls == [{"nodeTypes": ["table"], "includeText": False}]
+    assert failing_find.calls == 0
+
+
+def test_set_shading_uses_positional_cell_target_without_query() -> None:
+    from docx.table import Table, _Cell
+
+    session = _RecordingSession()
+    table = Table(session=session, node_id="t:2", rows=2, columns=2, doc_index=2)
+    cell = _Cell(table=table, row=0, col=1)
+
+    cell.set_shading(fill="1F497D")
+
+    assert len(session.commands) == 1
+    command = session.commands[0]
+    assert command.to_dict() == {
+        "type": "SetCellShading",
+        "target": {
+            "kind": "block",
+            "nodeType": "tableCell",
+            "nodeId": "tc:2:0:1",
+        },
+        "fill": "1F497D",
+    }

{athena_python_docx-0.21.1 → athena_python_docx-0.21.2}/uv.lock

@@ -8,7 +8,7 @@ resolution-markers = [
 
 [[package]]
 name = "athena-python-docx"
-version = "0.21.0"
+version = "0.21.1"
 source = { editable = "." }
 dependencies = [
     { name = "athena-references" },