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

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

@@ -349,6 +349,82 @@ Issue numbers reference `python-openxml/python-docx`.
   wontfix upstream but the request keeps recurring. Routes through
   `ExportPDF` (SuperDoc handles the actual conversion).
 
+- **`Document.export_docx(path=None, *, include_revisions=False)
+  -> bytes`** (0.11.4+) — export the document's current state as
+  ``.docx`` bytes, optionally writing to ``path``. Closes the gap
+  left by ``Document.save(path)`` raising
+  ``LocalSaveTargetNotSupportedError`` in this SDK: parity test
+  harnesses and CI workflows need a programmatic .docx export to
+  diff against ``python-docx`` output, and pointing callers at
+  Olympus's Export DOCX action breaks every headless flow.
+  Routes through ``ExportDocx`` → SuperDoc's ``exportDocx``;
+  raises ``DocxError`` when the server build doesn't expose it
+  rather than silently writing zero bytes.
+
+### 0.11.4 behavior fixes for cell-inner paragraphs
+
+Format ops on cell-inner paragraphs (`paragraph.alignment`,
+`paragraph.style`, every `paragraph_format` setter, and
+`paragraph.add_hyperlink`) used to cascade-fail the entire HTTP
+batch. SuperDoc 1.8.1's
+``SetParagraphAlignment``/``SetParagraphStyle``/``SetParagraphIndentation``/``SetParagraphSpacing``/``CreateHyperlink``
+reject cell-inner block targets with ``BlockNotFoundError``, and the
+applier's all-or-nothing batch model meant one cell-paragraph
+mistake mid-script nuked every other unrelated create/format command
+queued before it (``applied: []``).
+
+As of 0.11.4 these setters check the paragraph proxy's ``_in_cell``
+flag (set by ``_Cell.add_paragraph`` and ``_Cell.paragraphs``) and
+emit ``docx.text.paragraph.CellInnerFormatNotSupportedWarning``
+instead of forwarding the broken command. The format op is dropped,
+the surrounding batch survives, and the workaround pointer (
+``cell.text = 'value'`` to materialize, then ``cell.paragraphs[0]``
+for the addressable proxy) is in the warning text. Tracked at
+``docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md`` § 13. Behavior pinned
+by ``tests/test_athena_extensions_registry.py`` and the buffer
+tests; ``add_hyperlink`` in a cell drops BOTH the URL and the link
+text (empirically, ``Insert`` on a cell-inner paragraph also fails
+with ``BlockNotFoundError`` — so the obvious ``add_run(text)``
+fallback can't even land the visible text without nuking the
+surrounding batch). The call returns a stub ``Hyperlink`` with an
+empty range so callers don't crash; insert any visible text via
+``cell.text = '...'`` before calling ``add_hyperlink`` if you need
+the link text to survive.
+
+### 0.11.4 behavior fixes elsewhere
+
+- **`Sections.__getitem__` short-circuits on empty docs.**
+  ``Document.create()`` doesn't materialize a section client-side,
+  so ``sections.list`` returns ``[]`` or times out at the full
+  command-budget. Pre-0.11.4 ``doc.sections[0]`` either raised an
+  un-contextualized ``IndexError`` from ``items[index]`` or hung
+  for ~60s. The cache-then-raise path now fails fast with a clear
+  workaround pointer and avoids re-issuing the slow query.
+- **`Table._fresh_node_info` rotation tracking.** Each ``Table``
+  created via ``Document.add_table`` records its document-order
+  position as ``_doc_index``. When SuperDoc rotates the table's
+  nodeId between saves, the fallback resolves the rotated address
+  by position instead of always picking the last ``doc.find`` item.
+  Pre-0.11.4 the "take the last" heuristic silently mapped N
+  rotated proxies onto a single target, surfacing as
+  ``ValidationError: Cell (r,c) not found in table table-auto-…``
+  on the next cell access.
+- **`set_borders` accepts string and dict.** Both
+  ``cell.set_borders(top="single 0.5pt #DDDDDD")`` and
+  ``cell.set_borders(top={"style": "single", "size_pt": 0.5,
+  "color": "#DDDDDD"})`` work; the string form is normalized via
+  ``_normalize_border_spec`` to the wire shape the server's Zod
+  validator expects. Pre-0.11.4 only the dict was accepted —
+  the string variant documented in the skill produced an immediate
+  HTTP 400 from the server's validator.
+- **`Run.add_field` segments shape.** ``run.add_field("PAGE")`` (and
+  every other field kind) now emits ``at.segments`` with
+  ``[{blockId, start, end}]`` instead of the ``{kind: "selection",
+  start, end}`` cursor envelope used by other create-ops.
+  SuperDoc's ``doc.fields.insert`` rejects the cursor form with
+  ``SuperDocCliError: fields insert:at.segments is required``;
+  pre-0.11.4 the call took down the whole batch on every flush.
+
 These additions are surfaced under their natural python-docx-shaped
 names. When python-docx upstream eventually ships any of them
 natively, the SDK should swap to the upstream signature in place;

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.11.2
+Version: 0.12.0
 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.12.0}/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.12.0"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.11.2 → athena_python_docx-0.12.0}/docx/_http_doc.py

