athena-python-docx 0.15.1__tar.gz → 0.15.3__tar.gz

{athena_python_docx-0.15.1 → athena_python_docx-0.15.3}/CLAUDE.md

@@ -338,6 +338,19 @@ Issue numbers reference `python-openxml/python-docx`.
   `"endnotes"` / `"comments"` / `"all"`. Routes through
   `FindReplace`.
 
+- **`Document.find_text(pattern, *, regex=False, match_case=False,
+  whole_word=False, in_=None, max_results=20, context_chars=80)
+  -> dict`** — fast bounded text search for large-doc inspection.
+  Returns `{count, matches, truncated}` with context snippets instead
+  of exporting the whole `.docx` or walking every paragraph/run through
+  live SDK reads. Routes through `FindText`.
+
+- **`Document.iter_runs(*, in_=None, limit=None, offset=None)
+  -> list[dict]`** — server-side run enumeration for large-doc
+  inspection. Use this when an agent needs to sample or inspect runs
+  without issuing one ``getNodeById`` query per paragraph through
+  ``doc.paragraphs`` + ``paragraph.runs``. Routes through `IterRuns`.
+
 - **`Paragraph.list_id` / `Paragraph.list_level` /
   `Paragraph.list_format` / `Paragraph.list_number`** — list-item
   numbering reads. python-docx issue #471 (13 👍) demands access to

athena_python_docx-0.15.3/DOCX_EXEC_LAB.md

