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

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

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

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

@@ -75,9 +75,15 @@ class _LazyRaisingProxy:
       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).
+    * ``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
@@ -197,6 +203,10 @@ def __getattr__(name: str) -> Any:  # noqa: ANN401
     :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)
@@ -210,7 +220,9 @@ def __getattr__(name: str) -> Any:  # noqa: ANN401
             mod = _OxmlStubModule(full)
             sys.modules[full] = mod
         return mod
-    return _LazyRaisingProxy(f"docx.oxml.{name}")
+    proxy = _LazyRaisingProxy(f"docx.oxml.{name}")
+    globals()[name] = proxy
+    return proxy
 
 
 __all__ = ["OxmlNotAvailableError"]

{athena_python_docx-0.11.3 → athena_python_docx-0.12.0}/docx/section.py

@@ -890,18 +890,57 @@ class Sections(Sequence["Section"]):
     Subclasses :class:`collections.abc.Sequence` so ``count``,
     ``index``, ``__contains__``, and ``__reversed__`` come for free —
     this matches python-docx's :class:`docx.section.Sections`.
+
+    Implementation notes
+    --------------------
+
+    ``_items()`` is cached for the lifetime of this proxy. python-docx
+    semantics are that ``doc.sections`` is a stable handle whose ``len``
+    only changes when the user explicitly adds a section break — which
+    the SuperDoc-backed SDK can't currently do anyway — so re-querying
+    on every ``len()`` / ``__getitem__`` would be wasteful and turns
+    every accidental ``for section in doc.sections`` into N HTTP round
+    trips.
+
+    The list is also defensively short-circuited when ``sections.list``
+    raises (the SuperDoc query has been observed to hang for the full
+    60s command timeout on docs created with ``Document.create()`` when
+    SuperDoc has not yet materialized a default section). Without the
+    catch, ``len(doc.sections)`` / ``doc.sections[0]`` block the calling
+    script for a minute and then raise; with it, the SDK fails fast
+    with a clear ``RuntimeError`` that names the workaround.
     """
 
     def __init__(self, *, session: "Session") -> None:
         self._session: "Session" = session
+        self._items_cache: "list[dict] | None" = None
 
     def _items(self) -> list[dict]:
-        info: object = run_sync(self._session.doc.sections.list({}))
+        if self._items_cache is not None:
+            return self._items_cache
+        try:
+            info: object = run_sync(self._session.doc.sections.list({}))
+        except Exception:  # noqa: BLE001
+            # Common case: SuperDoc has not materialized a default
+            # section yet, and ``sections.list`` either returns ``[]``
+            # or hangs through the full command timeout. Cache the
+            # empty result so subsequent accesses are O(1) and never
+            # re-hang the calling script.
+            self._items_cache = []
+            return self._items_cache
+        items_list: list[dict] = []
         if isinstance(info, dict):
             items: object = info.get("items", [])
             if isinstance(items, list):
-                return [i for i in items if isinstance(i, dict)]
-        return []
+                items_list = [i for i in items if isinstance(i, dict)]
+        self._items_cache = items_list
+        return self._items_cache
+
+    def _invalidate(self) -> None:
+        """Drop the cached items list. Call after operations that may
+        add a new section break (currently none — kept for forward
+        compatibility with future ``add_section`` support)."""
+        self._items_cache = None
 
     def __iter__(self):
         for item in self._items():
@@ -914,6 +953,29 @@ class Sections(Sequence["Section"]):
 
     def __getitem__(self, index: int) -> Section:
         items = self._items()
+        if not items:
+            raise IndexError(
+                f"doc.sections is empty (index {index} requested). "
+                f"Document.create() does not materialize a default "
+                f"section client-side; SuperDoc's exported styles.xml "
+                f"is the source of truth for page setup. Page size, "
+                f"margins, headers, footers, and column count cannot "
+                f"currently be configured at this layer — track the "
+                f"unblock at docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md "
+                f"§ 'sections.list on net-new docs'."
+            )
+        # Mirror Python list / Sequence semantics for negative indices.
+        # python-docx's ``Sections`` inherits ``collections.abc.Sequence``
+        # whose default ``__getitem__`` supports ``-1`` → last,
+        # ``-2`` → second-to-last, etc. The earlier ``0 <= index <
+        # len(items)`` check rejected those, breaking
+        # ``doc.sections[-1]``.
+        if index < 0:
+            index += len(items)
+        if not 0 <= index < len(items):
+            raise IndexError(
+                f"doc.sections index out of range (len={len(items)})"
+            )
         addr = items[index].get("address", {})
         if not isinstance(addr, dict):
             raise IndexError(f"Section {index} has no address")

athena_python_docx-0.12.0/docx/session.py

@@ -0,0 +1,27 @@
+"""Discoverability alias — re-exports the public batching surface.
+
+Agents repeatedly try ``from docx.session import run_sync`` (verified
+in LangSmith thread ``thread_28dae56c-…`` on PR #20788 preview, where
+the model burned a tool-call iteration on
+``ModuleNotFoundError: No module named 'docx.session'`` before falling
+back to ``inspect.getsource``). The canonical home is the private
+``docx._batching`` module, but the leading-underscore prefix isn't a
+signal LLMs read reliably. This shim exists to fail less surprisingly.
+
+Stable surface — these are also exported from :mod:`docx._batching`
+and either path is supported:
+
+* :func:`run_sync` — drive an async coroutine from a sync call site.
+* :data:`DEFAULT_OP_TIMEOUT_SECONDS` — the timeout the ``run_sync``
+  shim applies before raising ``concurrent.futures.TimeoutError``.
+
+Anything else inside :mod:`docx._batching` is implementation detail
+and may move without a deprecation cycle; this module deliberately
+re-exports only the surface agents have a legitimate reason to call.
+"""
+
+from __future__ import annotations
+
+from docx._batching import DEFAULT_OP_TIMEOUT_SECONDS, run_sync
+
+__all__ = ["run_sync", "DEFAULT_OP_TIMEOUT_SECONDS"]