athena-python-docx 0.21.0__tar.gz → 0.21.2__tar.gz

{athena_python_docx-0.21.0 → athena_python_docx-0.21.2}/CLAUDE.md

@@ -25,35 +25,35 @@ Before adding or modifying any API surface:
 
 Run `uv run pytest tests/test_python_docx_api_parity.py -v -s` to verify parity.
 
-### Intentionally omitted (Superdoc SDK limitations)
+### Intentionally omitted (current SDK limitations)
 
-These standard python-docx members don't apply to a Superdoc-backed SDK:
+These standard python-docx members don't apply to a DOCX Studio-backed SDK:
 
 - `Paragraph._p`, `Run._r` — XML element access (no local XML)
 - `Document.part`, `Paragraph.part`, `Run.part` — package part access
 - `Document.core_properties.last_modified_by` — we use Keryx attribution instead
-- `Document.settings` — Word app settings (not surfaced by Superdoc)
-- `InlineShape.chart` — charts (Phase 2+)
+- `Document.settings` — Word app settings (not surfaced by DOCX Studio)
+- `InlineShape.chart` — charts are not currently surfaced by the SDK.
 - `Comment.add_paragraph` / `Comment.add_table` /
   `Comment.iter_inner_content` / `Comment.paragraphs` /
-  `Comment.tables` — SuperDoc models a comment as a single text body,
+  `Comment.tables` — DOCX Studio models a comment as a single text body,
   not a `BlockItemContainer`. Use `Comment.text` instead. The
   paragraph/table-bearing surface raises `CommentsNotImplementedError`.
 - **`_Cell.add_table(rows, cols)`** — surface preserved for parity
   (signature matches python-docx, no `width` kwarg) but raises
   :class:`docx.errors.NestedTableNotSupportedError` (subclass of
-  `NotImplementedError`) at runtime since 0.11.2. SuperDoc 1.8.1 has
-  no anchor or content-fragment shape that places a new table inside
-  an existing `tableCell` — `create.table` rejects cell-inner
+  `NotImplementedError`) at runtime since 0.11.2. The current
+  docx-editor command surface has no anchor or content-fragment shape
+  that places a new table inside an existing `tableCell` — `create.table` rejects cell-inner
   paragraph anchors with `INVALID_TARGET`, and the `doc.insert`
   workaround used by `_Cell.add_paragraph` doesn't generalize
   because the apps/api `Insert` schema doesn't yet forward
-  `nestingPolicy: {tables: "allow"}` and the SuperDoc table-content
+  `nestingPolicy: {tables: "allow"}` and the DOCX editor table-content
   fragment shape isn't documented. Tracked at
-  `docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md` § 13.
+  `docx-studio/DOCX_STUDIO_LIMITATIONS.md` § 13.
 - **`docx.oxml.*`** — the entire raw-OOXML module tree (``ns.qn``,
   ``OxmlElement``, ``CT_*`` classes, etc.) is unavailable because the
