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

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

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.11.2"
+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.3/tests/test_oxml_shim.py

@@ -0,0 +1,174 @@
+"""Lock-in tests for the ``docx.oxml`` stub package.
+
+``docx.oxml`` is intentionally unavailable in athena-python-docx —
+agent code that imports ``docx.oxml.ns``, ``docx.oxml.parser``, etc.
+used to fail with the stdlib's generic ``ModuleNotFoundError: No
+module named 'docx.oxml'`` and had to retry to discover the gap.
+
+The 0.8.0 stub package replaced that with a single typed
+:class:`OxmlNotAvailableError` that named the high-level python-docx
+surface the caller should use instead — but the 0.8.0 stub raised
+on attribute access, which is what ``from docx.oxml.ns import qn``
+triggers. That meant the import statement itself crashed before any
+line of the agent's actual logic ran. The common python-docx
+convention of declaring ``qn`` / ``OxmlElement`` at the top of every
+script "just in case" killed scripts that only used the high-level
+API.
+
+As of 0.11.3 the stub is **lazy**:
+
+1. Every common upstream submodule (``ns``, ``parser``, ``element``,
+   ``xmlchemy``, …) is importable — same as 0.8.0.
+2. Attribute access on those modules now returns a sentinel proxy
+   rather than raising — ``from docx.oxml.ns import qn`` succeeds,
+   ``qn`` is bound to a :class:`_LazyRaisingProxy`.
+3. The typed :class:`OxmlNotAvailableError` fires only when the
+   imported symbol is actually used — called (``qn(...)``),
+   attribute-accessed (``OxmlElement.tag``), or written-to
+   (``OxmlElement.tag = "..."``).
+
+These tests pin all three contracts so a future refactor can't
+regress to the 0.8.0 import-time failure or to a totally-permissive
+no-op stub.
+"""
+
+from __future__ import annotations
+
+import importlib
+import pytest
+
+
+def test_oxml_not_available_error_is_importerror_subclass() -> None:
+    """Code that uses ``try / except ImportError`` to detect missing
+    oxml support must still catch :class:`OxmlNotAvailableError`."""
+    from docx.oxml import OxmlNotAvailableError
+
+    assert issubclass(OxmlNotAvailableError, ImportError)
+
+
+@pytest.mark.parametrize(
+    "submodule",
+    [
+        "ns",
+        "parser",
+        "element",
+        "xmlchemy",
+        "exceptions",
+        "coreprops",
+        "document",
+        "text",
+        "table",
+        "comments",
+        "header_footer",
+        "section",
+        "settings",
+        "styles",
+        "numbering",
+    ],
+)
+def test_submodule_import_succeeds(submodule: str) -> None:
+    """``import docx.oxml.<X>`` must resolve to a stub module without
+    raising. Same contract as 0.8.0."""
+    mod = importlib.import_module(f"docx.oxml.{submodule}")
+    assert mod is not None
+    assert mod.__name__ == f"docx.oxml.{submodule}"
+
+
+def test_top_level_import_succeeds_lazy() -> None:
+    """``from docx.oxml import OxmlElement`` (and friends) must
+    succeed and bind a sentinel proxy. The 0.8.0 stub raised at
+    import time; 0.11.3 defers the error until the symbol is used.
+    """
+    from docx.oxml import OxmlElement  # must NOT raise
+
+    assert OxmlElement is not None
+    # repr should reveal the lazy nature so debugging is easy.
+    assert "docx.oxml.OxmlElement" in repr(OxmlElement)
+
+
+def test_submodule_import_succeeds_lazy() -> None:
+    """``from docx.oxml.ns import qn`` must succeed and bind a sentinel
+    proxy. This is the most common python-docx import pattern."""
+    from docx.oxml.ns import qn, nsmap  # must NOT raise
+
+    assert qn is not None
+    assert nsmap is not None
+    assert "docx.oxml.ns.qn" in repr(qn)
+
+
+def test_call_on_imported_symbol_raises() -> None:
+    """The typed error fires when the imported symbol is actually
+    invoked. ``qn("w:tcW")`` raises :class:`OxmlNotAvailableError`
+    with the educated message pointing at the high-level surface."""
+    from docx.oxml import OxmlNotAvailableError
+    from docx.oxml.ns import qn
+
+    with pytest.raises(OxmlNotAvailableError) as exc_info:
+        qn("w:tcW")
+    msg = str(exc_info.value)
+    assert "docx.oxml.ns.qn" in msg
+    assert "Document.add_paragraph" in msg
+
+
+def test_attribute_access_on_imported_symbol_raises() -> None:
+    """``OxmlElement.tag`` and similar attribute lookups on the
+    sentinel proxy raise the typed error with the full dotted path."""
+    from docx.oxml import OxmlElement, OxmlNotAvailableError
+
+    with pytest.raises(OxmlNotAvailableError) as exc_info:
+        _ = OxmlElement.tag
+    msg = str(exc_info.value)
+    assert "docx.oxml.OxmlElement.tag" in msg
+    assert "Document.add_paragraph" in msg
+
+
+def test_attribute_write_on_imported_symbol_raises() -> None:
+    """Writes against the sentinel (``OxmlElement.tag = "..."``) also
+    raise — otherwise the assignment silently succeeds and the next
+    read of ``OxmlElement.tag`` returns the cached value, masking the
+    fact that no XML element actually exists."""
+    from docx.oxml import OxmlElement, OxmlNotAvailableError
+
+    with pytest.raises(OxmlNotAvailableError):
+        OxmlElement.tag = "w:foo"
+
+
+def test_call_on_module_level_symbol_raises() -> None:
+    """``oxml.OxmlElement(...)`` (without a from-import) follows the
+    same path — the package-level ``__getattr__`` returns the lazy
+    proxy, the proxy raises on call."""
+    import docx.oxml as oxml
+    from docx.oxml import OxmlNotAvailableError
+
+    with pytest.raises(OxmlNotAvailableError):
+        oxml.OxmlElement()
+
+
+def test_repeated_attribute_access_returns_same_proxy() -> None:
+    """``ns.qn`` accessed twice returns the same proxy instance so
+    callers that bind it to a local then re-fetch (e.g. assignments
+    in different functions) don't get diverging sentinels."""
+    import docx.oxml.ns as ns
+
+    first = ns.qn
+    second = ns.qn
+    assert first is second
+
+
+def test_dunder_attribute_access_falls_through() -> None:
+    """Dunder access (``__path__``, ``__loader__``, etc.) must NOT
+    return a proxy — the import machinery probes those during
+    submodule resolution. Treating them as user attribute access
+    would break the import path."""
+    import docx.oxml.ns as ns
+
+    with pytest.raises(AttributeError):
+        _ = ns.__nonexistent_dunder__
+
+
+def test_from_submodule_import_succeeds_lazy() -> None:
+    """``from docx.oxml.parser import OxmlElement`` must succeed
+    under the lazy contract — 0.8.0 raised here, but the agent's
+    actual mistake is the call site, not the import."""
+    # Should not raise.
+    exec("from docx.oxml.parser import OxmlElement", {})

