athena-python-docx 0.11.0__tar.gz → 0.11.1__tar.gz

{athena_python_docx-0.11.0 → athena_python_docx-0.11.1}/PKG-INFO

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

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

{athena_python_docx-0.11.0 → athena_python_docx-0.11.1}/docx/_http_doc.py

@@ -186,22 +186,32 @@ _NOT_FOUND_ERROR_NAMES: frozenset[str] = frozenset(
 
 
 def _looks_like_block_not_found(err_obj: dict) -> bool:
-    """Detect SuperDoc's ``Block "<type>:<id>" was not found`` shape.
+    """Detect SuperDoc's cell-inner-paragraph addressing failures.
 
-    Triggers the typed :class:`BlockNotFoundError` so agent code can
-    distinguish a missing-block miss (cell-inner-paragraph addressing
-    bug, stale id from a different session) from a generic transport
-    or validation error.
+    SuperDoc emits two shapes for the same underlying gap
+    (``SUPERDOC_UPSTREAM_REQUESTS.md`` § 13):
+
+    * ``Block "paragraph:<uuid>" was not found.`` — older "not found" form.
+    * ``INVALID_TARGET - Expected paragraph:<uuid> but found tableCell:<id>.``
+      — newer type-mismatch form, surfaced when the supplied paragraph
+      anchor resolves to its containing ``tableCell`` instead.
+
+    Both surface as :class:`BlockNotFoundError` so agent code can route
+    them through the same cell-paragraph hint path.
     """
     msg = err_obj.get("message")
     if not isinstance(msg, str):
         return False
     lower = msg.lower()
-    if "not found" not in lower:
-        return False
-    # Be conservative: require either ``block "`` (the SuperDoc CLI's
-    # quoted-id format) or ``block <id>`` followed by ``not found``.
-    return 'block "' in lower or ('block ' in lower and ' was not found' in lower)
+    if "not found" in lower:
+        return 'block "' in lower or (
+            'block ' in lower and ' was not found' in lower
+        )
+    if "invalid_target" in lower or "invalid target" in lower:
+        # "Expected paragraph:<id> but found tableCell:<id>" — the new
+        # variant of the § 13 cell-inner-paragraph addressing gap.
+        return "but found tablecell" in lower
+    return False
 
 
 # Commands that target a paragraph block (or its inline range) and
@@ -239,6 +249,11 @@ _PARAGRAPH_TARGETING_COMMANDS: frozenset[str] = frozenset(
         "Replace",
         "InsertLineBreak",
         "InsertTab",
+        # Create-* anchor-into-cell-inner-paragraph variant of § 13.
+        "CreateParagraph",
+        "CreateHeading",
+        "CreateTable",
+        "CreateImage",
     }
 )
 

{athena_python_docx-0.11.0 → athena_python_docx-0.11.1}/docx/table.py

@@ -1345,23 +1345,24 @@ class _Cell:
         only ``str`` was honored and passing a ``ParagraphStyle`` got
         ``repr()``'d into the style id slot, silently producing a
         paragraph with a garbage style reference.
+
+        Routes through ``doc.insert`` with the cell itself as the
+        target and ``placement: 'insideEnd'`` — mirroring the wire
+        path that ``_Cell.text`` uses. SuperDoc 1.8.1 cannot resolve a
+        ``create.paragraph`` ``at`` anchor that points at a cell-inner
+        paragraph (SUPERDOC_UPSTREAM_REQUESTS.md § 13); attempting it
+        raises ``INVALID_TARGET - Expected paragraph:<id> but found
+        tableCell:<id>``.
         """
         from docx.document import _extract_inserted_node_id
         from docx.styles.style import ParagraphStyle
         from docx.text.paragraph import Paragraph
 
-        # python-docx 1.x: ``text`` is ``str`` (lxml TypeErrors on
-        # non-str). Was: any value flowed straight to the wire
-        # ``text`` field — SuperDoc's permissive parser swallowed or
-        # rejected silently.
         if not isinstance(text, str):
             raise TypeError(
                 f"_Cell.add_paragraph text requires str; got "
                 f"{type(text).__name__} {text!r}",
             )
-        # ``style`` is ``str | ParagraphStyle | None``. Was: catch-all
-        # ``str(style)`` shipped garbage like ``"<MyStyle object at
-        # 0x...>"`` as a style id — Word silently fell back to Normal.
         style_id: str | None
         if style is None:
             style_id = None
@@ -1376,38 +1377,49 @@ class _Cell:
                 f"{type(style).__name__} {style!r}",
             )
 