-  SDK is HTTP-only against a SuperDoc Y.Doc; there is no local lxml
+  SDK is HTTP-only against a DOCX Studio Y.Doc; there is no local lxml
   tree to manipulate. As of 0.8.0, ``docx.oxml`` is a real stub
   package that raises a typed
   :class:`docx.oxml.OxmlNotAvailableError` (subclass of
@@ -64,21 +64,21 @@ These standard python-docx members don't apply to a Superdoc-backed SDK:
   generic ``ModuleNotFoundError: No module named 'docx.oxml'`` and
   agents had to retry to discover the gap.
 
-### Phase-3b upstream-blocked surface
+### Known partially supported surface
 
 These are *shipped at the surface* but partially or fully no-op at
-runtime, pending DOCX Studio backend changes. See
-`docx-studio/PYTHON_DOCX_PARITY_GAPS.md` § *What unblocks the
-remaining work* for the exact wire-op shape needed to unblock each.
+runtime, pending additional docx-editor command support. Behavior should be
+pinned by focused tests and documented in
+`docx-studio/DOCX_STUDIO_LIMITATIONS.md`.
 
 - **24 setters on `BaseStyle` / `CharacterStyle` / `ParagraphStyle`**
   (`name`, `style_id`, `hidden`, `locked`, `priority`, `quick_style`,
   `unhide_when_used`, `base_style`, `next_paragraph_style`) emit
   `PendingStyleMutationWarning` and stash on `_overrides`.
-  SuperDoc 1.7's `doc.styles.apply` is constrained to
+  The current `doc.styles.apply` command surface is constrained to
   `target.scope: "docDefaults"` — no per-style metadata variant.
   Behavior pinned by `tests/test_style_setters_contract.py` (11
-  tests); when SuperDoc lands a metadata op, those tests will need
+  tests); when docx-editor lands a metadata op, those tests will need
   to flip to assert real bus calls.
 - **`Styles.latent_styles`** returns an empty `_LatentStyles` —
   `DocInfoResult.styles` only surfaces `paragraphStyles[]` (a flat
@@ -119,12 +119,12 @@ not file-backed. Each is documented in the relevant docstring.
   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
+  style after resolution also depends on the 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``.
+  definition. If the exported ``styles.xml`` only carries the Word 2007
+  set, Word 2013+ styleIds resolve in the ``<w:tblStyle>`` element but
+  still fall back to ``Normal Table`` until the export path 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
@@ -164,14 +164,14 @@ not file-backed. Each is documented in the relevant docstring.
   When a path or stream IS supplied, the SDK cannot fulfill the
   implied "write bytes to this target" contract, so the call raises
   loudly rather than silently flushing — agents must use Olympus's
-  Export DOCX (which goes through the SuperDoc session that already
+  Export DOCX (which goes through the DOCX Studio session that already
   has the bytes) instead of expecting a local file.
 
 - **`Document.track_revisions: bool`** — when `True`, all subsequent
   mutations are recorded as tracked revisions instead of direct edits.
   python-docx upstream has no top-level toggle (the closest is
   hand-edited `<w:trackChanges/>` on `Document.settings.element`).
-  We expose this as a Document-level property because every SuperDoc
+  We expose this as a Document-level property because every DOCX Studio
   mutation accepts a per-call `changeMode` envelope field. The
   python-docx-parity alias `Document.settings.track_revisions` reads
   and writes the same flag so call sites that walk `doc.settings`
@@ -184,10 +184,10 @@ not file-backed. Each is documented in the relevant docstring.
   because the upstream package has no track-changes API at all.
 
 - **`Document.user_name: str | None` / `Document.user_email: str |
-  None`** — author identity threaded through to SuperDoc on session-
+  None`** — author identity threaded through to DOCX Studio on session-
   open for tracked-change attribution. python-docx's
   `Document.core_properties.last_modified_by` is the closest upstream
-  surface; we use the SuperDoc-native fields directly because SuperDoc
+  surface; we use the DOCX Studio-native fields directly because DOCX Studio
   bakes them into the change records.
 
 - **`Document.revisions: Revisions`** — collection of tracked changes
@@ -195,7 +195,7 @@ not file-backed. Each is documented in the relevant docstring.
   `accept(id)`, `reject(id)`. Per-revision `Revision.accept()` /
   `Revision.reject()` resolve a single change. python-docx upstream
   has zero track-changes API, so this entire surface is an Athena
-  extension wired to SuperDoc's `doc.trackChanges.{list,get,decide}`.
+  extension wired to DOCX Studio's `doc.trackChanges.{list,get,decide}`.
 
 ### Athena extensions for most-requested upstream features (v0.11.0+)
 
@@ -213,7 +213,7 @@ Issue numbers reference `python-openxml/python-docx`.
   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
+  through `CreateHyperlink` (DOCX Studio `doc.hyperlinks.create`). Returns
   the same `Hyperlink` class the read path already exposes. Also
   available as `Run.add_hyperlink` for convenience.
 
@@ -293,7 +293,7 @@ Issue numbers reference `python-openxml/python-docx`.
   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).
+  DOCX Studio).
 
 - **`InlineShape.anchor(*, wrap="square", position_x_pt=,
   position_y_pt=, relative_from_x=, relative_from_y=,
@@ -370,13 +370,13 @@ Issue numbers reference `python-openxml/python-docx`.
   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).
+  `ExportPDF` (DOCX Studio handles the actual conversion).
 
 - **`Document.clear()`** (0.14.0+) — empty the document body so subsequent
   writes start from a clean slate. python-docx has no equivalent (it
   operates on local files where the caller can simply construct a new
   ``Document``). Iterates every top-level paragraph and table cell and
-  empties their text content. Block structure is preserved (SuperDoc has
+  empties their text content. Block structure is preserved (DOCX Studio has
   no wire op to delete blocks today), so post-clear the doc holds N
   empty paragraphs rather than collapsing to a single one — for a truly
   empty body, call ``Document.create()`` to mint a fresh asset instead.
@@ -395,6 +395,27 @@ Issue numbers reference `python-openxml/python-docx`.
   the citation-blue highlight to the destination paragraph/range. It is
   not a live link and does not overwrite destination text.
 
+  Use citations as evidence, not as generic source mentions.
+  ``Paragraph.add_citation(...)`` highlights the whole paragraph in Athena, so
+  make the destination unit match the evidence: a metric cell/table row for a
+  number, one short sentence for a claim, or one short paragraph only when the
+  same source supports the full paragraph. If only a few words or numbers in a
+  long paragraph are supported, split that claim into its own sentence,
+  paragraph, or table row before citing it. Do not add duplicate citations to
+  every rendered line when one citation on the semantic claim/table row is
+  sufficient.
+  Use a mention/reference instead when you only need to point at a related
+  source without claiming evidentiary support. For PDFs, prefer a tight page
+  text anchor or a page anchor with an ``excerpt`` containing the exact
+  phrase/number being supported, not just a broad section title.
+
+  Prefer a canonical citation string when the source/anchor is already known
+  as a Spaces URL, or when the source type is not modeled by the DOCX SDK
+  (video/audio time ranges, browser sessions, external URLs, etc.). Typed
+  ``AssetReference`` + anchor objects are still useful convenience helpers for
+  common Athena assets such as spreadsheets and PDFs, but they are not the only
+  valid source form.
+
   Common agent pattern after writing a supported claim:
 
   ```python
@@ -403,6 +424,16 @@ Issue numbers reference `python-openxml/python-docx`.
 
   doc = Document("asset_word")
   p = doc.add_paragraph("The combined assessment identified 20,049 total vulnerabilities.")
+
+  # Preferred generic path: pass a canonical Spaces URL or https URL.
+  citation_id = p.add_citation(
+      "/dashboard/spaces/?asset_ids=asset_spreadsheet&type=spreadsheet"
+      "&anchor=sheet_range&sheet_id=0&range=B2%3AB8",
+      excerpt="20,049 total vulnerabilities",
+      display_value="Vulnerability total",
+  )
+
+  # Typed helper path: still fine when the SDK has the source/anchor dataclasses.
   citation_id = p.add_citation(
       AssetReference(id="asset_spreadsheet"),
       anchor=SheetRangeAnchor(sheet_id=0, range="B2:B8"),
@@ -444,7 +475,7 @@ Issue numbers reference `python-openxml/python-docx`.
 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
+batch. The current docx-editor applier'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
@@ -458,7 +489,7 @@ 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.
+``docx-studio/DOCX_STUDIO_LIMITATIONS.md`` § 13.
 
 **0.11.5 follow-up: post-export OOXML rewrite.** When the parent
 table was created via ``Document.add_table`` in this session
@@ -468,7 +499,7 @@ OOXML-shaped props (``alignment``, ``style``, ``left_twips``,
 :class:`docx._postproc.PostExportOps` collector). ``Document.export_docx``
 applies them via an OOXML rewrite of ``word/document.xml`` before
 returning bytes — so the **exported ``.docx`` carries the formatting
-the agent asked for** even though SuperDoc never accepted the wire
+the agent asked for** even though DOCX Studio never accepted the wire
 op. Live-session state is unchanged (Olympus collaborators don't
 see the formatting until export). Template-seeded tables where
 ``_doc_index`` is ``None`` still warn-and-skip (no stable OOXML
@@ -487,7 +518,7 @@ helper pattern —
 
 — used to silently drop both the ``Hello world`` text AND the bold
 format because ``Paragraph.add_run`` on a cell-inner paragraph
-returned a stub Run with collapsed range, and SuperDoc 1.8.1
+returned a stub Run with collapsed range, and the docx-editor applier
 rejected the wire-level ``doc.insert`` against the cell-inner
 paragraph's blockId with ``Block <id> not found``. The 0.13.0 fix
 adds a ``_cell`` back-reference to every cell-inner Paragraph proxy
@@ -497,7 +528,7 @@ called on a cell-inner paragraph with non-empty text AND the
 back-ref is set, the SDK ships ``doc.insert(target=cell,
 placement="insideEnd", content=paragraph-fragment-with-text)``
 instead — the SAME wire path ``_Cell.add_paragraph(text)`` already
-uses. SuperDoc collapses the new paragraph into the cell's single
+uses. DOCX Studio collapses the new paragraph into the cell's single
 template paragraph as an inline run; the exported DOCX expands each
 non-empty inline run into its own ``<w:p>``. The returned Run is
 real (non-collapsed range) and carries the new exported-paragraph
@@ -524,10 +555,10 @@ of dropping it silently at the wire layer. The post-export rewrite
 walks every ``<w:r>`` in the targeted cell paragraph and injects
 ``<w:rPr>`` carrying the props — so ``cell.text = "Total"; cell.
 paragraphs[0].runs[0].bold = True`` produces a bold ``Total`` in
-the exported ``.docx`` even though SuperDoc never committed the
+the exported ``.docx`` even though DOCX Studio never committed the
 format wire op. Apply-to-all-runs semantics: the rewrite targets
 every ``<w:r>`` in the cell paragraph, because run-level addressing
-inside a cell isn't recoverable after SuperDoc collapses cell-
+inside a cell isn't recoverable after DOCX Studio collapses cell-
 inner inserts. Multi-run cell paragraphs with partial-run
 formatting are a documented limitation — agents should use one
 run per format intent.
@@ -550,7 +581,7 @@ rels entry so the rels file doesn't grow unboundedly. Behavior
 pinned by ``tests/test_postproc_cell_run_format_rewrite.py``.
 
 Live Olympus rendering still won't show cell-inner formatting or
-hyperlinks until SuperDoc lands the corresponding wire ops —
+hyperlinks until DOCX Studio lands the corresponding wire ops —
 ``Document.export_docx`` is the source of truth for the
 deliverable until then.
 
@@ -565,7 +596,7 @@ deliverable until then.
   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
+  position as ``_doc_index``. When DOCX Studio 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
@@ -584,18 +615,18 @@ deliverable until then.
   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``;
+  DOCX Studio's ``doc.fields.insert`` rejects the cursor form with
+  ``DocxStudioCommandError: fields insert:at.segments is required``;
   pre-0.11.4 the call took down the whole batch on every flush.
 
 ### 0.11.5 — `REF` field round-trip preservation (post-export rewrite)
 
-SuperDoc 1.23.1 / SDK 1.8.1 strips ``REF`` field codes
+The DOCX editor import/export path can strip ``REF`` field codes
 (``<w:fldChar>`` / ``<w:instrText REF …>`` / result-runs / end
 ``<w:fldChar>``) on import. On the Paul Weiss Purchase Agreement
 this loses all 301 cross-references — readers see chains of empty
 commas instead of "Section 3.02(b)" cross-refs. Tracked at
-``docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md`` § 18.
+``docx-studio/DOCX_STUDIO_LIMITATIONS.md`` § 18.
 
 As of 0.11.5, ``Document.create(docx=template.docx)`` scans the
 local template bytes with a stdlib zipfile + xml.etree parser and
@@ -614,7 +645,7 @@ same Python process that called ``Document.create(docx=...)`` also
 calls ``export_docx``. Cross-process flows (agent A creates, agent
 B exports) need agora-side persistence (separate follow-up). (2)
 Paragraph-wholesale replacement preserves the source paragraph but
-overwrites any SuperDoc in-paragraph edits — for round-trip
+overwrites any DOCX Studio in-paragraph edits — for round-trip
 preservation (the primary use case) this is exactly right. (3) Only
 top-level body paragraphs are scanned; cell-inner REFs aren't
 captured (rare for legal cross-references).
@@ -643,9 +674,9 @@ routing, `add_picture` native size + aspect ratio, `WD_BUILTIN_STYLE`
 and `CoreProperties` validation. These are not deviations — they close
 gaps. The items below are the **residual intentional deviations** that
 remain because matching upstream would break the asset-backed/HTTP
-architecture or a SuperDoc constraint:
+architecture or a DOCX Studio constraint:
 
-- **`WD_*` enum `.value` is the SuperDoc wire string, not the MS Word
+- **`WD_*` enum `.value` is the DOCX Studio wire string, not the MS Word
   integer constant.** `WD_ALIGN_PARAGRAPH.CENTER.value == "center"`
   (upstream: `1`); `int(member)` / `member == 1` / `WD_*(1)` therefore
   differ. The string value is load-bearing — every command serializes
@@ -661,7 +692,7 @@ architecture or a SuperDoc constraint:
   stripped before the (otherwise byte-identical) upstream slice parse.
   A strict superset — every value upstream accepts parses identically.
 
-- **`_Cell.vertical_alignment` setter accepts the four SuperDoc wire
+- **`_Cell.vertical_alignment` setter accepts the four DOCX Studio wire
   tokens** (`"top"`/`"center"`/`"bottom"`/`"both"`) in addition to
   `WD_ALIGN_VERTICAL` members. Upstream rejects all plain strings; this
   is an ergonomic superset (typos like `"middle"` still raise
@@ -685,19 +716,19 @@ architecture or a SuperDoc constraint:
 
 - **`Document.add_table(rows, cols)` requires `rows >= 1` and
   `cols >= 1`.** Upstream allows a 0-row/0-col grid you later populate,
-  but SuperDoc's ProseMirror table node can't represent one; the SDK
+  but DOCX Studio's ProseMirror table node can't represent one; the SDK
   raises eagerly rather than failing opaquely on the wire.
 
-- **`Comment.comment_id` returns `str`, not `int`.** SuperDoc uses
+- **`Comment.comment_id` returns `str`, not `int`.** DOCX Studio uses
   non-numeric entity ids (`"c-42"`), so the upstream `int` contract
-  can't be honored. Tracked in `SUPERDOC_UPSTREAM_REQUESTS.md`.
+  can't be honored. Tracked in `DOCX_STUDIO_LIMITATIONS.md`.
 
 - **`Section` dimension setters and `ParagraphFormat.line_spacing_rule
   = None` warn-and-preserve on a clear** rather than raising (upstream
-  accepts `None` to clear, but SuperDoc's merging mutation ops have no
+  accepts `None` to clear, but DOCX Studio's merging mutation ops have no
   single-attribute clear). They emit a `Pending…ClearWarning` and leave
   the value intact instead of destructively clearing the whole block.
-  Tracked in `SUPERDOC_UPSTREAM_REQUESTS.md`.
+  Tracked in `DOCX_STUDIO_LIMITATIONS.md`.
 
 ### If you need a deviation
 
@@ -723,13 +754,13 @@ This is a **thin HTTP client** that mimics the sync python-docx API.
   (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.
+  vs. treating it as a script bug. The former `transport="direct"`
+  (embedded DOCX Studio CLI + y-websocket from Python) was removed in
+  0.5.0; agent pods no longer embed DOCX Studio.
 - **Transparent batching (0.7.0+):** Create* commands
   (`CreateParagraph`, `CreateHeading`, `CreateTable`, `CreateImage`)
   ALWAYS pre-mint a client-side UUID (`client_node_id`) and defer
-  through the buffer. The applier resolves UUIDs to real SuperDoc
+  through the buffer. The applier resolves UUIDs to real DOCX Studio
   ids via per-batch `clientIdMap` on flush, and the buffer rewrites
   each proxy's `_node_id` in-place. Net result: 30 `add_paragraph`
   calls = 1 HTTP request, with no explicit `batch()` context manager

{athena_python_docx-0.21.0 → athena_python_docx-0.21.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.21.0
+Version: 0.21.2
 Summary: Drop-in replacement for python-docx that connects to Athena's DOCX Studio collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>
@@ -21,9 +21,6 @@ Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: python-docx>=1.1; extra == 'dev'
 Requires-Dist: responses>=0.24; extra == 'dev'
 Requires-Dist: ruff>=0.3; extra == 'dev'
-Provides-Extra: fidelity
-Requires-Dist: httpx>=0.27; extra == 'fidelity'
-Requires-Dist: superdoc-sdk>=1.8.0; extra == 'fidelity'
 Description-Content-Type: text/markdown
 
 # athena-python-docx

{athena_python_docx-0.21.0 → athena_python_docx-0.21.2}/docx/__init__.py

@@ -1,12 +1,12 @@
 """athena-python-docx — drop-in replacement for python-docx.
 
-Calls translate into Superdoc SDK operations against a Keryx Y.Doc.
+Calls translate into DOCX Studio SDK operations against a Keryx Y.Doc.
 See CLAUDE.md for the API parity contract.
 """
 
 from __future__ import annotations
 
-__version__ = "0.21.0"
+__version__ = "0.21.2"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.21.0 → athena_python_docx-0.21.2}/docx/_buffer.py

@@ -8,7 +8,7 @@ ships as one HTTP request instead of N.
 Create* commands are deferred because the SDK pre-mints a client-side
 UUID for every new node (see ``Document._mint_client_node_id``). The
 proxy returned to the caller is stamped with that UUID; the applier
-resolves UUIDs to real SuperDoc ids via ``clientIdMap`` and echoes the
+resolves UUIDs to real DOCX Studio ids via ``clientIdMap`` and echoes the
 mapping back, at which point the buffer rewrites each proxy's
 ``_node_id``. This makes batching invisible at the call site — user
 code looks like python-docx, runs at python-docx-batched speed.
@@ -49,7 +49,7 @@ def _apply_proxy_id_rewrites(
     proxy_id_refs: "dict[str, list[tuple[object, str]]]",
 ) -> None:
     """Walk ``results`` and rewrite registered proxy ids from client UUIDs
-    to the real SuperDoc ids the applier echoed back.
+    to the real DOCX Studio ids the applier echoed back.
 
     Shared by the success path in :meth:`CommandBuffer.flush` /
     :meth:`_eager_flush_with` AND by the **partial-failure recovery
@@ -287,7 +287,7 @@ class CommandBuffer:
 
     Create* commands defer because the SDK pre-mints a client-side UUID
     (``client_node_id`` / ``client_entity_id``); the applier translates
-    the UUID to a real SuperDoc id in a per-batch ``clientIdMap`` and
+    the UUID to a real DOCX Studio id in a per-batch ``clientIdMap`` and
     echoes the mapping back so the SDK can rewrite each proxy's
     ``_node_id`` on flush.
     """
@@ -385,7 +385,7 @@ class CommandBuffer:
     def set_user(self, name: str | None, email: str | None = None) -> None:
         """Set the batch-level user identity.
 
-        Sent on every commands request envelope. SuperDoc honors the
+        Sent on every commands request envelope. DOCX Studio honors the
         identity at session-open time only — subsequent batches against
         a pooled session ignore the value, but the payload is still
         included so a fresh session picks it up.
@@ -415,7 +415,7 @@ class CommandBuffer:
         ``client_entity_id`` — appends to the queue, resets the idle
         timer, and returns ``None``. Caller MUST NOT rely on the return
         value of a buffered mutation. For deferred Creates, the
-        applier resolves the client UUID to a real SuperDoc id via
+        applier resolves the client UUID to a real DOCX Studio id via
         ``clientIdMap`` on flush and the buffer rewrites each registered
         proxy's ``_node_id`` in-place.
         """

athena_python_docx-0.21.2/docx/_citations.py

@@ -0,0 +1,154 @@
+"""Helpers for SDK-native Athena citations."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+from urllib.parse import parse_qs, urlparse
+
+from docx._references import AssetReference
+from docx.commands import AddCitation
+
+
+_ATHENA_SPACES_HOST_SUFFIXES: tuple[str, ...] = (
+    "athenaintel.com",
+    "athenaintelligence.ai",
+)
+
+
+def new_citation_id() -> str:
+    return f"citation_{uuid.uuid4().hex[:12]}"
+
+
+def _is_athena_spaces_host(hostname: str | None) -> bool:
+    host = (hostname or "").lower()
+    return any(
+        host == suffix or host.endswith(f".{suffix}")
+        for suffix in _ATHENA_SPACES_HOST_SUFFIXES
+    )
+
+
+def source_ref_to_dict(source: AssetReference) -> dict[str, Any]:
+    if not isinstance(source, AssetReference):
+        raise TypeError(f"source must be an AssetReference; got {type(source).__name__}")
+    return source.to_dict()
+
+
+def normalize_citation_string(citation_string: str) -> str:
+    value = citation_string.strip()
+    if not value:
+        raise ValueError("citation_string must not be empty")
+
+    parsed = urlparse(value)
+    if parsed.scheme in ("http", "https") and parsed.netloc:
+        if parsed.path.rstrip("/") == "/dashboard/spaces":
+            if not _is_athena_spaces_host(parsed.hostname):
+                raise ValueError(
+                    "absolute Athena Spaces citation URLs must use an Athena host"
+                )
+            asset_ids = parse_qs(parsed.query).get("asset_ids")
+            if not asset_ids or not asset_ids[0]:
+                raise ValueError("Athena Spaces citation URLs must include asset_ids")
+        return value
+
+    if not parsed.scheme and value.startswith("/"):
+        relative = urlparse(value)
+        if relative.netloc:
+            raise ValueError(
+                "protocol-relative Athena Spaces citation URLs are not allowed; "
+                "use an absolute Athena host"
+            )
+        if relative.path.rstrip("/") == "/dashboard/spaces":
+            asset_ids = parse_qs(relative.query).get("asset_ids")
+            if asset_ids and asset_ids[0]:
+                return value
+            raise ValueError("Athena Spaces citation URLs must include asset_ids")
+
+    raise ValueError(
+        "citation_string must be a serialized citation URL, such as "
+        "'/dashboard/spaces/?asset_ids=...' or an 'https://...' URL"
+    )
+
+
+def anchor_to_dict(anchor: object | None) -> dict[str, Any] | None:
+    if anchor is None:
+        return None
+    if not hasattr(anchor, "to_dict"):
+        raise TypeError(
+            "anchor must be an Anchor dataclass (SheetRangeAnchor, "
+            f"PmNodeAnchor, etc.) — got {type(anchor).__name__}"
+        )
+    value = anchor.to_dict()
+    if not isinstance(value, dict) or not value.get("type"):
+        raise TypeError("anchor.to_dict() must return a dict with a 'type' field")
+    return value
+
+
+def destination_anchor_to_dict(destination_anchor: object) -> dict[str, Any]:
+    if hasattr(destination_anchor, "to_dict"):
+        destination_anchor = destination_anchor.to_dict()
+    if not isinstance(destination_anchor, dict):
+        raise TypeError(
+            "destination_anchor must be a PmNodeAnchor, PmNodeRangeAnchor, or wire dict"
+        )
+    anchor_type = destination_anchor.get("type")
+    if anchor_type == "pm_node" and destination_anchor.get("nodeId"):
+        return dict(destination_anchor)
+    if (
+        anchor_type == "pm_node_range"
+        and destination_anchor.get("startNodeId")
+        and destination_anchor.get("endNodeId")
+    ):
+        return dict(destination_anchor)
+    raise ValueError(
+        "destination_anchor must be {'type':'pm_node','nodeId':...} or "
+        "{'type':'pm_node_range','startNodeId':...,'endNodeId':...}"
+    )
+
+
+def build_add_citation_command(
+    *,
+    destination_anchor: object,
+    source: AssetReference | str | None,
+    anchor: object | None,
+    citation_string: str | None,
+    excerpt: str | None,
+    display_value: str | None,
+) -> tuple[str, AddCitation]:
+    source_ref: dict[str, Any] | None
+    if isinstance(source, str):
+        if (
+            citation_string is not None
+            and normalize_citation_string(citation_string)
+            != normalize_citation_string(source)
+        ):
+            raise ValueError("Pass citation_string either positionally or by keyword, not both")
+        citation_string = source
+        source_ref = None
+    elif source is None:
+        source_ref = None
+    else:
+        if citation_string is not None:
+            raise ValueError("Pass either an AssetReference source or citation_string, not both")
+        source_ref = source_ref_to_dict(source)
+
+    normalized_citation_string = (
+        normalize_citation_string(citation_string)
+        if citation_string is not None
+        else None
+    )
+    if source_ref is None and normalized_citation_string is None:
+        raise ValueError("source or citation_string is required")
+    if source_ref is None and anchor is not None:
+        raise ValueError("anchor requires an AssetReference source; encode the anchor in citation_string instead")
+
+    citation_id = new_citation_id()
+    return citation_id, AddCitation(
+        destination_anchor=destination_anchor_to_dict(destination_anchor),
+        source_ref=source_ref,
+        source_anchor=anchor_to_dict(anchor),
+        citation_string=normalized_citation_string,
+        citation_id=citation_id,
+        excerpt=excerpt,
+        display_value=display_value,
+    )