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

{athena_python_docx-0.11.1 → athena_python_docx-0.11.2}/CLAUDE.md

@@ -39,6 +39,18 @@ These standard python-docx members don't apply to a Superdoc-backed SDK:
   `Comment.tables` — SuperDoc models a comment as a single text body,
   not a `BlockItemContainer`. Use `Comment.text` instead. The
   paragraph/table-bearing surface raises `CommentsNotImplementedError`.
+- **`_Cell.add_table(rows, cols)`** — surface preserved for parity
+  (signature matches python-docx, no `width` kwarg) but raises
+  :class:`docx.errors.NestedTableNotSupportedError` (subclass of
+  `NotImplementedError`) at runtime since 0.11.2. SuperDoc 1.8.1 has
+  no anchor or content-fragment shape that places a new table inside
+  an existing `tableCell` — `create.table` rejects cell-inner
+  paragraph anchors with `INVALID_TARGET`, and the `doc.insert`
+  workaround used by `_Cell.add_paragraph` doesn't generalize
+  because the apps/api `Insert` schema doesn't yet forward
+  `nestingPolicy: {tables: "allow"}` and the SuperDoc table-content
+  fragment shape isn't documented. Tracked at
+  `docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md` § 13.
 - **`docx.oxml.*`** — the entire raw-OOXML module tree (``ns.qn``,
   ``OxmlElement``, ``CT_*`` classes, etc.) is unavailable because the
   SDK is HTTP-only against a SuperDoc Y.Doc; there is no local lxml

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

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

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

{athena_python_docx-0.11.1 → athena_python_docx-0.11.2}/docx/errors.py

@@ -128,6 +128,28 @@ class LocalSaveTargetNotSupportedError(DocxError, NotImplementedError):
     """
 
 
+class NestedTableNotSupportedError(DocxError, NotImplementedError):
+    """Raised when ``_Cell.add_table(...)`` is called.
+
+    SuperDoc 1.8.1 cannot place a new top-level block inside an
+    existing ``tableCell`` — ``create.table`` rejects a cell-inner
+    paragraph anchor with ``INVALID_TARGET - Expected paragraph:<id>
+    but found tableCell:<id>``, and there is no ``create.table``
+    anchor shape ("inside this cell") that addresses cell content
+    directly. The ``doc.insert``-based workaround used by
+    ``_Cell.text`` / ``_Cell.add_paragraph`` requires a
+    ``nestingPolicy: {tables: "allow"}`` flag and a table content
+    fragment that aren't yet plumbed through the docx-studio command
+    bus, so this entire method is unsupported until upstream
+    SuperDoc lands the cell-inner addressing fix tracked in
+    ``docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md`` § 13.
+
+    Subclasses :class:`NotImplementedError` so a generic
+    ``except NotImplementedError`` catches it without importing the
+    typed class.
+    """
+
+
 class ValidationError(DocxError):
     """Raised when SDK-level validation fails (bad args, out-of-range indices)."""
 

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

@@ -1430,40 +1430,47 @@ class _Cell:
     def add_table(self, rows: int, cols: int) -> Table:
         """Append a nested table inside the cell.
 