@@ -262,14 +262,24 @@ _CELL_PARAGRAPH_HINT: str = (
     "\n\nHint: SuperDoc 1.8.1 cannot format paragraphs nested inside "
     "table cells via SetParagraphAlignment / SetParagraphStyle / "
     "SetParagraphIndentation / SetParagraphSpacing / doc.insert with "
-    "a paragraph-block target, or any FormatApply on a cell-inner run. "
-    "The cell's inner paragraph id is returned by cell.getNodeById but "
-    "isn't a top-level addressable block. Materialize the cell's "
-    'paragraph first via ``cell.text = "value"``, then re-read '
-    "``cell.paragraphs[0]`` and apply format ops to that post-"
-    "materialization Paragraph proxy. Tracked upstream at "
-    "docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md § 'cell-inner paragraph "
-    "addressing'."
+    "a paragraph-block target. The cell's original inner paragraph id "
+    "(returned by ``cell.paragraphs[0]`` on a freshly-loaded cell) "
+    "isn't a top-level addressable block.\n\nWorkaround: create a "
+    "fresh paragraph in the cell via ``para = cell.add_paragraph(text)`` "
+    "— 0.11.1+ routes that through ``doc.insert`` against the cell "
+    "with ``placement: 'insideEnd'``, so the returned ``Paragraph`` "
+    "proxy points at an addressable block. Apply format ops to that "
+    "proxy:\n\n"
+    '    para = cell.add_paragraph("MAY 2026")\n'
+    "    para.alignment = WD_ALIGN_PARAGRAPH.RIGHT  # works\n"
+    "    para.add_run(...).bold = True             # also works\n\n"
+    "Do NOT use ``cell.paragraphs[0].alignment = X`` on a freshly-"
+    "loaded cell — that targets the original cell-inner paragraph "
+    "which can't be addressed for format ops. If the cell already "
+    "has agent-authored content, use ``cell.paragraphs[-1]`` (the "
+    "most-recently-inserted paragraph, which is addressable). "
+    "Tracked upstream at docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md "
+    "§ 'cell-inner paragraph addressing'."
 )
 
 

{athena_python_docx-0.11.2 → athena_python_docx-0.12.0}/docx/commands.py

@@ -1451,6 +1451,30 @@ class ExportPDF(Command):
     include_revisions: bool | None = None
 
 
+@dataclass
+class ExportDocx(Command):
+    """Export the document as a ``.docx`` byte stream, optionally storing
+    it under ``destination`` (an asset id, S3 URL, or path).
+
+    Returns ``{bytes_base64, asset_id?}``. The docx-studio applier
+    routes through SuperDoc's ``exportDocx`` SDK call when available;
+    when the server build doesn't expose it, the command returns an
+    empty payload and the Python SDK raises a clear ``DocxError``
+    rather than silently writing zero bytes.
+
+    Athena extension beyond python-docx 1.x — closes the gap left by
+    ``Document.save(path)`` rejecting local targets (an asset-backed
+    SDK can't fulfill the implied "write bytes to disk" contract from
+    the buffer alone). Parity test harnesses against upstream
+    ``python-docx`` need a byte-for-byte export to diff against, and
+    pointing users at Olympus's Export DOCX action breaks every CI
+    workflow that runs headless.
+    """
+
+    destination: str | None = None
+    include_revisions: bool | None = None
+
+
 # ---------------------------------------------------------------------------
 # Numbering / List metadata reads (Athena extension — python-docx
 # issue #471 demands ``Paragraph.get_listnum()``-style access. The
@@ -1580,6 +1604,8 @@ _RESPONSE_BEARING_TYPES: frozenset[str] = frozenset(
         "CreateContentControl",
         # ExportPDF returns bytes the caller needs synchronously.
         "ExportPDF",
+        # ExportDocx returns .docx bytes the caller needs synchronously.
+        "ExportDocx",
         # FindReplace returns a replacement count for the caller.
         "FindReplace",
     }
@@ -1619,8 +1645,15 @@ from docx._athena_extension import (  # noqa: E402 — local circular import saf
 )
 
 
