athena-python-docx 0.10.0__tar.gz → 0.11.0__tar.gz

{athena_python_docx-0.10.0 → athena_python_docx-0.11.0}/CLAUDE.md

@@ -81,12 +81,46 @@ remaining work* for the exact wire-op shape needed to unblock each.
 These differ from stock python-docx because the SDK is asset-backed,
 not file-backed. Each is documented in the relevant docstring.
 
-- **`Document.create(name=, base_url=, api_key=, parent_folder_id=, workspace_id=)`**
+- **Built-in table style friendly names resolve to OOXML styleIds.**
+  Word's ``styles.xml`` ships built-in table styles whose styleIds
+  (``LightGrid-Accent1``, ``MediumShading1-Accent2``, …) differ from
+  their display names (``"Light Grid Accent 1"``, …). Stock
+  python-docx resolves the friendly form against the loaded
+  document's styles collection at write time. We can't read
+  ``styles.xml`` over HTTP, so ``Document.add_table(style=...)`` /
+  ``Table.style`` setter consult an in-process map
+  (``docx._table_styles.BUILTIN_TABLE_STYLE_IDS``) covering every
+  Word 2007 and Word 2013+ built-in table style (204 entries) before
+  the value reaches ``<w:tblStyle w:val="..."/>``. Without this
+  mapping Word can't resolve the friendly name in ``styles.xml``
+  and silently falls back to ``Normal Table`` (no borders, no
+  header fill, no banding). Custom user-defined style names pass
+  through unchanged. Whether Word actually renders a Word 2013+
+  style after resolution also depends on SuperDoc's exported
+  ``styles.xml`` containing the matching ``<w:style w:type="table">``
+  definition — at SuperDoc 1.8.1 the exported ``styles.xml`` only
+  carries the Word 2007 set, so Word 2013+ styleIds resolve in the
+  ``<w:tblStyle>`` element but still fall back to ``Normal Table``
+  until SuperDoc upstream ships an expanded ``styles.xml``.
+
+- **`Document.create(name=, base_url=, api_key=, parent_folder_id=, workspace_id=, docx=, agora_base_url=)`**
   classmethod. Stock python-docx returns a blank in-memory document
   for `Document(None)`; we can't fabricate a SuperDocument asset
   client-side, so net-new asset creation is a separate factory that
   hits `POST {base_url}/docs/empty`. The constructor positional-arg
   shape (`Document(asset_id)`) is preserved for parity.
+  - **`docx=path`** mirrors the upstream `Document(docx="template.docx")`
+    constructor kwarg: when provided, the local `.docx` is uploaded to
+    agora's `/api/super-docs/create-from-upload` and used as the seed
+    for the new SuperDocument. The bytes are mirrored to S3 server-side
+    so subsequent template-asset reuse is fast. Without `docx=`, the
+    default Athena template is applied as today.
+  - **`agora_base_url=`** is a transport-detail kwarg only required when
+    the SDK can't derive the agora host from `base_url` (or from
+    `$ATHENA_AGORA_BASE_URL`). The default substitution rule replaces
+    `docx-studio` with `agora` in the docx-studio host; explicit
+    `agora_base_url` is required for local development or unusual
+    deployment topologies.
 
 - **`Document.asset_id: str`** read-only property — the Athena asset
   id this Document is bound to (`asset_<uuid>`). Agent-callable so
@@ -141,6 +175,174 @@ not file-backed. Each is documented in the relevant docstring.
   has zero track-changes API, so this entire surface is an Athena
   extension wired to SuperDoc's `doc.trackChanges.{list,get,decide}`.
 