-        Mirrors python-docx ``_Cell.add_table(rows, cols) -> Table``.
+        Mirrors python-docx ``_Cell.add_table(rows, cols) -> Table``
+        at the API surface, but raises
+        :class:`docx.errors.NestedTableNotSupportedError` at runtime
+        — SuperDoc 1.8.1 has no addressable shape for "create table
+        inside this cell" (every available anchor either targets a
+        cell-inner paragraph SuperDoc can't resolve, or promotes the
+        new block to the cell's parent row level). The unblock is
+        tracked at ``docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md`` § 13;
+        the same gap was the proximate cause of the
+        ``_Cell.add_paragraph`` failure fixed in 0.11.1 (#20745), and
+        that fix worked only because ``doc.insert`` accepts a paragraph
+        content fragment against a ``tableCell`` target — there is no
+        analogous table-content fragment path through the current
+        docx-studio command bus.
+
+        ``rows`` and ``cols`` are still validated upfront so callers
+        get the same ``ValidationError`` they would have hit before, in
+        case they were branching on it.
+
         Note that upstream's ``_Cell.add_table`` does not take a
         ``width`` parameter — Word inherits cell-table widths from
         layout. ``Document.add_table`` and ``Section.header.add_table``
         DO take ``width`` because they're block-level.
         """
-        from docx.document import _extract_inserted_node_id
+        from docx.errors import NestedTableNotSupportedError
 
         if rows < 1 or cols < 1:
             raise ValidationError(f"rows/cols must be >=1; got {rows}/{cols}")
-        # We can target the cell's last paragraph as an anchor.
-        ids = self._inner_paragraph_ids()
-        if ids:
-            anchor = {
-                "kind": "after",
-                "target": {
-                    "kind": "block",
-                    "nodeType": "paragraph",
-                    "nodeId": ids[-1],
-                },
-            }
-        else:
-            anchor = {"kind": "documentEnd"}
-        result: object = run_sync(
-            self._table._session.doc.create.table(
-                {"rows": rows, "columns": cols, "at": anchor},
-            ),
+        raise NestedTableNotSupportedError(
+            "_Cell.add_table is unsupported on SuperDoc 1.8.1. The cell "
+            "addressing gap (SUPERDOC_UPSTREAM_REQUESTS.md § 13) means "
+            "no anchor or content-fragment shape currently lets the SDK "
+            "place a new table inside an existing tableCell. Workarounds: "
+            "(a) build the table at document or section level via "
+            "Document.add_table and reference it from cell text, or "
+            "(b) include the nested table in the original template "
+            "document and address its cells directly. This method will "
+            "be reinstated once SuperDoc exposes either recursive "
+            "paragraph-anchor lookup or a cell-scoped create.table "
+            "variant.",
         )
-        node_id: str = _extract_inserted_node_id(result, expected_type="table") if isinstance(result, dict) else ""
-        if not node_id:
-            raise RuntimeError(
-                f"Superdoc did not return nodeId for nested table: {result!r}",
-            )
-        return Table(session=self._table._session, node_id=node_id)
 
     def merge(self, other_cell: "_Cell") -> "_Cell":
         """Return a merged cell created by spanning the rectangular

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.11.1"
+version = "0.11.2"
 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.1 → athena_python_docx-0.11.2}/tests/fidelity/complex_cases.py

@@ -319,18 +319,15 @@ CASES: list[ComplexCase] = [
         expected_ops=("tables.getCells", "create.paragraph"),
         tags=("level5", "table"),
     ),