@@ -0,0 +1,189 @@
+# DocX Execution Lab
+
+`scripts/docx_exec_lab.py` is a headless runner for quickly testing
+`athena-python-docx` snippets against Athena SuperDocument assets. It
+shortens the debug loop by running local SDK code directly against a
+chosen DOCX Studio API, capturing stdout/stderr/errors/timings, and
+optionally exporting the result to `.docx` for assertions.
+
+Use this before waiting on a full Agent -> Daytona -> preview cycle when
+debugging SDK behavior such as large-document replacement, table fills,
+unsupported OOXML internals, or export fidelity.
+
+## Inputs
+
+The runner accepts code from `--code-file` or stdin. It injects:
+
+- `ATHENA_DOCX_ASSET_ID` - the asset id passed with `--asset-id`
+- `ATHENA_DOCX_BASE_URL` and `DOCX_STUDIO_BASE_URL` - when `--base-url` is set
+- `DOCX_EXEC_LAB_OUTPUT_DIR` - output folder for the run
+- `DOCX_EXEC_LAB_EXPORT_PATH` - export target when `--export-docx` is set
+
+Authentication is read from the normal SDK environment, usually:
+
+```bash
+export ATHENA_DOCX_API_KEY="<your-api-key>"
+```
+
+Do not commit API keys. Use shell env vars or your local secret manager.
+
+## Run Against A PR Preview
+
+```bash
+cd docx-studio/python-sdk
+
+export ATHENA_DOCX_API_KEY="<your-api-key>"
+
+uv run python scripts/docx_exec_lab.py \
+  --base-url "https://docx-studio-pr21665-preview.previews.athenaintel.com" \
+  --asset-id "asset_..." \
+  --code-file scripts/docx_exec_lab_examples/find_replace_literal.py \
+  --timeout 30 \
+  --output-dir /tmp/docx-lab-find-replace \
+  --export-docx \
+  --assert-stdout-contains "Replacements made:" \
+  --assert-docx-text-contains "[Purchaser]"
+```
+
+The script writes structured JSON to `<output-dir>/result.json` and
+prints the same JSON to stdout. The JSON includes success flags,
+duration, stdout, stderr, exit code, error text, code path, asset id, and
+artifact paths.
+
+## Run Against Staging
+
+```bash
+cd docx-studio/python-sdk
+
+export ATHENA_DOCX_API_KEY="<your-staging-api-key>"
+export ATHENA_DOCX_BASE_URL="https://docx-studio.stg.athenaintel.com"
+
+uv run python scripts/docx_exec_lab.py \
+  --asset-id "asset_..." \
+  --code-file scripts/docx_exec_lab_examples/fast_table_fill.py \
+  --timeout 30 \
+  --output-dir /tmp/docx-lab-table-fill \
+  --export-docx \
+  --assert-stdout-contains "Filled 4 table rows" \
+  --assert-docx-text-contains "LOW (NYSE)"
+```
+
+## Run Against Local DOCX Studio
+
+Start DOCX Studio locally, then point the runner at that base URL:
+
+```bash
+cd docx-studio/python-sdk
+
+export ATHENA_DOCX_API_KEY="<local-or-dev-api-key>"
+
+uv run python scripts/docx_exec_lab.py \
+  --base-url "http://localhost:3001" \
+  --asset-id "asset_..." \
+  --code-file scripts/docx_exec_lab_examples/find_replace_literal.py \
+  --output-dir /tmp/docx-lab-local \
+  --export-docx
+```
+
+## Local UI With SuperDoc Embed
+
+The lab also includes a local-only HTML UI that wraps the same headless
+runner and iframes Olympus's existing SuperDoc embed route.
+
+```bash
+cd docx-studio/python-sdk
+
+export ATHENA_DOCX_API_KEY="<your-staging-api-key>"
+
+uv run python scripts/docx_exec_lab_server.py --open
+```
+
+Defaults:
+
+- DOCX Studio API: `https://docx-studio.stg.athenaintel.com`
+- Agora embed-token API: `https://agora-staging.athenaintel.com`
+- Olympus iframe host: `https://staging-app.athenaintel.com`
+
+The UI accepts an `asset_id`, Python code, and optional assertions. The
+right pane can mint an editable embed token through staging Agora and
+iframe the returned `https://staging-app.athenaintel.com/embed/{token}`
+URL, so changes render in the real Olympus/SuperDoc viewer.
+
+If the staging Agora URL differs, pass:
+
+```bash
+uv run python scripts/docx_exec_lab_server.py \
+  --agora-base-url "https://..." \
+  --olympus-base-url "https://staging-app.athenaintel.com" \
+  --docx-base-url "https://docx-studio.stg.athenaintel.com"
+```
+
+The page also has an API key field. Values entered there are sent only
+to the local server for that request and are not written to `result.json`.
+
+## Use Stdin For One-Off Repros
+
+```bash
+cd docx-studio/python-sdk
+
+printf '%s\n' \
+  'import os' \
+  'from docx import Document' \
+  'doc = Document(os.environ["ATHENA_DOCX_ASSET_ID"])' \
+  'print(doc.asset_id)' \
+  | uv run python scripts/docx_exec_lab.py \
+      --asset-id "asset_..." \
+      --base-url "https://docx-studio-pr21665-preview.previews.athenaintel.com" \
+      --assert-stdout-contains "asset_"
+```
+
+## Export Assertions
+
+When `--export-docx` is set, the snippet must leave an open global
+variable named `doc`. The lab calls:
+
+```python
+doc.export_docx("<output-dir>/exported.docx")
+```
+
+Then `--assert-docx-text-contains` extracts text from the exported Word
+XML and checks for expected content. This catches "the command returned
+success but the document did not change" failures.
+
+If a snippet needs custom export behavior, pass `--export-path` without
+`--export-docx` and write `os.environ["DOCX_EXEC_LAB_EXPORT_PATH"]`
+inside the snippet. The lab records that file if it exists.
+
+## Table Fill Guidance
+
+Use the fast cell text path for bulk table values:
+
+```python
+table = doc.add_table(rows=len(rows), cols=2, style="Table Grid")
+for row_index, (label, value) in enumerate(rows):
+    table.cell(row_index, 0).text = label
+    table.cell(row_index, 1).text = value
+doc.save()
+```
+
+Avoid reading `cell.paragraphs[0].runs[0]` inside the fill loop. That
+interleaves writes with remote reads, flushes pending operations, and is
+much slower on real assets.
+
+## Opt-In Real Asset Smoke
+
+The unit tests do not require network access. A real export smoke is
+available but skipped unless explicitly enabled:
+
+```bash
+cd docx-studio/python-sdk
+
+export ATHENA_DOCX_LAB_RUN_INTEGRATION=1
+export ATHENA_DOCX_LAB_ASSET_ID="asset_..."
+export ATHENA_DOCX_API_KEY="<your-api-key>"
+export ATHENA_DOCX_BASE_URL="https://docx-studio-pr21665-preview.previews.athenaintel.com"
+
+uv run pytest tests/test_docx_exec_lab.py -m integration -q
+```
+
+Use disposable or test assets for mutation snippets.

