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

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

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

{athena_python_docx-0.21.1 → athena_python_docx-0.21.3}/docx/_buffer.py

@@ -124,10 +124,12 @@ if TYPE_CHECKING:
 # HTTP POST to agora (see ``_ptc._send``), so emitting one card per low-level
 # mutation produces hundreds of sub-cards per script and pays full network
 # RTT on every one. The allow-list keeps the per-action signal — one card
-# per logical block creation (paragraph, heading, table) — without the spam
-# or the cumulative latency. Asset-level creation events (``CreateDocument``)
-# are emitted from ``Document.create`` directly, not through this buffer path.
-_PTC_EMIT_TOOLS: frozenset[str] = frozenset({"CreateParagraph", "CreateHeading", "CreateTable"})
+# per logical block/citation creation — without the spam or the cumulative
+# latency. Asset-level creation events (``CreateDocument``) are emitted from
+# ``Document.create`` directly, not through this buffer path.
+_PTC_EMIT_TOOLS: frozenset[str] = frozenset(
+    {"CreateParagraph", "CreateHeading", "CreateTable", "AddCitation"}
+)
 
 
 def _should_emit_ptc(cmd: Command) -> bool:

{athena_python_docx-0.21.1 → athena_python_docx-0.21.3}/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.3}/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``)
@@ -1504,11 +1541,13 @@ class _Cell:
 
         Reads the proxy's stored ``_node_id`` with NO round-trip. DOCX Studio
         tables carry real (non-``t:N``) node ids → returns ``None`` so the
-        caller queries (DOCX Studio 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.
+        caller queries (DOCX Studio is pooled, so that read is cheap anyway).
+        A freshly-created docx-editor table still holds a client UUID until its
+        create flushes. For docx-editor, :meth:`Document.add_table` already
+        knows the table's eventual document-order index, so SDK-created body
+        tables can fast-path before a fragile first ``tables.get_cells`` query.
+        We first try to flush the pending create so DOCX Studio's non-positional
+        table ids can still fall back to the query path after the id rewrite.
 
         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
@@ -1520,11 +1559,27 @@ class _Cell:
         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):
+        doc_index = getattr(table, "_doc_index", None)
+        if doc_index 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}"
+        if (
+            isinstance(nid, str)
+            and nid.startswith("t_")
+            and getattr(table, "_header_footer_ref_id", None) is None
+        ):
+            handle = getattr(table._session, "_doc_handle", None)
+            buf = getattr(handle, "buffer", None) if handle is not None else None
+            if buf is not None:
+                buf.flush()
+                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}"
+                if not (isinstance(nid, str) and nid.startswith("t_")):
+                    return None
+            return f"tc:{doc_index}:{self._row}:{self._col}"
         return None
 
     def _cell_id(self) -> str:

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.21.1"
+version = "0.21.3"
 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.3}/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.3}/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.3}/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,
@@ -53,6 +98,17 @@ class _TableStub:
         return self._node_id
 
 
+class _RewritingBuffer:
+    def __init__(self, table: _TableStub, real_node_id: str) -> None:
+        self.calls = 0
+        self._table = table
+        self._real_node_id = real_node_id
+
+    def flush(self) -> None:
+        self.calls += 1
+        self._table._node_id = self._real_node_id
+
+
 def test_docx_editor_cell_id_is_positional_with_no_query() -> None:
     from docx.table import _Cell
 
@@ -79,6 +135,32 @@ def test_docx_editor_cell_address_shape_no_query() -> None:
     assert gc.calls == 0
 
 
+def test_fresh_client_id_table_uses_known_doc_index_no_query() -> None:
+    from docx.table import _Cell
+
+    gc = _CountingGetCells()
+    table = _TableStub("t_client_abc", gc, doc_index=4)
+    cell = _Cell(table=table, row=1, col=1)  # type: ignore[arg-type]
+
+    assert cell._cell_id() == "tc:4:1:1"
+    assert gc.calls == 0
+
+
+def test_fresh_client_id_table_flushes_buffer_then_uses_rewritten_positional_id() -> None:
+    from docx.table import _Cell
+
+    gc = _CountingGetCells()
+    table = _TableStub("t_client_abc", gc, doc_index=4)
+    buffer = _RewritingBuffer(table, "t:8")
+    table._session._doc_handle = type("_Handle", (), {"buffer": buffer})()
+    cell = _Cell(table=table, row=1, col=1)  # type: ignore[arg-type]
+
+    assert cell._cell_id() == "tc:8:1:1"
+    assert table._node_id == "t:8"
+    assert buffer.calls == 1
+    assert gc.calls == 0
+
+
 def test_docx_studio_cell_id_falls_back_to_query() -> None:
     from docx.table import _Cell
 
@@ -117,3 +199,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_doc_index_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_client_uuid"
+    assert blocks_list.calls == []
+    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.3}/tests/test_ptc.py

@@ -524,6 +524,41 @@ def test_buffer_emits_for_create_table(monkeypatch: Any) -> None:
     assert calls["end"][0]["is_error"] is False
 
 
+def test_buffer_emits_for_add_citation(monkeypatch: Any) -> None:
+    """``AddCitation`` is allow-listed so agent-authored citations are
+    visible as PTC sub-tool-cards instead of silently only updating the
+    Athena citation layer."""
+    from docx._buffer import CommandBuffer
+    from docx.commands import AddCitation
+
+    calls = _stub_ptc(monkeypatch)
+    client = _FakeHttpClient()
+    buf = CommandBuffer(client, asset_id="asset-1", auto_flush_seconds=0)
+
+    buf.call(
+        AddCitation(
+            destination_anchor={"type": "pm_node", "nodeId": "p_1"},
+            citation_string="/dashboard/spaces/?asset_ids=asset_pdf&type=pdf&page=2",
+            citation_id="citation_abc",
+            excerpt="20,049 total vulnerabilities",
+            display_value="Vulnerability total",
+        )
+    )
+
+    assert len(calls["begin"]) == 1
+    assert calls["begin"][0][0] == "AddCitation"
+    assert calls["begin"][0][1]["citationString"] == (
+        "/dashboard/spaces/?asset_ids=asset_pdf&type=pdf&page=2"
+    )
+    assert calls["begin"][0][3] == "asset-1"
+    assert len(calls["end"]) == 0
+
+    buf.flush()
+    assert len(calls["end"]) == 1
+    assert calls["end"][0]["tool_name"] == "AddCitation"
+    assert calls["end"][0]["is_error"] is False
+
+
 def test_buffer_skips_ptc_for_non_body_creates(monkeypatch: Any) -> None:
     """Allow-listed creates that target a non-body story (header/footer/
     footnote via ``in_``) do NOT emit a PTC card: the frontend locate

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

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