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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.18.1
+Version: 0.18.3
 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.18.1 → athena_python_docx-0.18.3}/docx/__init__.py

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

{athena_python_docx-0.18.1 → athena_python_docx-0.18.3}/docx/_http.py

@@ -100,11 +100,16 @@ def create_empty_document(
         DocxError: any other 4xx/5xx from the server.
     """
     resolved_base: str | None = base_url or os.environ.get(_BASE_URL_ENV)
-    # api_key falls back to ATHENA_API_KEY (the canonical Athena user API
-    # key) so code running in sandboxes that only inject ATHENA_API_KEY
-    # still authenticates without an extra env var.
+    # Create must authenticate as the REAL user so the new asset's ``created_by``
+    # is the user, not a service identity. ``ATHENA_API_KEY`` is the canonical
+    # per-user Athena key (a local API key in BYO/SSO mode that agora resolves to
+    # the real user); the docx-studio studio key (``ATHENA_DOCX_API_KEY``) is a
+    # deployment service credential used only for studio access-checks on
+    # EXISTING assets, and agora's create gate rejects it (no backing user). So
+    # prefer the user key here; only fall back to the studio key for callers that
+    # set just that.
     resolved_key: str | None = (
-        api_key or os.environ.get(_API_KEY_ENV) or os.environ.get("ATHENA_API_KEY")
+        api_key or os.environ.get("ATHENA_API_KEY") or os.environ.get(_API_KEY_ENV)
     )
 
     if not resolved_base:
@@ -263,11 +268,16 @@ def upload_document(
     import uuid
 
     resolved_docx_base: str | None = docx_base_url or os.environ.get(_BASE_URL_ENV)
-    # api_key falls back to ATHENA_API_KEY (the canonical Athena user API
-    # key) so code running in sandboxes that only inject ATHENA_API_KEY
-    # still authenticates without an extra env var.
+    # Create must authenticate as the REAL user so the new asset's ``created_by``
+    # is the user, not a service identity. ``ATHENA_API_KEY`` is the canonical
+    # per-user Athena key (a local API key in BYO/SSO mode that agora resolves to
+    # the real user); the docx-studio studio key (``ATHENA_DOCX_API_KEY``) is a
+    # deployment service credential used only for studio access-checks on
+    # EXISTING assets, and agora's create gate rejects it (no backing user). So
+    # prefer the user key here; only fall back to the studio key for callers that
+    # set just that.
     resolved_key: str | None = (
-        api_key or os.environ.get(_API_KEY_ENV) or os.environ.get("ATHENA_API_KEY")
+        api_key or os.environ.get("ATHENA_API_KEY") or os.environ.get(_API_KEY_ENV)
     )
     resolved_agora_base: str | None = (
         agora_base_url

{athena_python_docx-0.18.1 → athena_python_docx-0.18.3}/docx/table.py

@@ -384,6 +384,11 @@ class Table:
         # ``table-auto-…`` id, followed by ``ValidationError: Cell (r,c)
         # not found`` when a cell access hit the wrong table.
         self._doc_index: int | None = doc_index
+        # Set True once any cell merge is applied through this proxy. The
+        # positional cell-id fast path (``_Cell._positional_cell_id``) is only
+        # valid on a uniform grid, so a merged table must fall back to the
+        # query/walk-back path that aliases secondary slots to the master.
+        self._has_merges: bool = False
         # Header/footer part identity. ``_header_footer_ref_id`` is the
         # relationship id (e.g. ``"rId9"``) returned by
         # ``header_footers.parts.create`` that points the section sectPr
@@ -1490,7 +1495,48 @@ class _Cell:
             return None
         return None
 
+    def _positional_cell_id(self) -> str | None:
+        """Compute the docx-editor cell id (``tc:tableIndex:row:col``)
+        client-side, or return ``None`` to fall back to the query path.
+
+        docx-editor cell ids are purely positional — a function of the
+        table's ``t:N`` id plus grid position — so a cell-format op
+        (``set_shading`` / ``set_borders`` / cell properties) can build its
+        address WITHOUT a ``tables.get_cells`` round-trip. On docx-editor
+        every such query is a full Y.Doc reload (no session pool), so resolving
+        ~one per cell is what makes a styled table slow; this mirrors how
+        athena-python-pptx addresses shapes by client-assigned id so the whole
+        build buffers into one batch.
+
+        Reads the proxy's stored ``_node_id`` with NO round-trip. SuperDoc
+        tables carry real (non-``t:N``) node ids → returns ``None`` so the
+        caller queries (SuperDoc 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.
+
+        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
+        structure is known) AND have no merge applied (``_has_merges``). A
+        merge aliases each secondary slot back to the top-left master — the
+        ``_cell_info`` walk-back is what performs that mapping — so a merged
+        table, or a read-loaded table whose merge state is unknown
+        (``_doc_index is None``, possible template merges we can't see), must
+        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):
+            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}"
+        return None
+
     def _cell_id(self) -> str:
+        positional = self._positional_cell_id()
+        if positional is not None:
+            return positional
         info = self._cell_info()
         if info is None:
             raise ValidationError(
@@ -2115,6 +2161,11 @@ class _Cell:
                 },
             ),
         )
+        # A merge breaks the uniform-grid assumption the positional cell-id
+        # fast path relies on, so force every subsequent cell address on this
+        # table through the query/walk-back path that aliases secondary slots
+        # to the master.
+        self._table._has_merges = True
         # Return the top-left cell. If self is already the top-left,
         # return self so we keep cached state; otherwise build a fresh
         # _Cell at the top-left address.

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

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

@@ -163,3 +163,54 @@ def test_create_request_body_includes_optional_fields() -> None:
         "parentFolderId": "folder_abc",
         "workspaceId": "ws_explicit",
     }
+
+
+def test_create_prefers_user_key_over_studio_key(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """create() authenticates as the user, not the static studio key.
+
+    In self-hosted SSO the executor injects BOTH the static studio key
+    (``ATHENA_DOCX_API_KEY``) and the per-user key (``ATHENA_API_KEY``). create
+    must use the per-user key so the new asset's ``created_by`` is the real
+    user — the studio key is a deployment service credential that agora's
+    create gate rejects (no backing user).
+    """
+    monkeypatch.setenv(
+        "ATHENA_DOCX_BASE_URL",
+        "https://docx-studio.stg.athenaintel.com",
+    )
+    monkeypatch.setenv("ATHENA_DOCX_API_KEY", "studio-static-key")
+    monkeypatch.setenv("ATHENA_API_KEY", "user-local-key")
+    captured: dict[str, Any] = {}
+
+    def _capture(req: Any, **_kwargs: Any) -> _FakeResponse:
+        captured["headers"] = dict(req.headers)
+        return _FakeResponse(json.dumps(_FAKE_RESPONSE).encode("utf-8"))
+
+    with patch("docx._http.urllib.request.urlopen", side_effect=_capture):
+        Document.create(name="X")
+
+    assert captured["headers"]["Authorization"] == "Bearer user-local-key"
+
+
+def test_create_falls_back_to_studio_key_without_user_key(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """With only the studio key configured, create still authenticates with it."""
+    monkeypatch.setenv(
+        "ATHENA_DOCX_BASE_URL",
+        "https://docx-studio.stg.athenaintel.com",
+    )
+    monkeypatch.setenv("ATHENA_DOCX_API_KEY", "studio-static-key")
+    monkeypatch.delenv("ATHENA_API_KEY", raising=False)
+    captured: dict[str, Any] = {}
+
+    def _capture(req: Any, **_kwargs: Any) -> _FakeResponse:
+        captured["headers"] = dict(req.headers)
+        return _FakeResponse(json.dumps(_FAKE_RESPONSE).encode("utf-8"))
+
+    with patch("docx._http.urllib.request.urlopen", side_effect=_capture):
+        Document.create(name="X")
+
+    assert captured["headers"]["Authorization"] == "Bearer studio-static-key"

athena_python_docx-0.18.3/tests/test_positional_cell_id.py

@@ -0,0 +1,119 @@
+"""docx-editor cell ids are positional (``tc:tableIndex:row:col``) and are
+computed client-side — no ``tables.get_cells`` round-trip. On docx-editor each
+such query is a full Y.Doc reload (no session pool), so a styled table that
+calls ``set_shading`` / ``set_borders`` per cell used to pay one reload per
+cell. SuperDoc tables (real, non-positional node ids) still resolve via the
+query (SuperDoc is pooled, so that read is cheap).
+
+This mirrors how athena-python-pptx addresses shapes by client-assigned id so
+the whole build buffers into one batch instead of interleaving read-backs.
+
+The fast path is gated to a **known uniform grid**: a table created via
+``Document.add_table`` (``_doc_index`` set) with no merge applied
+(``_has_merges`` falsy). A merged table aliases secondary slots back to the
+top-left master and a read-loaded table may carry template merges we can't
+see — both fall back to the ``tables.get_cells`` walk-back path to stay
+address-correct.
+"""
+
+from __future__ import annotations
+
+
+class _CountingGetCells:
+    """Async ``tables.get_cells`` stub that counts invocations."""
+
+    def __init__(self, cell_id: str = "superdoc_real_cell_id") -> None:
+        self.calls = 0
+        self._cell_id = cell_id
+
+    async def __call__(self, params: dict) -> dict:  # noqa: ARG002
+        self.calls += 1
+        return {"cells": [{"nodeId": self._cell_id, "colspan": 1, "rowspan": 1}]}
+
+
+class _TableStub:
+    def __init__(
+        self,
+        node_id: str,
+        get_cells: _CountingGetCells,
+        *,
+        doc_index: int | None = 0,
+        has_merges: bool = False,
+    ) -> None:
+        self._node_id = node_id
+        # A real ``add_table`` grid sets ``_doc_index``; read-loaded tables
+        # (``doc.tables`` / iteration) leave it ``None``. ``_has_merges`` flips
+        # True once ``_Cell.merge`` is applied.
+        self._doc_index = doc_index
+        self._has_merges = has_merges
+        doc = type("_Doc", (), {"tables": type("_T", (), {"get_cells": get_cells})()})()
+        self._session = type("_S", (), {"doc": doc})()
+
+    def _fresh_node_id(self) -> str:
+        return self._node_id
+
+
+def test_docx_editor_cell_id_is_positional_with_no_query() -> None:
+    from docx.table import _Cell
+
+    gc = _CountingGetCells()
+    table = _TableStub("t:0", gc)
+    cell = _Cell(table=table, row=1, col=2)  # type: ignore[arg-type]
+
+    assert cell._cell_id() == "tc:0:1:2"
+    assert gc.calls == 0  # computed client-side, no tables.get_cells round-trip
+
+
+def test_docx_editor_cell_address_shape_no_query() -> None:
+    from docx.table import _Cell
+
+    gc = _CountingGetCells()
+    table = _TableStub("t:3", gc)
+    cell = _Cell(table=table, row=0, col=0)  # type: ignore[arg-type]
+
+    assert cell._cell_address() == {
+        "kind": "block",
+        "nodeType": "tableCell",
+        "nodeId": "tc:3:0:0",
+    }
+    assert gc.calls == 0
+
+
+def test_superdoc_cell_id_falls_back_to_query() -> None:
+    from docx.table import _Cell
+
+    gc = _CountingGetCells(cell_id="superdoc_real_id")
+    # A real (non-``t:N``) node id is the SuperDoc shape → must resolve via query.
+    table = _TableStub("nodeXYZ123", gc)
+    cell = _Cell(table=table, row=0, col=0)  # type: ignore[arg-type]
+
+    assert cell._cell_id() == "superdoc_real_id"
+    assert gc.calls >= 1
+
+
+def test_merged_table_falls_back_to_query() -> None:
+    from docx.table import _Cell
+
+    # A docx-editor ``t:N`` table that has had a merge applied must NOT
+    # fast-path: the positional id of a secondary slot would skip the
+    # walk-back that aliases it to the merge master.
+    gc = _CountingGetCells(cell_id="tc:0:0:0")  # server resolves to the master
+    table = _TableStub("t:0", gc, has_merges=True)
+    cell = _Cell(table=table, row=0, col=1)  # type: ignore[arg-type]
+
+    assert cell._cell_id() == "tc:0:0:0"  # master, via the query walk-back
+    assert gc.calls >= 1
+
+
+def test_read_loaded_table_falls_back_to_query() -> None:
+    from docx.table import _Cell
+
+    # A read-loaded table (``doc.tables`` / iteration → ``_doc_index is None``)
+    # may carry template merges we can't see, so it must query rather than
+    # assume a uniform grid.
+    gc = _CountingGetCells(cell_id="tc:0:0:1")
+    table = _TableStub("t:0", gc, doc_index=None)
+    cell = _Cell(table=table, row=0, col=1)  # type: ignore[arg-type]
+
+    assert cell._cell_id() == "tc:0:0:1"
+    assert gc.calls >= 1

{athena_python_docx-0.18.1 → athena_python_docx-0.18.3}/uv.lock

@@ -21,7 +21,7 @@ wheels = [
 
 [[package]]
 name = "athena-python-docx"
-version = "0.15.2"
+version = "0.18.3"
 source = { editable = "." }
 dependencies = [
     { name = "requests" },