-        ids = self._inner_paragraph_ids()
-        if ids:
-            anchor = {
-                "kind": "after",
-                "target": {
-                    "kind": "block",
-                    "nodeType": "paragraph",
-                    "nodeId": ids[-1],
-                },
-            }
-        else:
-            # No paragraphs yet — create one inside the cell (sibling of cell
-            # is invalid; fall back to documentEnd and accept degraded placement).
-            anchor = {"kind": "documentEnd"}
+        fragment: dict = {
+            "kind": "paragraph",
+            "paragraph": {
+                "inlines": (
+                    [{"kind": "run", "run": {"text": text}}]
+                    if text
+                    else []
+                ),
+            },
+        }
 
+        session = self._table._session
+        cell_id = self._cell_id()
         result: object = run_sync(
-            self._table._session.doc.create.paragraph(
-                {"text": text, "at": anchor},
+            session.doc.insert(
+                {
+                    "target": {
+                        "kind": "block",
+                        "nodeType": "tableCell",
+                        "nodeId": cell_id,
+                    },
+                    "placement": "insideEnd",
+                    "content": fragment,
+                },
             ),
         )
+
+        node_id: str = ""
         if isinstance(result, dict):
-            node_id: str = _extract_inserted_node_id(
+            node_id = _extract_inserted_node_id(
                 result, expected_type="paragraph",
             )
-        else:
-            node_id = ""
+        if not node_id:
+            ids = self._inner_paragraph_ids()
+            if ids:
+                node_id = ids[-1]
         if not node_id:
             raise RuntimeError(
-                f"Superdoc did not return nodeId for _Cell.add_paragraph: {result!r}",
+                f"docx-studio did not return nodeId for "
+                f"_Cell.add_paragraph (cell={cell_id!r}): {result!r}",
             )
         para = Paragraph(
-            session=self._table._session,
+            session=session,
             node_id=node_id,
             node_type="paragraph",
         )

{athena_python_docx-0.11.0 → athena_python_docx-0.11.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.11.0"
+version = "0.11.1"
 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.11.0 → athena_python_docx-0.11.1}/tests/fidelity/op_snapshots/22_table_cell_paragraphs_iteration.json

@@ -3,8 +3,10 @@
   "tables.setCell",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "tables.get",
   "tables.getCells",
   "getNodeById",

{athena_python_docx-0.11.0 → athena_python_docx-0.11.1}/tests/fidelity/op_snapshots/62_many_cell_paragraphs.json

@@ -2,24 +2,34 @@
   "create.table",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
+  "tables.get",
+  "tables.getCells",
+  "insert",
   "tables.get",
   "tables.getCells",
   "getNodeById",
-  "create.paragraph",
+  "tables.get",
+  "tables.getCells",
+  "insert",
   "tables.get",
   "tables.getCells",
   "getNodeById",
-  "create.paragraph",
+  "tables.get",
+  "tables.getCells",
+  "insert",
   "tables.get",
   "tables.getCells",
   "getNodeById",
-  "create.paragraph",
+  "tables.get",
+  "tables.getCells",
+  "insert",
   "tables.get",
   "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "tables.get",
   "tables.getCells",
   "getNodeById",

{athena_python_docx-0.11.0 → athena_python_docx-0.11.1}/tests/fidelity/op_snapshots/69_newsletter.json

@@ -38,20 +38,28 @@
   "tables.setStyle",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "getNodeById",
   "format.apply",
   "tables.get",
   "tables.getCells",
-  "getNodeById",
-  "create.paragraph",
+  "insert",
   "tables.get",
   "tables.getCells",
   "getNodeById",
-  "create.paragraph",
+  "tables.get",
+  "tables.getCells",
+  "insert",
   "tables.get",
   "tables.getCells",
   "getNodeById",
-  "create.paragraph"
+  "tables.get",
+  "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
+  "getNodeById"
 ]

{athena_python_docx-0.11.0 → athena_python_docx-0.11.1}/tests/fidelity/op_snapshots/90_cell_add_paragraph_styled.json

@@ -2,8 +2,10 @@
   "create.table",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "styles.paragraph.setStyle",
   "getNodeById"
 ]

{athena_python_docx-0.11.0 → athena_python_docx-0.11.1}/tests/fidelity/op_snapshots/ex13_cell_with_10_paragraphs.json

@@ -3,52 +3,72 @@
   "tables.setStyle",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "format.paragraph.setAlignment",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "format.paragraph.setAlignment",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "format.paragraph.setAlignment",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "format.paragraph.setAlignment",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "format.paragraph.setAlignment",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "format.paragraph.setAlignment",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "format.paragraph.setAlignment",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "format.paragraph.setAlignment",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "format.paragraph.setAlignment",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "format.paragraph.setAlignment"
 ]

{athena_python_docx-0.11.0 → athena_python_docx-0.11.1}/tests/fidelity/op_snapshots/mega01_book_chapter.json