+### Athena extensions for most-requested upstream features (v0.11.0+)
+
+These surfaces are **additions** to python-docx, not deviations from
+existing behavior — every upstream class, method, property, and
+parameter remains 1:1 with python-docx 1.2.0. The parity ratchet at
+`tests/parity/` is one-directional (upstream → athena) so Athena
+extensions do not produce findings; they're listed here for human
+review and so future contributors can find the rationale.
+
+Each item below corresponds to a long-standing upstream feature gap.
+Issue numbers reference `python-openxml/python-docx`.
+
+- **`Paragraph.add_hyperlink(text, address, *, fragment=None,
+  tooltip=None) -> Hyperlink`** — appends a hyperlinked run.
+  python-docx surfaces `Hyperlink` as read-only; PR #74 has been open
+  since 2014 and is the single most-requested missing feature. Routes
+  through `CreateHyperlink` (SuperDoc `doc.hyperlinks.create`). Returns
+  the same `Hyperlink` class the read path already exposes. Also
+  available as `Run.add_hyperlink` for convenience.
+
+- **`Run.add_field(kind, *, args=None, cached_result=None) -> Field`**
+  + **`Document.fields: Fields`** — generic Word field insertion.
+  Supports `"PAGE"`, `"NUMPAGES"`, `"DATE"`, `"TIME"`, `"AUTHOR"`,
+  `"FILENAME"`, `"NUMWORDS"`, `"REF"`, `"SEQ"`, `"TOC"`, and the
+  generic `"FIELD"` escape hatch. python-docx has no field API
+  whatsoever; issue #498 (page numbers) and #31 (23 comments) demand
+  this. `Fields` is sequence-like; `Fields.refresh_all(scope?)`
+  forces a recompute. Routes through `CreateField` / `FieldsRefresh`
+  / `FieldsList`.
+
+- **`Document.bookmarks: Bookmarks`** + **`Paragraph.add_bookmark
+  (name)`** + **`Document.add_bookmark(name, *, paragraph=None,
+  run=None) -> Bookmark`** — named anchors for cross-references,
+  TOC entries, captions, and internal hyperlinks. python-docx
+  upstream has no bookmark API; issue #425 (35 comments) has been
+  open since 2017. Routes through `CreateBookmark` /
+  `DeleteBookmark` / `BookmarksList` / `BookmarksGet`.
+
+- **`Document.footnotes: Footnotes`** + **`Run.add_footnote(text, *,
+  custom_mark=None) -> Footnote`** — footnote references with a
+  separate body story. python-docx Issue #1 (the first issue ever
+  filed, open since 2014) demands this; it drove the `bayoo-docx`
+  fork. Routes through `CreateFootnote` / `FootnotesList` /
+  `FootnotesGet` / `FootnotesPatch` / `FootnotesDelete`. The
+  parallel **`Document.endnotes: Endnotes`** + **`Run.add_endnote
+  (text, *, custom_mark=None)`** mirrors the same machinery for
+  end-of-section notes.
+
+- **`Document.add_toc(*, levels=(1, 3), style_id=None,
+  include_hyperlinks=True, title=None, tab_leader="dot", at=None)
+  -> TableOfContents`** — inserts a TOC field at the cursor.
+  python-docx issue #36 (closed-without-action), #1207, #1403 demand
+  this. The returned `TableOfContents` proxy exposes `refresh()` to
+  recompute the cached result. Routes through `CreateTOC` /
+  `RefreshTOC`.
+
+- **`Paragraph.add_caption(text, *, label="Figure", bookmark=None,
+  style=None) -> Paragraph`** — adds a caption paragraph with a SEQ
+  field for auto-numbering. python-docx issue #676 (11 👍). Routes
+  through `CreateCaption`.
+
+- **`Run.add_cross_reference(target, *, reference_kind="text",
+  hyperlink=True) -> Field`** — REF field pointing at a bookmark or
+  SEQ. python-docx issue #97 (33 comments). Reference kinds:
+  `"text"`, `"number"`, `"page"`, `"label-number"`, `"above-below"`,
+  `"paragraph"`. Routes through `CreateCrossReference`.
+
+- **`_Cell.set_borders(*, top=, bottom=, left=, right=,
+  inside_horizontal=, inside_vertical=)`** + **`_Cell.borders`**
+  property + **`Table.set_borders(...)`** — per-edge border control.
+  python-docx issue #201 (5 👍), #1238 demand a cell-borders API.
+  Routes through `SetCellBorders` / `SetTableBorders`.
+
+- **`_Cell.set_shading(*, fill=, pattern=, color=)`** +
+  **`_Cell.shading`** property — cell fill / shading. python-docx
+  issue #146 (12 comments) demands this. Routes through
+  `SetCellShading`.
+
+- **`_Cell.v_merge` / `_Cell.is_merge_continuation` /
+  `_Cell.is_merge_origin`** — robust merged-cell detection.
+  python-docx surfaces `_Cell.grid_span` (horizontal) but the
+  vertical merge state and master detection are issue #1312, #1434,
+  #1458. Pure derived properties from existing `tables.getCells`
+  data.
+
+- **`Table.add_row(*, copy_format_from=None)`** — when `copy_format_from`
+  is provided (int row index or `_Row`), the new row inherits height,
+  borders, shading, vertical alignment, and run formatting from the
+  source row. python-docx issue #205 (9 👍). The no-arg form is
+  unchanged.
+
+- **`InlineShape.alt_text` / `InlineShape.title` /
+  `InlineShape.decorative`** + mirrors on `Picture` — accessibility
+  metadata. python-docx PR #1530 is in flight but unreleased; the
+  feature has been requested for years. Routes through
+  `SetImageAltText` / `SetImageDecorative` (already wired in
+  SuperDoc).
+
+- **`InlineShape.anchor(*, wrap="square", position_x_pt=,
+  position_y_pt=, relative_from_x=, relative_from_y=,
+  behind_text=)`** — promote an inline image to a floating
+  (anchored) image. python-docx is inline-only; issue #159 has been
+  open since 2017. Wrap modes: `"inline"`, `"square"`, `"tight"`,
+  `"through"`, `"top-bottom"`, `"behind"`, `"in-front"`. Routes
+  through `SetImageAnchor`.
+
+- **`Document.add_watermark(*, text=None, image_path=None, ...)
+  -> str`** — page-watermark on every page. python-docx issue #845
+  (9 👍). Pass either `text` or `image_path`. Routes through
+  `CreateWatermark`. `Document.delete_watermark` is available via
+  the lower-level `DeleteWatermark` command.
+
+- **`Document.charts: Charts`** + **`Document.add_chart(chart_type,
+  data, *, title=None, width_pt=None, height_pt=None, at=None)
+  -> Chart`** — chart insertion + data editing. python-docx issue
+  #179 (12 👍, 19 comments) demands creation, #1141 demands editing.
+  `chart_type` covers all Word 2016+ families. `Chart.data` setter
+  replaces the underlying table; `Chart.chart_type` setter switches
+  family. Routes through `CreateChart` / `SetChartData` /
+  `SetChartType` / `ChartsList` / `ChartsGet`.
+
+- **`Run.add_math(content, *, format="mathml", display=False)
+  -> MathEquation`** — math equations. python-docx issue #320 (23
+  comments). Formats: `"mathml"`, `"omml"` (Word native), `"latex"`
+  (server-converted). Routes through `CreateMath` / `MathPatch`.
+
+- **`Document.content_controls: ContentControls`** +
+  **`Document.add_content_control(control_kind, ...) -> ContentControl`**
+  — structured-document-tag (SDT) wrappers. python-docx issues #155,
+  #224 (15 comments), #1417 demand write support. Kinds:
+  `"rich-text"`, `"plain-text"`, `"picture"`, `"checkbox"`,
+  `"date"`, `"dropdown"`, `"combobox"`, `"repeating-section"`,
+  `"group"`. Routes through `CreateContentControl` /
+  `ContentControlsList` / `ContentControlsGet` /
+  `ContentControlsPatch` / `ContentControlsDelete`.
+
+- **`Section.set_columns(*, count, equal_width=None, widths=None,
+  space_pt=None, separator=None)`** + **`Section.column_count`** +
+  **`Section.column_widths`** — multi-column section layout.
+  python-docx issue #167 (12 comments). Routes through
+  `SetSectionColumns`.
+
+- **`Document.find_replace(pattern, replacement, *, regex=False,
+  match_case=False, whole_word=False, in_=None, max_replacements=None)
+  -> int`** — formatting-preserving find-and-replace primitive.
+  python-docx issues #30 (39 comments), #980 (12 👍) demand the
+  run-isolation primitive this provides. `in_` scopes to
+  `"body"` / `"headers"` / `"footers"` / `"footnotes"` /
+  `"endnotes"` / `"comments"` / `"all"`. Routes through
+  `FindReplace`.
+
+- **`Paragraph.list_id` / `Paragraph.list_level` /
+  `Paragraph.list_format` / `Paragraph.list_number`** — list-item
+  numbering reads. python-docx issue #471 (13 👍) demands access to
+  list metadata. Routes through `NumberingGet`.
+
+- **`Document.to_pdf(*, quality=None, destination=None,
+  include_revisions=False) -> bytes`** — render to PDF via the
+  Daytona-hosted LibreOffice. python-docx issue #113 was closed as
+  wontfix upstream but the request keeps recurring. Routes through
+  `ExportPDF` (SuperDoc handles the actual conversion).
+
+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;
+this section is the canonical reference for what each Athena
+extension wires up.
+
 ### If you need a deviation
 
 If there is a genuine technical reason why a deviation from python-docx is necessary:
@@ -158,10 +360,16 @@ This is a **thin HTTP client** that mimics the sync python-docx API.
 - Every internal call constructs a typed `Command` dataclass
   (`docx.commands`) and ships it through a `CommandBuffer`
   (`docx._buffer`) which POSTs to docx-studio's `/docs/:id/commands`.
-- HTTP transport: `requests.Session` with a Retry (3 attempts, 0.5s
-  backoff, 429/502/503/504). The legacy `transport="direct"` (embedded
-  Superdoc CLI + y-websocket from Python) was removed in 0.5.0; agent
-  pods no longer embed Superdoc.
+- HTTP transport: `requests.Session` with a Retry (3 attempts, exponential
+  backoff `factor=2.0` plus 0.5s jitter when urllib3 ≥2.0 supports it,
+  ~14s total budget, 429/502/503/504). Once retries are exhausted on
+  502/503/504, the SDK raises `DocxStudioTemporarilyUnavailable`
+  (a `SessionError`) carrying `http_status` and an optional
+  `retry_after_seconds` parsed from the server's `Retry-After` header.
+  Agent code can catch this typed error to back off at the agent level
+  vs. treating it as a script bug. The legacy `transport="direct"`
+  (embedded Superdoc CLI + y-websocket from Python) was removed in
+  0.5.0; agent pods no longer embed Superdoc.
 - **Transparent batching (0.7.0+):** Create* commands
   (`CreateParagraph`, `CreateHeading`, `CreateTable`, `CreateImage`)
   ALWAYS pre-mint a client-side UUID (`client_node_id`) and defer

