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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.21.2
+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.2 → 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.2"
+__version__ = "0.21.3"
 
 from docx.api import Document
 from docx._buffer import flush_all

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

@@ -1541,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
@@ -1557,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.2 → athena_python_docx-0.21.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.21.2"
+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.2 → athena_python_docx-0.21.3}/tests/test_positional_cell_id.py

@@ -98,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
 
@@ -124,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
 
@@ -164,7 +201,7 @@ def test_read_loaded_table_falls_back_to_query() -> None:
     assert gc.calls >= 1
 
 
-def test_unflushed_client_table_uses_blocks_list_not_find_for_cell_id() -> None:
+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")
@@ -197,8 +234,8 @@ def test_unflushed_client_table_uses_blocks_list_not_find_for_cell_id() -> None:
     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 table._node_id == "t_client_uuid"
+    assert blocks_list.calls == []
     assert failing_find.calls == 0
 
 

{athena_python_docx-0.21.2 → 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.2 → athena_python_docx-0.21.3}/uv.lock

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