-    ComplexCase(
-        name="23_nested_table",
-        description="Add a nested table inside a cell",
-        script=(
-            "outer = doc.add_table(rows=1, cols=1)\n"
-            "cell = outer.cell(0, 0)\n"
-            "nested = cell.add_table(rows=2, cols=2)\n"
-            'nested.cell(0, 0).text = "nested"'
-        ),
-        expected_ops=("create.table",),
-        tags=("level5", "table", "nested"),
-    ),
+    # Removed in 0.11.2 (#20745 follow-up): ``_Cell.add_table`` now
+    # raises ``NestedTableNotSupportedError`` because SuperDoc 1.8.1
+    # has no addressable shape for "create new table inside this cell"
+    # — every available anchor either targets a cell-inner paragraph
+    # SuperDoc can't resolve or promotes the new block to the cell's
+    # parent row. Tracked at SUPERDOC_UPSTREAM_REQUESTS.md § 13. Pre-
+    # 0.11.2 this case "passed" by silently writing the nested table
+    # to documentEnd, which round-tripped in the fake but is wrong in
+    # production. See tests/test_cell_add_table_not_supported.py.
     ComplexCase(
         name="24_table_add_row_column",
         description="Add row and column dynamically (python-docx 1.x requires width for add_column)",
@@ -745,17 +742,9 @@ CASES: list[ComplexCase] = [
     ),
 
     # ---------- Level 17: deep nesting + iteration ----------
-    ComplexCase(
-        name="51_nested_tables_deep",
-        description="Table in cell that contains another table in a cell",
-        script=(
-            "outer = doc.add_table(rows=1, cols=1)\n"
-            "mid = outer.cell(0, 0).add_table(rows=1, cols=1)\n"
-            "inner = mid.cell(0, 0).add_table(rows=2, cols=2)\n"
-            'inner.cell(0, 0).text = "deepest"'
-        ),
-        tags=("level17", "nested"),
-    ),
+    # 51_nested_tables_deep removed in 0.11.2 (#20745 follow-up):
+    # _Cell.add_table now raises NestedTableNotSupportedError on
+    # SuperDoc 1.8.1; see SUPERDOC_UPSTREAM_REQUESTS.md § 13.
     ComplexCase(
         name="52_iterate_everything",
         description="Create a doc then iterate sections/paragraphs/tables",
@@ -1784,20 +1773,9 @@ CASES: list[ComplexCase] = [
     ),
 
     # ---------- Level 56: cell.tables for nested detection ----------
-    ComplexCase(
-        name="103_cell_tables_enumeration",
-        description="Enumerate cell.tables after nesting",
-        script=(
-            "outer = doc.add_table(rows=1, cols=1)\n"
-            "c = outer.cell(0, 0)\n"
-            "c.add_table(rows=2, cols=2)\n"
-            "c.add_table(rows=1, cols=1)\n"
-            "# cell.tables should list nested tables\n"
-            "nested = c.tables\n"
-            "# don't assert exact count — fake may not fully reflect"
-        ),
-        tags=("level56", "nested"),
-    ),
+    # 103_cell_tables_enumeration removed in 0.11.2 (#20745 follow-up):
+    # _Cell.add_table raises NestedTableNotSupportedError; see
+    # SUPERDOC_UPSTREAM_REQUESTS.md § 13.
 
     # ---------- Level 57: core properties pull in datetime ----------
     ComplexCase(

{athena_python_docx-0.11.1 → athena_python_docx-0.11.2}/tests/fidelity/extreme_cases.py

@@ -11,18 +11,9 @@ from tests.fidelity.complex_cases import ComplexCase
 
 EXTREME_CASES: list[ComplexCase] = [
     # ---- Deep nesting ----
-    ComplexCase(
-        name="ex01_five_levels_deep_tables",
-        description="5-level deep nested tables",
-        script=(
-            "current = doc.add_table(rows=1, cols=1).cell(0, 0)\n"
-            "for i in range(4):\n"
-            "    nested = current.add_table(rows=1, cols=1)\n"
-            "    current = nested.cell(0, 0)\n"
-            "current.text = 'deepest'"
-        ),
-        tags=("extreme", "nested"),
-    ),
+    # ex01_five_levels_deep_tables removed in 0.11.2 (#20745 follow-up):
+    # _Cell.add_table raises NestedTableNotSupportedError on SuperDoc
+    # 1.8.1; see SUPERDOC_UPSTREAM_REQUESTS.md § 13.
 
     # ---- Unicode stress ----
     ComplexCase(

{athena_python_docx-0.11.1 → athena_python_docx-0.11.2}/tests/fidelity/real_world_cases.py

@@ -305,19 +305,10 @@ REAL_WORLD_CASES: list[ComplexCase] = [
         tags=("real_world", "headers", "even_odd"),
     ),
 
-    # Cell-level _Cell.add_table — nested table inside a cell, no width
-    # parameter (matches upstream signature parity fix from Phase C).
-    ComplexCase(
-        name="rw14_nested_cell_table",
-        description="Nested 2x2 table inside the (0,0) cell of a parent table",
-        script=(
-            "document = doc\n"
-            "t = document.add_table(rows=2, cols=2, style='TableGrid')\n"
-            "inner = t.cell(0, 0).add_table(2, 2)\n"
-            "inner.cell(0, 0).text = 'inner'"
-        ),
-        tags=("real_world", "table", "nested"),
-    ),
+    # rw14_nested_cell_table removed in 0.11.2 (#20745 follow-up):
+    # _Cell.add_table now raises NestedTableNotSupportedError; the
+    # functionality requires SuperDoc upstream work tracked at
+    # SUPERDOC_UPSTREAM_REQUESTS.md § 13.
 
     # Paragraph-style instances passed to add_paragraph (Phase A
     # tightening). Exercises the str | ParagraphStyle | None branch of

athena_python_docx-0.11.2/tests/test_cell_add_table_not_supported.py

@@ -0,0 +1,79 @@
+"""Pinning test for ``_Cell.add_table`` raising
+:class:`NestedTableNotSupportedError`.
+
+SuperDoc 1.8.1 has no addressable shape for "create new table inside
+this cell" — ``create.table`` rejects a cell-inner paragraph anchor
+with ``INVALID_TARGET - Expected paragraph:<id> but found
+tableCell:<id>``, and the ``doc.insert``-based workaround used by
+``_Cell.add_paragraph`` (paragraph fragment + ``placement: insideEnd``)
+has no analog for table content fragments wired through the
+docx-studio command bus. So ``_Cell.add_table`` raises a typed
+``NestedTableNotSupportedError`` rather than silently corrupting the
+document (the pre-0.11.2 implementation either failed with the
+cryptic INVALID_TARGET when the cell had content or silently wrote
+the table to documentEnd when the cell was empty).
+
+Tracked at ``docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md`` § 13.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from docx.errors import NestedTableNotSupportedError, ValidationError
+
+
+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-x1",
+                "rowIndex": 0,
+                "columnIndex": 0,
+                "text": "",
+            },
+        ],
+    }
+    table = Table(session=mock_session, node_id="tbl-1")
+    return _Cell(table=table, row=0, col=0)
+
+
+def test_cell_add_table_raises_nested_table_not_supported(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    cell = _make_cell(mock_session, fake_sd_methods)
+    with pytest.raises(NestedTableNotSupportedError) as exc_info:
+        cell.add_table(2, 2)
+    msg = str(exc_info.value)
+    assert "SUPERDOC_UPSTREAM_REQUESTS.md § 13" in msg
+    assert "Document.add_table" in msg
+
+
+def test_cell_add_table_still_validates_dimensions_first(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    """``ValidationError`` for bad dimensions must still fire BEFORE the
+    NotImplementedError. Lets agents catch the more specific error
+    type without first reasoning about why the method is unsupported.
+    """
+    cell = _make_cell(mock_session, fake_sd_methods)
+    with pytest.raises(ValidationError, match="rows/cols"):
+        cell.add_table(0, 2)
+    with pytest.raises(ValidationError, match="rows/cols"):
+        cell.add_table(2, 0)
+
+
+def test_nested_table_error_is_a_notimplementederror(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    """``NestedTableNotSupportedError`` subclasses ``NotImplementedError``
+    so generic ``except NotImplementedError`` (a common pattern) catches
+    it without needing to import the typed class.
+    """
+    cell = _make_cell(mock_session, fake_sd_methods)
+    with pytest.raises(NotImplementedError):
+        cell.add_table(2, 2)

athena_python_docx-0.11.1/tests/fidelity/op_snapshots/103_cell_tables_enumeration.json

@@ -1,14 +0,0 @@
-[
-  "create.table",
-  "tables.get",
-  "tables.getCells",
-  "getNodeById",
-  "create.table",
-  "tables.get",
-  "tables.getCells",
-  "getNodeById",
-  "create.table",
-  "tables.get",
-  "tables.getCells",
-  "getNodeById"
-]

athena_python_docx-0.11.1/tests/fidelity/op_snapshots/23_nested_table.json

@@ -1,9 +0,0 @@
-[
-  "create.table",
-  "tables.get",
-  "tables.getCells",
-  "getNodeById",
-  "create.table",
-  "tables.get",
-  "tables.setCell"
-]

athena_python_docx-0.11.1/tests/fidelity/op_snapshots/51_nested_tables_deep.json

@@ -1,14 +0,0 @@
-[
-  "create.table",
-  "tables.get",
-  "tables.getCells",
-  "getNodeById",
-  "create.table",
-  "tables.get",
-  "tables.get",
-  "tables.getCells",
-  "getNodeById",
-  "create.table",
-  "tables.get",
-  "tables.setCell"
-]

athena_python_docx-0.11.1/tests/fidelity/op_snapshots/ex01_five_levels_deep_tables.json

@@ -1,24 +0,0 @@
-[
-  "create.table",
-  "tables.get",
-  "tables.getCells",
-  "getNodeById",
-  "create.table",
-  "tables.get",
-  "tables.get",
-  "tables.getCells",
-  "getNodeById",
-  "create.table",
-  "tables.get",
-  "tables.get",
-  "tables.getCells",
-  "getNodeById",
-  "create.table",
-  "tables.get",
-  "tables.get",
-  "tables.getCells",
-  "getNodeById",
-  "create.table",
-  "tables.get",
-  "tables.setCell"
-]

athena_python_docx-0.11.1/tests/fidelity/op_snapshots/rw14_nested_cell_table.json

@@ -1,10 +0,0 @@
-[
-  "create.table",
-  "tables.setStyle",
-  "tables.get",
-  "tables.getCells",
-  "getNodeById",
-  "create.table",
-  "tables.get",
-  "tables.setCell"
-]