athena_python_docx-0.11.2/docx/oxml/__init__.py

@@ -1,148 +0,0 @@
-"""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. As of
-0.8.0 this package is a typed stub: every import path resolves, but
-every attribute access raises :class:`OxmlNotAvailableError` with a
-single actionable message pointing at the high-level python-docx
-surface (``Document.add_paragraph``, ``Run.bold``, ``_Cell.text``, …)
-or the typed command bus (``docx.commands``).
-
-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 on any access to ``docx.oxml.*`` symbols.
-
-    Inherits :class:`ImportError` so callers using
-    ``try: from docx.oxml import X / except ImportError`` still match,
-    while ``except OxmlNotAvailableError`` lets newer code distinguish
-    a "no oxml surface" miss from a real import-resolution failure.
-    """
-
-
-_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 _OxmlStubModule(types.ModuleType):
-    """ModuleType subclass that raises :class:`OxmlNotAvailableError`
-    on every 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``) and raise the
-    typed exception when the symbol is dereferenced.
-
-    No ``__slots__`` — ``types.ModuleType`` itself carries a
-    ``__dict__``, so a slots declaration on a subclass is a no-op and
-    doesn't prevent ``docx.oxml.ns.qn = something`` from silently
-    bypassing :meth:`__getattr__` on the next read. If a future caller
-    needs to block that bypass we'd need a ``__setattr__`` guard that
-    rejects user-attribute writes while still letting the import
-    machinery install dunders (``__loader__``, ``__spec__``, …) on the
-    stub at package-init time.
-    """
-
-    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__
-        raise OxmlNotAvailableError(f"{path}.{name} — {_MESSAGE}")
-
-
-# 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 to
-    the default ``AttributeError`` so Python's import machinery
-    behaves normally. Everything else raises the typed error.
-    """
-    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
-    raise OxmlNotAvailableError(f"docx.oxml.{name} — {_MESSAGE}")
-
-
-__all__ = ["OxmlNotAvailableError"]

athena_python_docx-0.11.2/tests/test_oxml_shim.py

@@ -1,123 +0,0 @@
-"""Lock-in tests for the ``docx.oxml`` stub package.
-
-``docx.oxml`` is intentionally unavailable in athena-python-docx —
-agent code that imports ``docx.oxml.ns``, ``docx.oxml.parser``, etc.
-used to fail with the stdlib's generic ``ModuleNotFoundError: No
-module named 'docx.oxml'`` and had to retry to discover the gap. The
-0.8.0 stub package replaces that with a single typed
-:class:`OxmlNotAvailableError` that names the high-level python-docx
-surface the caller should use instead, so the agent learns
-immediately.
-
-These tests pin both halves of the contract:
-
-1. Every common upstream submodule (``ns``, ``parser``, ``element``,
-   ``xmlchemy``, etc.) is importable — i.e. the import doesn't raise
-   ``ModuleNotFoundError``.
-2. Any attribute access on those modules raises
-   :class:`OxmlNotAvailableError` with the actionable message pointing
-   at the high-level API.
-"""
-
-from __future__ import annotations
-
-import importlib
-import pytest
-
-
-def test_package_attribute_access_raises_typed_error() -> None:
-    """``from docx.oxml import OxmlElement`` (and friends) must raise
-    :class:`OxmlNotAvailableError`, not the stdlib's bare
-    ``ImportError`` or ``AttributeError``."""
-    import docx.oxml as oxml
-    from docx.oxml import OxmlNotAvailableError
-
-    with pytest.raises(OxmlNotAvailableError) as exc_info:
-        _ = oxml.OxmlElement
-    assert "OxmlElement" in str(exc_info.value)
-    assert "docx.oxml" in str(exc_info.value)
-    # The actionable hint must name the high-level surface.
-    assert "Document.add_paragraph" in str(exc_info.value)
-
-
-def test_oxml_not_available_error_is_importerror_subclass() -> None:
-    """Code that uses ``try / except ImportError`` to detect missing
-    oxml support must still catch :class:`OxmlNotAvailableError` so
-    pre-0.8.0 callers don't regress."""
-    from docx.oxml import OxmlNotAvailableError
-
-    assert issubclass(OxmlNotAvailableError, ImportError)
-
-
-@pytest.mark.parametrize(
-    "submodule",
-    [
-        "ns",
-        "parser",
-        "element",
-        "xmlchemy",
-        "exceptions",
-        "coreprops",
-        "document",
-        "text",
-        "table",
-        "comments",
-        "header_footer",
-        "section",
-        "settings",
-        "styles",
-        "numbering",
-    ],
-)
-def test_submodule_import_succeeds(submodule: str) -> None:
-    """``import docx.oxml.<X>`` must resolve to a stub module without
-    raising. The stub raises on attribute access, but the import
-    itself succeeds — that's the contract that distinguishes a stub
-    from a totally-missing module (which would still raise
-    ``ModuleNotFoundError`` and force agents to retry)."""
-    mod = importlib.import_module(f"docx.oxml.{submodule}")
-    assert mod is not None
-    assert mod.__name__ == f"docx.oxml.{submodule}"
-
-
-def test_submodule_attribute_access_raises() -> None:
-    """The whole point of the shim — ``from docx.oxml.ns import qn``
-    raises :class:`OxmlNotAvailableError` with a message that names
-    the high-level surface, instead of crashing with the stdlib's
-    bare ``ModuleNotFoundError``."""
-    import docx.oxml.ns as ns
-    from docx.oxml import OxmlNotAvailableError
-
-    with pytest.raises(OxmlNotAvailableError) as exc_info:
-        _ = ns.qn
-    assert "docx.oxml.ns.qn" in str(exc_info.value)
-    # Same hint as the top-level package error.
-    assert "Document.add_paragraph" in str(exc_info.value)
-
-
-def test_from_submodule_import_raises_typed_error() -> None:
-    """``from docx.oxml.parser import OxmlElement`` must raise
-    :class:`OxmlNotAvailableError` even though the submodule import
-    itself succeeded — the attribute access happens during the
-    ``from`` step and is the user-observable failure mode."""
-    from docx.oxml import OxmlNotAvailableError
-
-    import_stmt = "from docx.oxml.parser import OxmlElement"
-    with pytest.raises(OxmlNotAvailableError):
-        exec(import_stmt, {})
-
-
-def test_dunder_attribute_access_falls_through() -> None:
-    """Dunder access (``__path__``, ``__loader__``, etc.) must NOT
-    raise :class:`OxmlNotAvailableError` — the import machinery probes
-    those during submodule resolution, and treating them as user
-    attribute access would break the whole import path. The stub
-    raises ``AttributeError`` for dunders so the import system can
-    fall back to its normal behavior."""
-    import docx.oxml.ns as ns
-
-    # Mimic what the import system does when it can't find an
-    # explicit attribute — should raise plain AttributeError, not
-    # OxmlNotAvailableError.
-    with pytest.raises(AttributeError):
-        _ = ns.__nonexistent_dunder__