@@ -45,8 +45,10 @@
   "tables.setCell",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "getNodeById",
   "getNodeById",
   "format.apply",
@@ -54,8 +56,10 @@
   "format.apply",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "getNodeById",
   "getNodeById",
   "format.apply",
@@ -63,8 +67,10 @@
   "format.apply",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "getNodeById",
   "getNodeById",
   "format.apply",
@@ -72,8 +78,10 @@
   "format.apply",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "getNodeById",
   "getNodeById",
   "format.apply",
@@ -81,8 +89,10 @@
   "format.apply",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "getNodeById",
   "getNodeById",
   "format.apply",
@@ -90,8 +100,10 @@
   "format.apply",
   "tables.get",
   "tables.getCells",
+  "insert",
+  "tables.get",
+  "tables.getCells",
   "getNodeById",
-  "create.paragraph",
   "getNodeById",
   "getNodeById",
   "format.apply",

{athena_python_docx-0.11.0 → athena_python_docx-0.11.1}/tests/test_block_not_found_error.py

@@ -263,6 +263,75 @@ def test_generic_not_found_still_raises_notfounderror() -> None:
     )
 
 
+def test_invalid_target_tablecell_routes_through_block_not_found() -> None:
+    """SuperDoc's newer cell-paragraph addressing-error shape
+
+        ``INVALID_TARGET - Expected paragraph:<uuid> but found tableCell:<id>.``
+
+    must surface as :class:`BlockNotFoundError` with the cell-paragraph
+    hint, same as the older ``Block "paragraph:<uuid>" was not found``
+    form. Both error shapes share the same root cause (SUPERDOC_UPSTREAM_
+    REQUESTS § 13) — agents shouldn't have to learn which variant fired
+    to find the recovery path."""
+
+    def _capture(url: str, **kwargs: Any) -> _FakeResponse:  # noqa: ARG001
+        return _FakeResponse(
+            status_code=207,
+            body=_partial_failure_body(
+                cmd_type="SetParagraphAlignment",
+                message=(
+                    "INVALID_TARGET - Expected paragraph:"
+                    "2d58567b-e933-4f72-bfde-674e7b552f8a but found "
+                    "tableCell:cell-auto-38f799d7."
+                ),
+            ),
+        )
+
+    client = HttpClient(base_url="https://example.com", api_key="bg_key")
+
+    with patch.object(client._session, "post", side_effect=_capture):
+        with pytest.raises(BlockNotFoundError) as exc_info:
+            _execute_setalignment(client)
+
+    msg = str(exc_info.value)
+    assert "cell.text" in msg, (
+        "INVALID_TARGET ... but found tableCell is the new variant of "
+        "the cell-paragraph addressing gap (SUPERDOC_UPSTREAM_REQUESTS "
+        "§ 13). The hint MUST fire here just like the older 'Block "
+        "not found' form."
+    )
+
+
+def test_invalid_target_create_paragraph_routes_through_block_not_found() -> None:
+    """``CreateParagraph`` against a cell-inner paragraph anchor (the
+    pre-0.11.x ``_Cell.add_paragraph`` shape) raises the INVALID_TARGET
+    form. ``_Cell.add_paragraph`` now routes through ``doc.insert``
+    instead, but other call sites that build a Create with a cell-inner
+    target should still get the hint instead of a generic DocxError."""
+
+    def _capture(url: str, **kwargs: Any) -> _FakeResponse:  # noqa: ARG001
+        return _FakeResponse(
+            status_code=207,
+            body=_partial_failure_body(
+                cmd_type="CreateParagraph",
+                message=(
+                    "INVALID_TARGET - Expected paragraph:"
+                    "2d58567b-e933-4f72-bfde-674e7b552f8a but found "
+                    "tableCell:cell-auto-38f799d7."
+                ),
+            ),
+        )
+
+    client = HttpClient(base_url="https://example.com", api_key="bg_key")
+
+    with patch.object(client._session, "post", side_effect=_capture):
+        with pytest.raises(BlockNotFoundError) as exc_info:
+            _execute_setalignment(client)
+
+    msg = str(exc_info.value)
+    assert "cell.text" in msg
+
+
 def test_transport_error_unchanged() -> None:
     """A genuine 5xx or validation error must NOT be reclassified as
     :class:`BlockNotFoundError`. Only the "Block ... not found" shape

athena_python_docx-0.11.1/tests/test_cell_add_paragraph_wire_shape.py

@@ -0,0 +1,133 @@
+"""Wire-shape lock-in for ``_Cell.add_paragraph``.
+
+Pre-fix: the SDK anchored ``create.paragraph`` after the cell's last
+inner paragraph (``at: {kind: "after", target: paragraph(<inner-id>)}``).
+SuperDoc 1.8.1 cannot resolve that anchor for cell-inner paragraphs
+and raises ``INVALID_TARGET - Expected paragraph:<id> but found
+tableCell:<id>``. See ``docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md`` § 13.
+
+Post-fix: the SDK routes through ``doc.insert`` with the cell itself
+as target and ``placement: "insideEnd"`` — the same wire path that
+``_Cell.text`` already uses successfully.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _make_cell(mock_session: Any, fake_sd_methods: Any) -> Any:
+    from docx.table import Table, _Cell
+
+    fake_sd_methods.scripted_returns["tables.get_cells"] = {
+        "cells": [
+            {
+                "nodeId": "cell-auto-abc123",
+                "rowIndex": 0,
+                "columnIndex": 0,
+                "text": "existing content",
+            },
+        ],
+    }
+    fake_sd_methods.scripted_returns["get_node_by_id"] = {
+        "node": {
+            "kind": "tableCell",
+            "id": "cell-auto-abc123",
+            "tableCell": {
+                "paragraphs": [
+                    {"kind": "paragraph", "id": "para-existing-1"},
+                    {"kind": "paragraph", "id": "para-new-2"},
+                ],
+            },
+        },
+    }
+
+    table = Table(session=mock_session, node_id="tbl-1")
+    return _Cell(table=table, row=0, col=0)
+
+
+def test_cell_add_paragraph_routes_through_insert(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    """``cell.add_paragraph('hi')`` MUST NOT call ``create.paragraph``
+    with a cell-inner-paragraph anchor.
+
+    The pre-fix wire shape was:
+        create.paragraph({
+            text: "hi",
+            at: {kind: "after",
+                 target: {nodeType: "paragraph", nodeId: <inner-id>}},
+        })
+
+    That shape provokes SuperDoc 1.8.1's INVALID_TARGET error on every
+    cell loaded from a real .docx (every such cell has at least one
+    inner paragraph). The post-fix shape uses ``doc.insert`` against
+    the cell with ``placement: insideEnd``.
+    """
+    cell = _make_cell(mock_session, fake_sd_methods)
+
+    cell.add_paragraph("hi")
+
+    insert_calls = [c for c in fake_sd_methods.calls if c[0] == "insert"]
+    assert insert_calls, (
+        "Expected _Cell.add_paragraph to call doc.insert, but only saw "
+        f"{[c[0] for c in fake_sd_methods.calls]}"
+    )
+    _, params = insert_calls[-1]
+    assert params["target"] == {
+        "kind": "block",
+        "nodeType": "tableCell",
+        "nodeId": "cell-auto-abc123",
+    }, f"target must be the cell itself, not its inner paragraph; got {params['target']!r}"
+    assert params["placement"] == "insideEnd"
+    content = params["content"]
+    assert isinstance(content, dict)
+    assert content["kind"] == "paragraph"
+    inlines = content["paragraph"]["inlines"]
+    assert inlines == [{"kind": "run", "run": {"text": "hi"}}]
+
+    create_para_calls = [
+        c for c in fake_sd_methods.calls if c[0] == "create.paragraph"
+    ]
+    for _, p in create_para_calls:
+        at = p.get("at") or {}
+        target = at.get("target") or {}
+        assert target.get("nodeType") != "paragraph" or not str(
+            target.get("nodeId", "")
+        ).startswith("para-"), (
+            "create.paragraph must not anchor to a cell-inner "
+            f"paragraph (got at={at!r})"
+        )
+
+
+def test_cell_add_paragraph_empty_text_emits_empty_inlines(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    """``cell.add_paragraph()`` (no text) inserts a paragraph fragment
+    with an empty inlines list — the same shape ``_Cell.text = ''``
+    produces."""
+    cell = _make_cell(mock_session, fake_sd_methods)
+
+    cell.add_paragraph()
+
+    insert_calls = [c for c in fake_sd_methods.calls if c[0] == "insert"]
+    assert insert_calls
+    _, params = insert_calls[-1]
+    assert params["content"]["paragraph"]["inlines"] == []
+
+
+def test_cell_add_paragraph_returns_paragraph_with_node_id(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    """The returned ``Paragraph`` proxy must carry a real node_id so
+    follow-up operations (``para.style = ...``, ``para.add_run(...)``)
+    address the new paragraph rather than its containing cell.
+    """
+    cell = _make_cell(mock_session, fake_sd_methods)
+
+    para = cell.add_paragraph("hi")
+
+    from docx.text.paragraph import Paragraph
+
+    assert isinstance(para, Paragraph)
+    assert para._node_id, "Paragraph proxy must carry a non-empty node_id"