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

{athena_python_docx-0.11.1 → athena_python_docx-0.11.3}/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.3}/PKG-INFO

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

{athena_python_docx-0.11.1 → athena_python_docx-0.11.3}/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.3/docx/oxml/__init__.py

@@ -0,0 +1,216 @@
+"""Stub package — ``docx.oxml`` is intentionally unavailable in
+athena-python-docx.
+
+python-docx upstream exposes raw OOXML element classes (``OxmlElement``,
+``CT_*``, ``qn``, ``nsmap``, …) for advanced users who manipulate
+Word's XML directly. athena-python-docx is backed by a SuperDoc Y.Doc
++ Keryx pipeline, not a local OOXML tree, so there is no XML element
+to manipulate.
+
+Before 0.8.0 attempts to ``from docx.oxml.ns import qn`` failed with
+the stdlib's generic ``ModuleNotFoundError: No module named
+'docx.oxml'`` — agent code had to discover the gap by retry. 0.8.0
+turned this package into a typed stub, but the stub raised
+``OxmlNotAvailableError`` on attribute access — which is what
+``from docx.oxml.ns import qn`` triggers, so the import statement
+itself crashed before any line of the agent's actual logic ran. Common
+python-docx convention is to declare ``qn`` / ``OxmlElement`` at the
+top of every script "just in case," and that preamble killed scripts
+that only used the high-level API.
+
+As of 0.11.3 the stub is **lazy**: ``from docx.oxml.ns import qn``
+succeeds and returns a sentinel proxy that defers the typed error
+until the symbol is actually called or further-attribute-accessed.
+Scripts that import for parity but never use the symbol now run
+cleanly; scripts that reach for ``qn("w:tcW")`` still get the
+actionable error pointing at the high-level alternative.
+
+The gap is documented in ``docx-studio/python-sdk/CLAUDE.md`` § "Intentionally
+omitted" and locked into the parity matrix via
+``tests/parity/intentional_deviations.json`` (``docx.oxml**``).
+"""
+
+from __future__ import annotations
+
+import sys
+import types
+from typing import Any
+
+
+class OxmlNotAvailableError(ImportError):
+    """Raised when a ``docx.oxml.*`` symbol is actually used.
+
+    Inherits :class:`ImportError` so callers using
+    ``try: from docx.oxml import X / except ImportError`` still match
+    after 0.11.3's lazy-stub change (the import itself succeeds, but
+    the first call site against the imported name raises this — and
+    code that uses ``except ImportError`` around a use-site still
+    catches it).
+
+    Use ``except OxmlNotAvailableError`` to distinguish a "no oxml
+    surface" miss from a real import-resolution failure or other
+    ``ImportError`` cause.
+    """
+
+
+_MESSAGE: str = (
+    "docx.oxml is not available in athena-python-docx — the SuperDoc "
+    "backend doesn't expose raw OOXML elements. Use the high-level "
+    "python-docx API (Document.add_paragraph, Run.bold, _Cell.text, …) "
+    "or the typed command surface in docx.commands for any mutation "
+    "the high-level API doesn't cover. "
+    "See docx-studio/python-sdk/CLAUDE.md § 'Intentionally omitted' for "
+    "the parity rationale."
+)
+
+
+class _LazyRaisingProxy:
+    """Sentinel returned by the ``docx.oxml`` stub for any imported name.
+
+    Behaves as a callable, an attribute-accessible namespace, and an
+    awaitable for the union of common python-docx patterns:
+
+    * ``from docx.oxml.ns import qn`` → ``qn`` is a _LazyRaisingProxy.
+      Just importing it is a no-op. ``qn("w:tcW")`` raises with the
+      educated message.
+    * ``from docx.oxml import OxmlElement`` → same. ``OxmlElement(...)``
+      raises; ``OxmlElement.something`` raises.
+    * ``isinstance(x, OxmlElement)`` → raises (we'd rather a noisy
+      failure than silently say no, since the typed error tells the
+      caller what to do).
+
+    The proxy carries the full dotted path so the error message points
+    at exactly the offending symbol — ``docx.oxml.ns.qn`` rather than a
+    generic "docx.oxml".
+    """
+
+    __slots__ = ("_path",)
+
+    def __init__(self, path: str) -> None:
+        # Bypass __setattr__ guard.
+        object.__setattr__(self, "_path", path)
+
+    def _raise(self, suffix: str = "") -> None:
+        path = object.__getattribute__(self, "_path")
+        target = f"{path}{suffix}" if suffix else path
+        raise OxmlNotAvailableError(f"{target} — {_MESSAGE}")
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
+        self._raise()
+
+    def __getattr__(self, name: str) -> Any:  # noqa: ANN401
+        if name.startswith("__") and name.endswith("__"):
+            raise AttributeError(name)
+        self._raise(f".{name}")
+
+    def __setattr__(self, name: str, value: Any) -> None:  # noqa: ANN401
+        # Block writes to the proxy so agents that try
+        # ``OxmlElement.tag = "..."`` get the typed error rather than a
+        # silent attribute set on the sentinel.
+        if name == "_path":
+            object.__setattr__(self, name, value)
+            return
+        self._raise(f".{name}")
+
+    def __repr__(self) -> str:
+        path = object.__getattribute__(self, "_path")
+        return f"<docx.oxml lazy stub {path!r} — call to raise>"
+
+
+class _OxmlStubModule(types.ModuleType):
+    """ModuleType subclass that returns :class:`_LazyRaisingProxy`
+    sentinels for any attribute access.
+
+    Installed into :data:`sys.modules` at package-init time so
+    qualified imports like ``from docx.oxml.ns import qn`` find a real
+    module object (avoiding ``ModuleNotFoundError``). The proxy
+    returned defers the typed error until the symbol is actually
+    invoked, letting top-level python-docx import blocks succeed.
+
+    No ``__slots__`` — ``types.ModuleType`` itself carries a
+    ``__dict__``, so a slots declaration on a subclass is a no-op.
+    """
+
+    def __getattr__(self, name: str) -> Any:  # noqa: ANN401
+        if name.startswith("__") and name.endswith("__"):
+            # Dunder access (e.g. ``__path__`` during submodule import)
+            # must fall through to AttributeError so Python's import
+            # machinery can probe without triggering our typed error.
+            raise AttributeError(name)
+        path = self.__name__
+        proxy = _LazyRaisingProxy(f"{path}.{name}")
+        # Cache so repeated `getattr` returns the same proxy and so
+        # `from X import Y` followed by another `from X import Y`
+        # gives the same instance.
+        object.__setattr__(self, name, proxy)
+        return proxy
+
+
+# Common upstream submodule paths. Listed explicitly rather than wild-
+# carded so adding a new one is a visible diff. Every entry maps to a
+# single sentinel module; no per-submodule state.
+_SUBMODULES: tuple[str, ...] = (
+    "ns",
+    "parser",
+    "element",
+    "xmlchemy",
+    "exceptions",
+    "ooxml",
+    "coreprops",
+    "document",
+    "text",
+    "table",
+    "comments",
+    "header_footer",
+    "footnote",
+    "endnote",
+    "shared",
+    "shape",
+    "section",
+    "settings",
+    "styles",
+    "numbering",
+)
+
+
+def _install_stub_submodules() -> None:
+    """Pre-populate :data:`sys.modules` with stub entries for every
+    well-known ``docx.oxml.*`` submodule.
+
+    Idempotent — re-running is a no-op for entries already installed
+    (covers the rare case of a test that reloads the package).
+    """
+    for short in _SUBMODULES:
+        full = f"docx.oxml.{short}"
+        if full in sys.modules:
+            continue
+        sys.modules[full] = _OxmlStubModule(full)
+
+
+_install_stub_submodules()
+
+
+def __getattr__(name: str) -> Any:  # noqa: ANN401
+    """PEP 562 attribute hook for ``from docx.oxml import X``.
+
+    Submodule names (handled via :data:`sys.modules` injection in
+    :func:`_install_stub_submodules`) and dunder names fall through
+    normally. Everything else returns a :class:`_LazyRaisingProxy` so
+    the import succeeds and the typed error fires only on actual use.
+    """
+    if name.startswith("__") and name.endswith("__"):
+        raise AttributeError(name)
+    if name in _SUBMODULES:
+        # Should already be present in sys.modules; defensive fallback
+        # so we never leak ModuleNotFoundError if the caller reloaded
+        # the package between calls.
+        full = f"docx.oxml.{name}"
+        mod = sys.modules.get(full)
+        if mod is None:
+            mod = _OxmlStubModule(full)
+            sys.modules[full] = mod
+        return mod
+    return _LazyRaisingProxy(f"docx.oxml.{name}")
+
+
+__all__ = ["OxmlNotAvailableError"]

{athena_python_docx-0.11.1 → athena_python_docx-0.11.3}/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.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.11.1"
+version = "0.11.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.11.1 → athena_python_docx-0.11.3}/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.3}/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.3}/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.3/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)