{athena_python_docx-0.15.1 → athena_python_docx-0.15.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.15.1
+Version: 0.15.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>
@@ -67,6 +67,15 @@ uv pip install -e ".[dev]"
 uv run pytest tests/ -x
 ```
 
+## DocX Execution Lab
+
+For fast local repros against real Athena document assets, use the
+headless runner in `scripts/docx_exec_lab.py`. It executes an arbitrary
+Python snippet with this checkout of `athena-python-docx`, captures
+stdout/stderr/errors/timings, and can export the resulting `.docx` for
+text assertions. `scripts/docx_exec_lab_server.py` adds a local UI with
+an Olympus/SuperDoc embed preview pane. See `DOCX_EXEC_LAB.md`.
+
 ## Environment variables
 
 Required when connecting to Keryx (set by Athena backend when executing in Daytona):

{athena_python_docx-0.15.1 → athena_python_docx-0.15.3}/README.md

@@ -40,6 +40,15 @@ uv pip install -e ".[dev]"
 uv run pytest tests/ -x
 ```
 
+## DocX Execution Lab
+
+For fast local repros against real Athena document assets, use the
+headless runner in `scripts/docx_exec_lab.py`. It executes an arbitrary
+Python snippet with this checkout of `athena-python-docx`, captures
+stdout/stderr/errors/timings, and can export the resulting `.docx` for
+text assertions. `scripts/docx_exec_lab_server.py` adds a local UI with
+an Olympus/SuperDoc embed preview pane. See `DOCX_EXEC_LAB.md`.
+
 ## Environment variables
 
 Required when connecting to Keryx (set by Athena backend when executing in Daytona):

{athena_python_docx-0.15.1 → athena_python_docx-0.15.3}/docx/__init__.py

@@ -6,11 +6,11 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.15.1"
+__version__ = "0.15.3"
 
-from docx._execution import begin_execution
 from docx.api import Document
 from docx._buffer import flush_all
+
 # Re-exports python-docx ships at docx top-level for convenience.
 from docx.shared import Emu, Inches, Pt, Cm, Mm, Twips, Length, RGBColor
 
@@ -24,7 +24,6 @@ __all__ = [
     "Twips",
     "Length",
     "RGBColor",
-    "begin_execution",
     "flush_all",
     "__version__",
 ]

{athena_python_docx-0.15.1 → athena_python_docx-0.15.3}/docx/_batching.py

@@ -7,16 +7,14 @@ This is the only place in the SDK that uses threading.
 from __future__ import annotations
 
 import asyncio
+import concurrent.futures
 import threading
 from typing import Any, Coroutine, TypeVar
 
-T = TypeVar("T")
+from docx._timeouts import DEFAULT_OP_TIMEOUT_SECONDS
+from docx.errors import OperationTimeoutError
 
-# Default per-op timeout. Individual Superdoc SDK calls should complete well
-# under this — the value is a safety net so a WebSocket stall or Keryx
-# downtime surfaces a TimeoutError instead of wedging the calling thread
-# until the outer Daytona INSTRUCTION_TIMEOUT_SECONDS kill.
-DEFAULT_OP_TIMEOUT_SECONDS: float = 60.0
+T = TypeVar("T")
 
 _loop: asyncio.AbstractEventLoop | None = None
 _thread: threading.Thread | None = None
@@ -64,13 +62,17 @@ def run_sync(
             (use sparingly — prefer the default so stalls surface early).
 
     Raises:
-        concurrent.futures.TimeoutError: if the coroutine does not
-            complete within `timeout` seconds.
+        OperationTimeoutError: if the coroutine does not complete within
+            `timeout` seconds.
         The coroutine's exception, re-raised in the calling thread.
     """
     loop = _ensure_loop()
     future = asyncio.run_coroutine_threadsafe(coro, loop)
-    return future.result(timeout=timeout)
+    try:
+        return future.result(timeout=timeout)
+    except concurrent.futures.TimeoutError as exc:
+        future.cancel()
+        raise OperationTimeoutError(timeout_seconds=timeout) from exc
 
 
 def shutdown() -> None:

{athena_python_docx-0.15.1 → athena_python_docx-0.15.3}/docx/_buffer.py

@@ -39,6 +39,7 @@ from docx._execution import (
     current_execution_id,
     is_stale_execution,
 )
+from docx._timeouts import timeout_for_commands
 from docx.commands import Command, is_response_bearing, must_flush_immediately
 from docx.errors import DocxError, FlushAllError
 
@@ -113,6 +114,7 @@ def _extract_partial_results(exc: BaseException) -> list[Any]:
                 out.append(result)
     return out
 
+
 if TYPE_CHECKING:
     from docx._http_doc import HttpClient
 
@@ -223,18 +225,39 @@ def flush_all(*, strict: bool = False) -> None:
                 sys.stderr.write(f"[docx-sdk] flush_all: {msg}\n")
 
     if failures:
-        raise FlushAllError(failures)
+        raise FlushAllError(failures=failures)
 
 
 # ---------------------------------------------------------------------------
 # CommandBuffer
 # ---------------------------------------------------------------------------
 
-# Idle window before a pure-mutation buffer auto-flushes. Short by design —
-# the SDK's main consumer is agent code that fires sequential property
-# setters within milliseconds of each other; we just need to coalesce those
-# without holding writes back from Keryx for human-perceptible time.
-DEFAULT_AUTO_FLUSH_SECONDS: float = 0.1
+
+def _default_auto_flush_seconds() -> float:
+    """Return the transparent-batching idle window.
+
+    A very small window streams single edits quickly, but it can also flush
+    generated table-population loops halfway through the loop. That is painful
+    on large legal documents because each partial table batch can take longer
+    than the normal client timeout. Keep the default human-fast while giving
+    agent code enough room to coalesce common loops; allow local override for
+    debugging.
+    """
+    import os
+
+    raw = os.environ.get("ATHENA_DOCX_AUTO_FLUSH_SECONDS")
+    if raw is None:
+        return 1.0
+    try:
+        return max(float(raw), 0.0)
+    except ValueError:
+        return 1.0
+
+
+# Idle window before a pure-mutation buffer auto-flushes. Agent-generated
+# loops commonly perform dozens of property setters; a 1s window still feels
+# live while avoiding mid-loop table flushes on large documents.
+DEFAULT_AUTO_FLUSH_SECONDS: float = _default_auto_flush_seconds()
 
 
 class CommandBuffer:
@@ -305,6 +328,12 @@ class CommandBuffer:
         with self._lock:
             return len(self._pending)
 
+    @property
+    def pending_timeout_seconds(self) -> float:
+        with self._lock:
+            pending = list(self._pending)
+        return timeout_for_commands(commands=pending)
+
     @property
     def is_stale_for_current_execution(self) -> bool:
         return is_stale_execution(self._execution_id)
@@ -476,10 +505,13 @@ class CommandBuffer:
             return
         try:
             if self.is_stale_for_current_execution:
+                pending: list[Command]
                 with self._lock:
                     self._cancel_timer_locked()
+                    pending = self._pending
                     self._pending = []
                     self._proxy_id_refs = {}
+                _ptc_emit_end_batch(pending, is_error=True)
             else:
                 self.flush()
         finally:
@@ -553,6 +585,8 @@ class CommandBuffer:
             self._timer = None
 
     def _auto_flush(self) -> None:
+        if self.is_stale_for_current_execution:
+            return
         try:
             self.flush()
         except Exception as e:  # noqa: BLE001

{athena_python_docx-0.15.1 → athena_python_docx-0.15.3}/docx/_http_doc.py

@@ -38,6 +38,7 @@ from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
 from docx._buffer import CommandBuffer
+from docx._timeouts import timeout_for_commands
 from docx.commands import (
     BlocksList,
     BookmarksGet,
@@ -86,6 +87,7 @@ from docx.commands import (
     FieldsRefresh,
     Find,
     FindReplace,
+    FindText,
     FootnotesDelete,
     FootnotesGet,
     FootnotesList,
@@ -210,9 +212,7 @@ def _looks_like_block_not_found(err_obj: dict) -> bool:
         return False
     lower = msg.lower()
     if "not found" in lower:
-        return 'block "' in lower or (
-            'block ' in lower and ' was not found' in lower
-        )
+        return 'block "' in lower or ("block " in lower and " was not found" in lower)
     if "invalid_target" in lower or "invalid target" in lower:
         # "Expected paragraph:<id> but found tableCell:<id>" — the new
         # variant of the § 13 cell-inner-paragraph addressing gap.
@@ -323,7 +323,7 @@ _TABLE_QUERY_COMMANDS: frozenset[str] = frozenset(
 
 _TABLE_CLIENT_ID_HINT: str = (
     "\n\nHint: this looks like a stale client-side table UUID "
-    '(``t_xxxxxxxxxxxx``). Either an earlier batch in this execution '
+    "(``t_xxxxxxxxxxxx``). Either an earlier batch in this execution "
     "raised before the SDK could rewrite the Table proxy's id from the "
     "client UUID to the real SuperDoc id, OR the table belongs to a "
     "prior execution whose state has been discarded. Recover by calling "
@@ -521,8 +521,7 @@ def _http_post_json(
         if is_remote_disconnect:
             n_commands = (
                 len(body.get("commands", []))
-                if isinstance(body, dict)
-                and isinstance(body.get("commands"), list)
+                if isinstance(body, dict) and isinstance(body.get("commands"), list)
                 else 0
             )
             hint = (
@@ -608,13 +607,9 @@ def _http_post_json(
             if _looks_like_block_not_found(err_obj):
                 cmd_type = err_obj.get("type")
                 paragraph_targeting = (
-                    isinstance(cmd_type, str)
-                    and cmd_type in _PARAGRAPH_TARGETING_COMMANDS
-                )
-                table_query = (
-                    isinstance(cmd_type, str)
-                    and cmd_type in _TABLE_QUERY_COMMANDS
+                    isinstance(cmd_type, str) and cmd_type in _PARAGRAPH_TARGETING_COMMANDS
                 )
+                table_query = isinstance(cmd_type, str) and cmd_type in _TABLE_QUERY_COMMANDS
                 if paragraph_targeting:
                     hint = _CELL_PARAGRAPH_HINT
                 elif table_query:
@@ -749,6 +744,7 @@ class HttpClient:
             url=url,
             api_key=self._api_key,
             body=body,
+            timeout=timeout_for_commands(commands=commands),
         )
         applied = resp.get("applied")
         # An empty applied list paired with an `error` field is the
@@ -881,7 +877,6 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "track_changes.list": TrackChangesList,
     "track_changes.get": TrackChangesGet,
     "track_changes.decide": TrackChangesDecide,
-
     # --- Athena-extension ops (v0.11.0) -----------------------------------
     # Mirror the dotted-path style of the upstream-parity routes above:
     # ``hyperlinks.create`` matches SuperDoc's ``doc.hyperlinks.create``.
@@ -928,6 +923,7 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "sdt.delete": ContentControlsDelete,
     "sections.set_columns": SetSectionColumns,
     "find_replace": FindReplace,
+    "find_text": FindText,
     "iter_runs": IterRuns,
     "export_pdf": ExportPDF,
     "numbering.get": NumberingGet,
@@ -968,6 +964,7 @@ _FIELD_RENAMES: dict[str, dict[str, str]] = {
     # path-proxy snake-case transform leaves `in` as a Python keyword
     # collision; rename to `in_` here so the dataclass accepts it.
     "find_replace": {"in": "in_"},
+    "find_text": {"in": "in_"},
     "iter_runs": {"in": "in_"},
     "numbering.list": {"in": "in_"},
 }
@@ -983,9 +980,7 @@ def _build_command(op: str, params: dict[str, Any]) -> Command:
         )
 
     # Convert param keys camelCase → snake_case to match dataclass fields.
-    snake_params: dict[str, Any] = {
-        _camel_to_snake(k): v for k, v in params.items()
-    }
+    snake_params: dict[str, Any] = {_camel_to_snake(k): v for k, v in params.items()}
 
     # Apply per-op renames (e.g. find: type → node_type).
     renames = _FIELD_RENAMES.get(op)

athena_python_docx-0.15.3/docx/_timeouts.py

@@ -0,0 +1,32 @@
+"""Timeout budgets for SDK operations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+DEFAULT_OP_TIMEOUT_SECONDS: float = 60.0
+
+# Large document-wide primitives can be intentionally expensive while still
+# being the safest path for agents. Keep the normal SDK budget tight, but give
+# these one-shot commands enough room to finish on dense legal documents.
+LONG_RUNNING_COMMAND_TIMEOUT_SECONDS: float = 300.0
+
+_LONG_RUNNING_COMMAND_TYPES: frozenset[str] = frozenset(
+    {
+        "FindReplace",
+        # Plain ``cell.text = value`` table fills are buffered as TableSetCell
+        # commands. On dense legal documents, SuperDoc can spend well over the
+        # ordinary 60s budget committing a table batch even when the Python code
+        # uses the fast no-read cell path.
+        "TableSetCell",
+    }
+)
+
+
+def timeout_for_commands(*, commands: list[Any]) -> float:
+    """Return the HTTP timeout budget for a batch of command objects."""
+    for command in commands:
+        command_type = getattr(command, "type", type(command).__name__)
+        if command_type in _LONG_RUNNING_COMMAND_TYPES:
+            return LONG_RUNNING_COMMAND_TIMEOUT_SECONDS
+    return DEFAULT_OP_TIMEOUT_SECONDS

{athena_python_docx-0.15.1 → athena_python_docx-0.15.3}/docx/client.py

@@ -23,6 +23,7 @@ from contextlib import asynccontextmanager
 from typing import TYPE_CHECKING, Any
 
 from docx._execution import assert_current_execution, current_execution_id
+from docx._timeouts import DEFAULT_OP_TIMEOUT_SECONDS
 from docx.errors import (
     AuthenticationError,
     DocumentClosedError,
@@ -99,6 +100,21 @@ class Session:
     def is_open(self) -> bool:
         return self._opened and not self._closed
 
+    @property
+    def pending_timeout_seconds(self) -> float:
+        handle = self._doc_handle
+        buffer = getattr(handle, "buffer", None) if handle is not None else None
+        timeout = (
+            getattr(buffer, "pending_timeout_seconds", DEFAULT_OP_TIMEOUT_SECONDS)
+            if buffer is not None
+            else DEFAULT_OP_TIMEOUT_SECONDS
+        )
+        if isinstance(timeout, bool):
+            return DEFAULT_OP_TIMEOUT_SECONDS
+        if isinstance(timeout, (int, float)):
+            return float(timeout)
+        return DEFAULT_OP_TIMEOUT_SECONDS
+
     async def open(self) -> None:
         """Construct the HTTP client + buffered doc handle.
 

{athena_python_docx-0.15.1 → athena_python_docx-0.15.3}/docx/commands.py

@@ -1510,6 +1510,27 @@ class FindReplace(Command):
     max_replacements: int | None = None
 
 
+@dataclass
+class FindText(Command):
+    """Search document text and return bounded match context.
+
+    Athena extension beyond python-docx 1.x. This is the read-side
+    companion to :class:`FindReplace`: it avoids exporting a full
+    ``.docx`` or walking every paragraph/run when callers only need a
+    match count plus a few snippets. ``max_results`` limits how many
+    contexts come back; ``count`` in the result remains the total
+    number of matches found.
+    """
+
+    pattern: str = ""
+    regex: bool | None = None
+    match_case: bool | None = None
+    whole_word: bool | None = None
+    in_: str | dict[str, Any] | None = None
+    max_results: int | None = None
+    context_chars: int | None = None
+
+
 @dataclass
 class IterRuns(Command):
     """Stream runs across the document (with story locator + offset)
@@ -1637,6 +1658,7 @@ _QUERY_TYPES: frozenset[str] = frozenset(
         "ContentControlsGet",
         "NumberingGet",
         "NumberingList",
+        "FindText",
         "IterRuns",
     }
 )
@@ -1741,9 +1763,7 @@ from docx._athena_extension import (  # noqa: E402 — local circular import saf
 )
 
 
-def _mark_athena_extension_command(
-    cls: type, issue: "str | None", 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
@@ -1799,6 +1819,7 @@ for _cls, _issue, _desc in [
     (ContentControlsDelete, "python-docx#155", "SDT delete"),
     (SetSectionColumns, "python-docx#167", "Section multi-column layout"),
     (FindReplace, "python-docx#30", "Formatting-preserving find/replace"),
+    (FindText, "python-docx#980", "Fast document text search"),
     (IterRuns, "python-docx#980", "Run stream for run-isolation"),
     (ExportPDF, "python-docx#113", "PDF export"),
     (ExportDocx, None, "DOCX export — local file roundtrip"),
@@ -1931,6 +1952,7 @@ __all__ = [
     "ContentControlsDelete",
     "SetSectionColumns",
     "FindReplace",
+    "FindText",
     "IterRuns",
     "ExportPDF",
     "ExportDocx",