-def _mark_athena_extension_command(cls: type, issue: str, description: str) -> None:
+def _mark_athena_extension_command(
+    cls: type, issue: "str | None", description: str
+) -> None:
     setattr(cls, ATHENA_EXTENSION_ATTR, True)
+    # ``issue`` is ``None`` for additions that don't have a 1:1 upstream
+    # python-docx issue — typically things that are *not* missing from
+    # python-docx but that our asset-backed SDK has to surface differently
+    # (e.g. ``Document.export_docx`` because ``Document.save(path)``
+    # rejects local targets in this SDK).
     setattr(cls, ATHENA_EXTENSION_ISSUE_ATTR, issue)
     setattr(cls, ATHENA_EXTENSION_DESCRIPTION_ATTR, description)
     setattr(cls, ATHENA_EXTENSION_SINCE_ATTR, "0.11.0")
@@ -1672,6 +1705,7 @@ for _cls, _issue, _desc in [
     (FindReplace, "python-docx#30", "Formatting-preserving find/replace"),
     (IterRuns, "python-docx#980", "Run stream for run-isolation"),
     (ExportPDF, "python-docx#113", "PDF export"),
+    (ExportDocx, None, "DOCX export — local file roundtrip"),
     (NumberingGet, "python-docx#471", "Numbering metadata read"),
     (NumberingList, "python-docx#471", "Numbering enumeration"),
 ]:
@@ -1803,6 +1837,7 @@ __all__ = [
     "FindReplace",
     "IterRuns",
     "ExportPDF",
+    "ExportDocx",
     "NumberingGet",
     "NumberingList",
     # Helpers

{athena_python_docx-0.11.2 → athena_python_docx-0.12.0}/docx/document.py

@@ -168,6 +168,14 @@ class Document:
         # ``add_paragraph`` / ``add_heading`` / ``add_table`` resets this.
         self._last_list_item_id: str | None = None
         self._last_list_kind: str | None = None
+        # Document-order counter for tables created via ``add_table``.
+        # Captured at the time of creation and stamped on the Table
+        # proxy as ``_doc_index`` so the rotation fallback in
+        # ``Table._fresh_node_info`` can disambiguate when SuperDoc
+        # rotates the table's id between saves. Lazy-initialized to the
+        # current top-level table count so docs opened from an existing
+        # asset account for pre-existing tables.
+        self._table_doc_index_counter: int | None = None
 
     @classmethod
     @athena_extension(
@@ -1018,6 +1026,94 @@ class Document:
                     return b""
         return b""
 
+    @athena_extension(
+        since="0.11.4",
+        description="Document.export_docx — write the current state to a local .docx.",
+    )
+    def export_docx(
+        self,
+        path: "str | None" = None,
+        *,
+        include_revisions: bool = False,
+    ) -> bytes:
+        """Export the document's current state as ``.docx`` bytes.
+
+        Athena extension beyond python-docx 1.x. ``Document.save(path)``
+        is intentionally rejected by this SDK (``LocalSaveTargetNotSupportedError``)
+        because the buffer holds no local bytes — the source of truth
+        is the SuperDoc Y.Doc on docx-studio. ``export_docx`` is the
+        explicit "ship the current Y.Doc state to disk" escape hatch:
+        the server runs SuperDoc's ``exportDocx`` against the live
+        session and streams the bytes back, the SDK writes them to
+        ``path`` (when given) and returns them.
+
+        Parameters
+        ----------
+        path:
+            Optional local filesystem path. When provided, the bytes
+            are written there (parents must exist). Always returned
+            from the call regardless.
+        include_revisions:
+            When ``True``, accepted/pending tracked revisions are
+            baked into the exported document instead of being
+            collapsed to their resolved form.
+
+        Returns
+        -------
+        bytes
+            The full ``.docx`` payload.
+
+        Raises
+        ------
+        DocxError
+            When the server-side SuperDoc build doesn't expose
+            ``exportDocx`` (older docx-studio deploys), the command
+            returns an empty payload and this method raises a clear
+            ``DocxError`` instead of silently writing 0 bytes.
+        """
+        from docx.commands import ExportDocx
+        from docx.errors import DocxError
+
+        # Drain anything pending so the export reflects every queued
+        # mutation. ``send_command`` for a response-bearing command
+        # already flushes, but the explicit save makes intent visible
+        # in tracebacks if anything below fails.
+        self.save()
+
+        result = run_sync(
+            self._session.send_command(
+                ExportDocx(
+                    destination=None,
+                    include_revisions=include_revisions,
+                ),
+            ),
+        )
+        payload: bytes = b""
+        if isinstance(result, dict):
+            import base64
+
+            b64 = result.get("bytesBase64") or result.get("bytes_base64")
+            if isinstance(b64, str):
+                try:
+                    payload = base64.b64decode(b64)
+                except (ValueError, TypeError):
+                    payload = b""
+
+        if not payload:
+            raise DocxError(
+                "docx-studio returned no bytes for ExportDocx. Either "
+                "the server build doesn't expose SuperDoc's exportDocx "
+                "yet (upgrade docx-studio) or the asset is in a state "
+                "that can't be serialized to .docx. Use to_pdf() as a "
+                "stopgap, or fall back to Olympus's Export DOCX action "
+                "for an interactive export."
+            )
+
+        if path is not None:
+            with open(path, "wb") as f:
+                f.write(payload)
+        return payload
+
     @athena_extension(issue=425, description="Document.add_bookmark.")
     def add_bookmark(
         self,
@@ -1377,6 +1473,13 @@ class Document:
         # SuperDoc id via per-batch ``clientIdMap``, so any subsequent
         # ``set_style({nodeId: cli_id})`` resolves correctly server-side.
         client_node_id = self._mint_client_node_id("t")
+        # Resolve the next document-order position for this new table.
+        # First call queries ``doc.find`` to account for any tables that
+        # already existed when the Document was opened — Document.create()
+        # docs start at 0, ``Document(existing_asset_id)`` starts at
+        # whatever count the asset has.
+        doc_index = self._next_table_doc_index()
+
         table_params: dict = {
             "rows": rows,
             "columns": cols,
@@ -1402,10 +1505,50 @@ class Document:
             node_id=node_id,
             rows=rows,
             columns=cols,
+            doc_index=doc_index,
         )
         self._register_proxy_id(client_node_id, tbl)
         return tbl
 
+    def _next_table_doc_index(self) -> int:
+        """Return the session-relative position the next ``add_table``
+        will occupy, then increment the counter.
+
+        ``_doc_index`` is intentionally session-relative (0-based among
+        tables added in *this* Document handle's lifetime) rather than
+        document-absolute. Pre-0.11.4 (the lazy-init attempt) queried
+        ``doc.find({"type": "table"})`` on the first ``add_table`` to
+        seed the counter with the count of pre-existing tables — but
+        that added a stray ``find`` op to every Document's wire log,
+        which broke the op-snapshot drift tests in
+        ``tests/fidelity/op_snapshots/``. ``Table._fresh_node_info`` does
+        the offset math at rotation-lookup time instead (``items[len(
+        items) - session_count + _doc_index]``), reading the live
+        session count off the buffer attribute set below. For
+        ``Document.create()`` docs (the common case) the offset is 0
+        and the lookup degenerates to the obvious ``items[_doc_index]``.
+
+        Defensive against unit tests that construct ``Document`` via
+        ``Document.__new__`` (skipping ``__init__``) — those instances
+        don't have ``_table_doc_index_counter`` set, so we read it via
+        ``getattr`` and fall back to a fresh local counter that we
+        write back through ``setattr``.
+        """
+        counter = getattr(self, "_table_doc_index_counter", None) or 0
+        idx = counter
+        new_count = idx + 1
+        self._table_doc_index_counter = new_count
+        # Expose the live session count via the session so Table proxies
+        # can compute the offset in ``_fresh_node_info`` rotation
+        # fallbacks without holding a direct reference back to Document.
+        try:
+            session = getattr(self, "_session", None)
+            if session is not None:
+                session._table_session_count = new_count  # type: ignore[attr-defined]
+        except Exception:
+            pass
+        return idx
+
     def add_picture(
         self,
         image_path_or_stream: str | BinaryIO,

athena_python_docx-0.12.0/docx/oxml/__init__.py

@@ -0,0 +1,228 @@
+"""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 Python's native
+      ``TypeError: isinstance() arg 2 must be a type, a tuple of
+      types, or a union`` (CPython validates the second argument is a
+      type before consulting ``__instancecheck__``, so the proxy never
+      sees the call). Agents who reach for it land in the same
+      "this surface isn't real" place via a different error class —
+      the message names ``isinstance`` so the typed
+      :class:`OxmlNotAvailableError` route isn't required to surface
+      the gap.
+
+    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.
+
+    The proxy is cached into module globals so a second access skips
+    ``__getattr__`` and returns the same instance — matches the
+    per-submodule caching done by :meth:`_OxmlStubModule.__getattr__`.
+    """
+    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
+    proxy = _LazyRaisingProxy(f"docx.oxml.{name}")
+    globals()[name] = proxy
+    return proxy
+
+
+__all__ = ["OxmlNotAvailableError"]