{athena_python_docx-0.10.0 → athena_python_docx-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.10.0
+Version: 0.11.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.0/docx/__init__.py

@@ -0,0 +1,46 @@
+"""athena-python-docx — drop-in replacement for python-docx.
+
+Calls translate into Superdoc SDK operations against a Keryx Y.Doc.
+See CLAUDE.md for the API parity contract.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.11.0"
+
+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
+
+__all__ = [
+    "Document",
+    "Emu",
+    "Inches",
+    "Pt",
+    "Cm",
+    "Mm",
+    "Twips",
+    "Length",
+    "RGBColor",
+    "flush_all",
+    "__version__",
+]
+
+
+# ---------------------------------------------------------------------------
+# Athena-extension modules (no python-docx upstream parity surface). These
+# are documented in python-sdk/CLAUDE.md § "Intentional deviations (additions
+# / different semantics)" so the parity ratchet at tests/parity/ doesn't
+# regress them. We don't auto-import them here because every one adds
+# import-time cost for the common ``Document(asset_id)`` path; import the
+# specific module you need:
+#
+#     from docx.bookmarks import Bookmark
+#     from docx.fields import Field
+#     from docx.footnotes import Footnote, Endnote
+#     from docx.toc import TableOfContents
+#     from docx.charts import Chart
+#     from docx.math import MathEquation
+#     from docx.sdt import ContentControl
+# ---------------------------------------------------------------------------

athena_python_docx-0.11.0/docx/_athena_extension.py

@@ -0,0 +1,384 @@
+"""Marker decorator + audit helpers for Athena extensions beyond
+python-docx 1.x.
+
+This SDK MUST be a 1:1 replica of python-docx (see ``CLAUDE.md`` § *API
+Parity Rule*). Anything that is NOT in upstream python-docx is an
+**Athena extension** and must be:
+
+1. Documented in ``CLAUDE.md`` § *Intentional deviations (additions /
+   different semantics)* — for the human-readable rationale.
+2. Marked at runtime with :func:`athena_extension` — so introspection
+   tooling (parity audits, docs generation, IDE plugins) can identify
+   the addition without grepping prose, and so the
+   :func:`iter_athena_extensions` walker can enumerate every addition
+   in one place.
+
+The decorator stamps the wrapped object with introspectable attributes:
+
+* ``__athena_extension__`` — always ``True``
+* ``__athena_extension_issue__`` — upstream python-docx issue ref, e.g.
+  ``"python-docx#74"``
+* ``__athena_extension_description__`` — one-line summary
+* ``__athena_extension_since__`` — athena-python-docx SDK version that
+  introduced the surface
+
+Apply at every Athena-extension layer:
+
+* **Class** — decorator on the ``class`` statement::
+
+    @athena_extension(issue=1, description="Footnote proxy")
+    class Footnote: ...
+
+* **Method / function** — decorator on the ``def`` statement::
+
+    @athena_extension(issue=74, description="Paragraph.add_hyperlink")
+    def add_hyperlink(self, ...): ...
+
+* **Property** — decorator on the **getter** (before ``@property``)::
+
+    @property
+    @athena_extension(issue=471)
+    def list_id(self): ...
+
+  When the property has a setter, mark the setter's underlying function
+  too (so writes are auditable independently of reads)::
+
+    @list_id.setter
+    @athena_extension(issue=471)
+    def list_id(self, value): ...
+
+* **Module-level constant** — for whole modules that are entirely
+  Athena extensions, set at top of file::
+
+    __athena_extension_module__ = True
+    __athena_extension_issue__ = "python-docx#1"
+    __athena_extension_description__ = "Footnotes / Endnotes"
+
+  The walker picks these up alongside per-member markers.
+
+The decorator is import-time-cheap, has no runtime overhead at call
+sites (it returns the original object after stamping), and never
+modifies docstrings or signatures. The introspectable attributes are
+parity-neutral — the upstream-vs-athena comparator in
+``tests/parity/compare.py`` only looks at signatures + kinds, not at
+function ``__dict__`` keys.
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from typing import Any, Callable, Iterator, TypeVar
+
+
+# Attribute names — kept as module constants so audits and tests can
+# reference them without re-typing the string everywhere.
+ATHENA_EXTENSION_ATTR: str = "__athena_extension__"
+ATHENA_EXTENSION_ISSUE_ATTR: str = "__athena_extension_issue__"
+ATHENA_EXTENSION_DESCRIPTION_ATTR: str = "__athena_extension_description__"
+ATHENA_EXTENSION_SINCE_ATTR: str = "__athena_extension_since__"
+
+ATHENA_EXTENSION_MODULE_ATTR: str = "__athena_extension_module__"
+
+# Default ``since`` value — overridable per-marker. Bumped when a new
+# wave of additions lands; pre-existing extensions (Document.create,
+# Document.revisions, etc.) carry their original since values.
+_DEFAULT_SINCE: str = "0.11.0"
+
+
+T = TypeVar("T")
+
+
+def athena_extension(
+    *,
+    issue: int | str | None = None,
+    description: str = "",
+    since: str = _DEFAULT_SINCE,
+) -> Callable[[T], T]:
+    """Decorator that marks a class / function / method as an Athena
+    extension beyond python-docx 1.x.
+
+    Stamps four introspectable attributes on the wrapped object:
+
+    - ``__athena_extension__`` — always ``True``
+    - ``__athena_extension_issue__`` — ``"python-docx#<n>"`` when
+      ``issue`` is an int; passed through verbatim when a string;
+      ``None`` when omitted
+    - ``__athena_extension_description__`` — ``description``
+    - ``__athena_extension_since__`` — ``since``
+
+    Returns the original object unchanged (apart from the new
+    attributes), so call sites pay zero runtime cost.
+
+    Args:
+        issue: python-docx upstream issue / PR number that this
+            extension addresses. ``int`` (e.g. ``74``) is auto-formatted
+            as ``"python-docx#74"``; ``str`` is used verbatim.
+        description: One-line human summary. Optional but recommended
+            for non-obvious additions.
+        since: The athena-python-docx SDK version that first shipped
+            this surface. Defaults to the current default-since
+            (``0.11.0``).
+
+    Example::
+
+        @athena_extension(issue=74, description="Add hyperlink (closes issue #74)")
+        def add_hyperlink(self, text, address, *, fragment=None, tooltip=None):
+            ...
+
+    For properties, decorate the underlying getter (and setter) BEFORE
+    ``@property`` so the markers stick to ``prop.fget`` /
+    ``prop.fset``::
+
+        @property
+        @athena_extension(issue=471)
+        def list_id(self): ...
+    """
+    issue_value: str | None
+    if issue is None:
+        issue_value = None
+    elif isinstance(issue, int):
+        issue_value = f"python-docx#{issue}"
+    else:
+        issue_value = str(issue)
+
+    def decorator(obj: T) -> T:
+        # ``setattr`` instead of ``obj.__athena_extension__ = …`` so the
+        # decorator works on classes, plain functions, lambdas, and any
+        # object whose namespace accepts attribute assignment. Built-in
+        # ``property`` descriptors don't (which is why callers must
+        # decorate the underlying getter, not the property itself).
+        try:
+            setattr(obj, ATHENA_EXTENSION_ATTR, True)
+            if issue_value is not None:
+                setattr(obj, ATHENA_EXTENSION_ISSUE_ATTR, issue_value)
+            if description:
+                setattr(obj, ATHENA_EXTENSION_DESCRIPTION_ATTR, description)
+            setattr(obj, ATHENA_EXTENSION_SINCE_ATTR, since)
+        except (AttributeError, TypeError):
+            # E.g. someone applied the decorator directly to a
+            # ``property`` object (which rejects setattr). Re-raise with
+            # a hint so the fix is obvious.
+            raise TypeError(
+                f"@athena_extension cannot be applied to "
+                f"{type(obj).__name__} — built-in descriptor rejects "
+                f"setattr. For properties, decorate the underlying "
+                f"getter/setter function BEFORE @property:\n\n"
+                f"    @property\n"
+                f"    @athena_extension(...)\n"
+                f"    def my_prop(self): ...\n",
+            )
+        return obj
+
+    return decorator
+
+
+def is_athena_extension(obj: Any) -> bool:
+    """Return ``True`` if ``obj`` is marked as an Athena extension.
+
+    Handles the property-wrapping case: a ``property`` descriptor
+    proxies to its ``fget`` (and ``fset``) — either marker counts.
+    """
+    if getattr(obj, ATHENA_EXTENSION_ATTR, False):
+        return True
+    if isinstance(obj, property):
+        if obj.fget is not None and getattr(obj.fget, ATHENA_EXTENSION_ATTR, False):
+            return True
+        if obj.fset is not None and getattr(obj.fset, ATHENA_EXTENSION_ATTR, False):
+            return True
+    return False
+
+
+def athena_extension_metadata(obj: Any) -> dict[str, Any] | None:
+    """Return a dict of marker attributes for ``obj``, or ``None`` if
+    it isn't an Athena extension."""
+    target: Any = obj
+    if isinstance(obj, property):
+        if obj.fget is not None and getattr(obj.fget, ATHENA_EXTENSION_ATTR, False):
+            target = obj.fget
+        elif obj.fset is not None and getattr(obj.fset, ATHENA_EXTENSION_ATTR, False):
+            target = obj.fset
+        else:
+            return None
+    if not getattr(target, ATHENA_EXTENSION_ATTR, False):
+        return None
+    return {
+        "issue": getattr(target, ATHENA_EXTENSION_ISSUE_ATTR, None),
+        "description": getattr(target, ATHENA_EXTENSION_DESCRIPTION_ATTR, ""),
+        "since": getattr(target, ATHENA_EXTENSION_SINCE_ATTR, None),
+    }
+
+
+# Module-level helpers should NOT pull these in transitively at SDK
+# import time — keep the walker lazy.
+def iter_athena_extensions(package: str = "docx") -> Iterator[dict[str, Any]]:
+    """Walk every submodule of ``package`` and yield one record per
+    Athena extension found.
+
+    Records have shape::
+
+        {
+            "kind": "module" | "class" | "function" | "method" |
+                    "property" | "command",
+            "location": "docx.bookmarks.Bookmarks.add",
+            "issue": "python-docx#74",
+            "description": "Append a hyperlinked text run",
+            "since": "0.11.0",
+        }
+
+    The walker:
+
+    * Imports every module under ``package`` (it tolerates import
+      errors gracefully — a broken module is skipped, not fatal).
+    * Yields a ``"module"`` record for any submodule with
+      ``__athena_extension_module__ = True`` at module scope.
+    * Yields one record per top-level callable / class with the
+      marker.
+    * For each marked class, walks the class body and yields a
+      ``"method"`` / ``"property"`` record per marked member.
+
+    Used by ``tests/test_athena_extensions_registry.py`` to verify
+    coverage stays in sync with the surfaces documented in CLAUDE.md.
+    """
+    try:
+        root = importlib.import_module(package)
+    except ImportError:
+        return
+
+    # The root package itself may carry the module-level marker.
+    if getattr(root, ATHENA_EXTENSION_MODULE_ATTR, False):
+        yield {
+            "kind": "module",
+            "location": package,
+            "issue": getattr(root, ATHENA_EXTENSION_ISSUE_ATTR, None),
+            "description": getattr(root, ATHENA_EXTENSION_DESCRIPTION_ATTR, ""),
+            "since": getattr(root, ATHENA_EXTENSION_SINCE_ATTR, None),
+        }
+    yield from _iter_module_members(root, package)
+
+    if not hasattr(root, "__path__"):
+        return
+
+    for _finder, sub_name, _ispkg in pkgutil.walk_packages(
+        root.__path__, prefix=f"{package}.",
+    ):
+        try:
+            sub = importlib.import_module(sub_name)
+        except Exception:  # noqa: BLE001 — broken submodule, skip.
+            continue
+        if getattr(sub, ATHENA_EXTENSION_MODULE_ATTR, False):
+            yield {
+                "kind": "module",
+                "location": sub_name,
+                "issue": getattr(sub, ATHENA_EXTENSION_ISSUE_ATTR, None),
+                "description": getattr(sub, ATHENA_EXTENSION_DESCRIPTION_ATTR, ""),
+                "since": getattr(sub, ATHENA_EXTENSION_SINCE_ATTR, None),
+            }
+        yield from _iter_module_members(sub, sub_name)
+
+
+def _iter_module_members(
+    module: Any, module_name: str,
+) -> Iterator[dict[str, Any]]:
+    """Walk ``vars(module)`` and yield extension records for top-level
+    callables / classes. For each class, recurse into its members.
+
+    Underscore-prefixed *classes* (``_Cell``, ``_Row``, ``_Column``,
+    ``_NoteBase``, etc.) ARE walked — python-docx uses leading-
+    underscore class names for collection types that are part of the
+    public API. Underscore-prefixed *functions* / module attrs are
+    treated as private and skipped.
+    """
+    seen_classes: set[int] = set()
+    for attr_name, attr in vars(module).items():
+        is_class = isinstance(attr, type)
+        if attr_name.startswith("_") and not is_class:
+            continue
+        # Top-level marked function / dataclass.
+        if (
+            not is_class
+            and getattr(attr, ATHENA_EXTENSION_ATTR, False)
+        ):
+            kind = "command" if attr_name[0:1].isupper() else "function"
+            meta = athena_extension_metadata(attr) or {}
+            yield {
+                "kind": kind,
+                "location": f"{module_name}.{attr_name}",
+                **meta,
+            }
+        # Class: emit the class record (if marked) then recurse.
+        if is_class:
+            qual = getattr(attr, "__qualname__", attr_name)
+            mod_of_class = getattr(attr, "__module__", "")
+            # Skip re-exports — only emit the canonical definition's
+            # members. (E.g. ``docx.shape.Picture`` is re-exported from
+            # ``docx.shape``; emit once.)
+            if mod_of_class and mod_of_class != module_name:
+                continue
+            if id(attr) in seen_classes:
+                continue
+            seen_classes.add(id(attr))
+            if getattr(attr, ATHENA_EXTENSION_ATTR, False):
+                meta = athena_extension_metadata(attr) or {}
+                yield {
+                    "kind": "class",
+                    "location": f"{module_name}.{qual}",
+                    **meta,
+                }
+            yield from _iter_class_members(attr, module_name, qual)
+
+
+def _iter_class_members(
+    cls: type, module_name: str, class_qualname: str,
+) -> Iterator[dict[str, Any]]:
+    """Yield records for marked methods / properties on ``cls``.
+
+    Handles three wrapped-callable cases the bare
+    ``getattr(member, ATTR, False)`` check would miss:
+
+    * ``property`` — read marker from ``fget`` / ``fset``.
+    * ``classmethod`` — marker lives on ``__func__``.
+    * ``staticmethod`` — marker lives on ``__func__``.
+    """
+    for member_name, member in vars(cls).items():
+        if member_name.startswith("_"):
+            continue
+        # Peek into classmethod / staticmethod descriptors — the
+        # decorator wraps the underlying function, so the marker
+        # attribute lives on ``descriptor.__func__``.
+        probe: Any = member
+        if isinstance(member, (classmethod, staticmethod)):
+            probe = member.__func__
+        meta = athena_extension_metadata(probe)
+        if meta is None and probe is not member:
+            # Fall back to checking the descriptor itself (covers any
+            # marker explicitly applied to the wrapper).
+            meta = athena_extension_metadata(member)
+        if meta is None:
+            continue
+        if isinstance(member, property):
+            kind = "property"
+        elif isinstance(member, classmethod):
+            kind = "classmethod"
+        elif isinstance(member, staticmethod):
+            kind = "staticmethod"
+        else:
+            kind = "method"
+        yield {
+            "kind": kind,
+            "location": f"{module_name}.{class_qualname}.{member_name}",
+            **meta,
+        }
+
+
+__all__ = [
+    "athena_extension",
+    "is_athena_extension",
+    "athena_extension_metadata",
+    "iter_athena_extensions",
+    "ATHENA_EXTENSION_ATTR",
+    "ATHENA_EXTENSION_ISSUE_ATTR",
+    "ATHENA_EXTENSION_DESCRIPTION_ATTR",
+    "ATHENA_EXTENSION_SINCE_ATTR",
+    "ATHENA_EXTENSION_MODULE_ATTR",
+]