athena-python-docx 0.18.3__tar.gz → 0.19.0__tar.gz

{athena_python_docx-0.18.3 → athena_python_docx-0.19.0}/CLAUDE.md

@@ -222,6 +222,22 @@ Issue numbers reference `python-openxml/python-docx`.
   the same `Hyperlink` class the read path already exposes. Also
   available as `Run.add_hyperlink` for convenience.
 
+- **`Paragraph.add_citation(*, source, text=None, anchor=None,
+  display_value=None, label=None) -> str`** + **`Document.remove_citation
+  (*, citation_id, soft=True)`** — source-citation markers (Athena
+  studio-linking; no python-docx analog, `issue=None`). Attaches a
+  Word-style superscript citation marker pointing at an Athena asset
+  (`source`, an `AssetReference`), optionally narrowed by `anchor` (a
+  sheet range, PDF page, …). Renders in Olympus as a clickable superscript
+  with a hover preview + Citations-panel entry — the same unified
+  citation system as sheets / PPTX / native docs; clicking opens the
+  source in a new tab. Routes through `CreateCitation` / `RemoveCitation`;
+  the studio server derives the openable `citation_string` from
+  `source_ref` + `source_anchor` via `@athenaintel/references` (single
+  canonical serializer). `docx/_references.py` mirrors the pptx
+  `AssetReference` + anchor re-exports off the shared `athena-references`
+  package.
+
 - **`Run.add_field(kind, *, args=None, cached_result=None) -> Field`**
   + **`Document.fields: Fields`** — generic Word field insertion.
   Supports `"PAGE"`, `"NUMPAGES"`, `"DATE"`, `"TIME"`, `"AUTHOR"`,

{athena_python_docx-0.18.3 → athena_python_docx-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.18.3
+Version: 0.19.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>
@@ -11,6 +11,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.11
+Requires-Dist: athena-references>=0.1.0
 Requires-Dist: requests>=2.28
 Requires-Dist: urllib3>=1.26.6
 Provides-Extra: dev

{athena_python_docx-0.18.3 → athena_python_docx-0.19.0}/docx/__init__.py

@@ -6,7 +6,7 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.18.3"
+__version__ = "0.19.0"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.18.3 → athena_python_docx-0.19.0}/docx/_buffer.py

@@ -41,7 +41,7 @@ from docx._execution import (
 )
 from docx._timeouts import timeout_for_commands
 from docx.commands import Command, is_response_bearing, must_flush_immediately
-from docx.errors import DocxError, FlushAllError
+from docx.errors import DocxError, DocxUnsupportedCommandError, FlushAllError
 
 
 def _apply_proxy_id_rewrites(
@@ -467,8 +467,17 @@ class CommandBuffer:
     def flush(self) -> list[Any]:
         """Flush pending commands as one HTTP batch.
 
-        Returns the list of per-command result dicts. Empty list if nothing
-        was pending. Cancels any active idle timer.
+        Returns the per-command result list, positionally aligned with the
+        flushed commands (skipped commands occupy their slot as ``None``).
+        Empty list if nothing was pending. Cancels any active idle timer.
+
+        This is the FIRE-AND-FORGET path: callers here don't await an
+        individual command's result, so an unsupported command that the
+        server skipped is simply warned (inside ``execute_batch``) and its
+        slot left ``None`` — the supported commands still applied. (A caller
+        that DOES need a single command's result goes through
+        :meth:`_eager_flush_with`, which raises on a skipped trailing command
+        rather than returning the wrong slot.)
 
         After the batch returns, walks per-cmd results for
         ``real_node_id`` / ``real_entity_id`` echoes and updates any
@@ -490,7 +499,7 @@ class CommandBuffer:
         if not pending:
             return []
         try:
-            results = self._client.execute_batch(
+            results, _skipped_by_index = self._client.execute_batch(
                 self._asset_id,
                 pending,
                 change_mode=change_mode,
@@ -554,8 +563,11 @@ class CommandBuffer:
             proxy_id_refs = self._proxy_id_refs
             self._proxy_id_refs = {}
         all_cmds: list[Command] = [*pending, cmd]
+        trailing_index = len(all_cmds) - 1
         try:
-            results: list[Any] = self._client.execute_batch(
+            results: list[Any]
+            skipped_by_index: dict[int, dict[str, Any]]
+            results, skipped_by_index = self._client.execute_batch(
                 self._asset_id,
                 all_cmds,
                 change_mode=change_mode,
@@ -576,10 +588,32 @@ class CommandBuffer:
             _ptc_emit_end_batch(all_cmds, is_error=True)
             raise
         _ptc_emit_end_batch(all_cmds, is_error=False)
+        # Proxy-id rewrites still run for the buffered prefix that DID apply —
+        # the trailing skip (if any) doesn't strand the supported Creates that
+        # flushed alongside it.
         _apply_proxy_id_rewrites(results, proxy_id_refs)
+        # This is the AWAITED-result path: the caller is about to read the
+        # trailing command's result. If the server skipped that command
+        # (capability gap), there is no result to return — returning some
+        # earlier applied mutation's slot would be silent WRONG DATA. Fail
+        # loud instead. (Fire-and-forget mutations never reach here; they go
+        # through :meth:`flush`, which keeps the skip+warn behavior.)
+        if trailing_index in skipped_by_index:
+            skip = skipped_by_index[trailing_index]
+            reason = skip.get("reason") if isinstance(skip, dict) else None
+            raise DocxUnsupportedCommandError(
+                f"docx-studio skipped command {type(cmd).__name__!r} but the "
+                f"SDK was awaiting its result" + (f": {reason}" if reason else ".")
+            )
         if not results:
             return {}
-        return results[-1]
+        # Trailing command applied: its slot holds the result dict (or ``{}``
+        # for a non-dict result). A ``None`` here would only arise if the
+        # server omitted the trailing command's index from ``applied[]``
+        # without listing it in ``skipped[]`` — fall back to ``{}`` to match
+        # the legacy "no result" behavior rather than handing back ``None``.
+        trailing = results[-1]
+        return trailing if trailing is not None else {}
 
     def _reset_timer_locked(self) -> None:
         # Caller must hold self._lock.

{athena_python_docx-0.18.3 → athena_python_docx-0.19.0}/docx/_http_doc.py

@@ -31,6 +31,7 @@ from __future__ import annotations
 
 import json
 import os
+import warnings
 from typing import Any
 
 import requests
@@ -172,6 +173,7 @@ from docx.errors import (
     BlockNotFoundError,
     DocxError,
     DocxStudioTemporarilyUnavailable,
+    DocxUnsupportedCommandWarning,
     NotFoundError,
     SessionError,
 )
@@ -662,6 +664,29 @@ def _http_post_json(
     )
 
 
+def _warn_skipped_commands(skipped: list[Any]) -> None:
+    """Emit one :class:`DocxUnsupportedCommandWarning` per server-reported
+    skipped command.
+
+    Each entry is the wire-shape ``{index, type, reason}`` dict the applier
+    records when a command raises ``UnsupportedDocxEditorCommandError``. The
+    batch still succeeded for every supported command; warning (rather than
+    raising) is the graceful-degradation contract so a script that ends with
+    an unsupported op doesn't abort into an empty document.
+
+    Tolerant of malformed entries: anything that isn't a dict is summarized
+    generically rather than crashing the (otherwise successful) batch.
+    """
+    for entry in skipped:
+        if isinstance(entry, dict):
+            cmd_type = entry.get("type", "<unknown>")
+            reason = entry.get("reason") or "not supported by the docx-editor engine yet"
+            message = f"Skipped unsupported command {cmd_type!r}: {reason}"
+        else:
+            message = f"Skipped unsupported command: {entry!r}"
+        warnings.warn(message, DocxUnsupportedCommandWarning, stacklevel=2)
+
+
 # ---------------------------------------------------------------------------
 # HttpClient — the bare HTTP transport. Stateless wrt batching.
 # ---------------------------------------------------------------------------
@@ -706,8 +731,22 @@ class HttpClient:
         *,
         change_mode: str | None = None,
         user: dict[str, str] | None = None,
-    ) -> list[Any]:
-        """POST a batch of typed commands, return per-command result dicts.
+    ) -> tuple[list[Any], dict[int, dict[str, Any]]]:
+        """POST a batch of typed commands.
+
+        Returns ``(results, skipped_by_index)``:
+
+        - ``results`` is **positionally aligned** with ``commands``: one slot
+          per input command, in order. An applied command's slot holds its
+          ``result`` dict (or ``{}`` for a non-dict result); a SKIPPED
+          command's slot holds ``None``. Positional alignment is what lets a
+          caller awaiting a single command's result (``_eager_flush_with``)
+          map ``results[-1]`` back to *its* command and detect that the
+          command was skipped (``None``) rather than silently returning some
+          earlier applied mutation's result.
+        - ``skipped_by_index`` maps the input index of each skipped command to
+          its ``{index, type, reason}`` entry, so callers awaiting a result a
+          skipped command can't provide can raise a precise error.
 
         Envelope fields:
             change_mode: ``"direct"`` | ``"tracked"`` | ``None``. When
@@ -720,14 +759,22 @@ class HttpClient:
                 opens the per-asset session for the first time; ignored
                 on subsequent batches against the same pooled session.
 
-        On success, length matches len(commands). On 207 partial-failure,
-        the server returns 207 with `applied` (the successful prefix) plus
-        an `error` for the failing command — :func:`_http_post_json`
-        translates that to a :class:`DocxError`. We don't pad partial
-        results because the doc state is undefined.
+        On success, ``len(applied) + len(skipped) == len(commands)``. The
+        server's ``skipped[]`` array carries commands the docx-editor engine
+        doesn't implement yet; each is surfaced as a
+        :class:`DocxUnsupportedCommandWarning` (graceful degradation — one
+        unsupported FIRE-AND-FORGET mutation no longer aborts the whole batch
+        into an empty document). Fire-and-forget mutations don't read their
+        result, so a warning + skip is correct for them. A skipped command
+        that a caller IS awaiting (a query / response-bearing op routed
+        through ``_eager_flush_with``) is detected positionally and raised by
+        that caller. On 207 partial-failure, the server returns 207 with
+        `applied` (the successful prefix) plus an `error` for the failing
+        command — :func:`_http_post_json` translates that to a
+        :class:`DocxError`.
         """
         if not commands:
-            return []
+            return [], {}
 
         url: str = f"{self._base_url}/docs/{asset_id}/commands"
         body: dict[str, Any] = {
@@ -747,6 +794,12 @@ class HttpClient:
             timeout=timeout_for_commands(commands=commands),
         )
         applied = resp.get("applied")
+        # Commands the engine doesn't implement yet are reported in
+        # ``skipped[]`` (non-fatal). Warn per skip and count them toward the
+        # batch total — they're a success, not a failure.
+        skipped_raw = resp.get("skipped")
+        skipped = skipped_raw if isinstance(skipped_raw, list) else []
+        _warn_skipped_commands(skipped)
         # An empty applied list paired with an `error` field is the
         # 'all-commands-failed' shape — surface it rather than returning
         # an empty result list to a caller that's about to index [-1].
@@ -758,19 +811,37 @@ class HttpClient:
                 f"docx-studio response missing applied[]: {resp!r}",
             )
 
-        if len(applied) != len(commands):
+        # Applied + skipped together must account for every command. A short
+        # ``applied`` is only legitimate when the remainder were skipped.
+        if len(applied) + len(skipped) != len(commands):
             raise DocxError(
-                f"docx-studio applied {len(applied)} of {len(commands)} commands",
+                f"docx-studio applied {len(applied)} (+{len(skipped)} skipped) "
+                f"of {len(commands)} commands",
             )
 
-        results: list[Any] = []
+        # Build a positionally-aligned result list (one slot per input
+        # command). Applied slots carry the result dict; skipped slots stay
+        # ``None``. Each entry's ``index`` field places it at the right slot —
+        # we don't assume ``applied[]`` is a contiguous prefix once skips can
+        # appear anywhere in the batch.
+        results: list[Any] = [None] * len(commands)
         for entry in applied:
-            if isinstance(entry, dict):
-                result = entry.get("result")
-                results.append(result if isinstance(result, dict) else {})
-            else:
-                results.append({})
-        return results
+            if not isinstance(entry, dict):
+                continue
+            idx = entry.get("index")
+            if not isinstance(idx, int) or not (0 <= idx < len(results)):
+                continue
+            result = entry.get("result")
+            results[idx] = result if isinstance(result, dict) else {}
+
+        skipped_by_index: dict[int, dict[str, Any]] = {}
+        for entry in skipped:
+            if not isinstance(entry, dict):
+                continue
+            idx = entry.get("index")
+            if isinstance(idx, int) and 0 <= idx < len(commands):
+                skipped_by_index[idx] = entry
+        return results, skipped_by_index
 
 
 # ---------------------------------------------------------------------------

athena_python_docx-0.19.0/docx/_references.py

@@ -0,0 +1,82 @@
+"""Thin Python mirror of the @athenaintel/references TypeScript package.
+
+Used by the citation SDK method (``Paragraph.add_citation`` — an Athena
+extension beyond the python-docx surface). Mirrors only what the SDK needs to
+construct ``AssetReference`` + ``Anchor`` payloads — full reference
+serialization (URI / URL / Spaces format) is server-side.
+
+The anchor + version-policy dataclasses are re-exported from the shared
+``athena-references`` package (the single Python source of truth, kept in
+lockstep with ``packages/references`` and ``agora/agora/utils/asset_references``).
+``AssetReference`` is a thin back-compat wrapper that additionally accepts a
+plain ``dict`` ``meta`` and serializes it verbatim.
+
+Note (Athena extension):
+    This module is NOT part of python-docx — it exists to construct
+    Athena-asset references for the SDK's citation method.
+"""
+
+from __future__ import annotations
+
+__athena_extension_module__: bool = True
+__athena_extension_description__: str = (
+    "Cross-studio asset reference types (Athena studio-linking, no upstream)."
+)
+__athena_extension_since__: str = "0.11.0"
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from athena_references import (
+    Anchor,
+    PageAnchor,
+    PageRangeAnchor,
+    PmNodeAnchor,
+    PmNodeRangeAnchor,
+    ShapeAnchor,
+    SheetCellAnchor,
+    SheetRangeAnchor,
+    SheetTableAnchor,
+    SlideAnchor,
+    VersionPolicy,
+    VersionPolicyLatest,
+    VersionPolicyPinned,
+)
+
+
+@dataclass
+class AssetReference:
+    """Athena asset reference. ``id`` is the asset UUID.
+
+    Re-homes the canonical anchor types onto the shared ``athena-references``
+    package while preserving the historical SDK contract that ``meta`` may be a
+    plain ``dict`` (serialized verbatim) in addition to ``None``.
+    """
+
+    id: str
+    meta: Optional[dict[str, Any]] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the canonical wire shape."""
+        out: dict[str, Any] = {"referenced": "asset", "id": self.id}
+        if self.meta is not None:
+            out["meta"] = dict(self.meta)
+        return out
+
+
+__all__ = [
+    "AssetReference",
+    "Anchor",
+    "PageAnchor",
+    "PageRangeAnchor",
+    "PmNodeAnchor",
+    "PmNodeRangeAnchor",
+    "ShapeAnchor",
+    "SheetCellAnchor",
+    "SheetRangeAnchor",
+    "SheetTableAnchor",
+    "SlideAnchor",
+    "VersionPolicyLatest",
+    "VersionPolicyPinned",
+    "VersionPolicy",
+]

{athena_python_docx-0.18.3 → athena_python_docx-0.19.0}/docx/commands.py

@@ -926,6 +926,47 @@ class RemoveHyperlink(Command):
     target: dict[str, Any] = dataclasses.field(default_factory=dict)
 
 
+# ---------------------------------------------------------------------------
+# Citations (Athena extension — source-citation markers. No python-docx
+# analog; mirrors the PPTX studio's AddSlideCitation / RemoveCitation. The
+# studio server derives the openable ``citation_string`` (Spaces URL) from
+# ``source_ref`` + ``source_anchor`` via @athenaintel/references.)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CreateCitation(Command):
+    """Insert a source-citation marker.
+
+    Either ``text`` inserts a new cited span at ``at`` (a Word-style
+    superscript marker is appended after it), or ``target`` cites an existing
+    range. ``source_ref`` / ``source_anchor`` describe the cited source
+    (AssetReference / Anchor JSON, transited as dicts like ``SetImageAnchor``).
+    ``label`` is the marker glyph (defaults to a running index server-side).
+    ``client_entity_id`` is the client-minted citation id the applier honors
+    as the citation's stable id (the ``docx-editor-citations`` Y.Map key).
+    """
+
+    source_ref: dict[str, Any] = dataclasses.field(default_factory=dict)
+    source_anchor: dict[str, Any] | None = None
+    display_value: str | None = None
+    label: str | None = None
+    text: str | None = None
+    target: dict[str, Any] | None = None
+    at: dict[str, Any] | None = None
+    client_entity_id: str | None = None
+
+
+@dataclass
+class RemoveCitation(Command):
+    """Remove a citation by id — strips the marker mark and, by default,
+    deactivates the metadata record (``active: false``) so the removal is
+    undoable. ``soft=False`` splices the record out entirely."""
+
+    citation_id: str = ""
+    soft: bool = True
+
+
 # ---------------------------------------------------------------------------
 # Fields (Athena extension — python-docx has no field-add API. PAGE,
 # NUMPAGES, DATE, TIME, FILENAME, AUTHOR, NUMWORDS, REF, SEQ, TOC. The
@@ -1714,6 +1755,9 @@ _RESPONSE_BEARING_TYPES: frozenset[str] = frozenset(
         # Athena-extension response-bearing creates — each returns an
         # entity id the caller wraps in a proxy.
         "CreateHyperlink",
+        # CreateCitation eager-flushes so the marker's ``at`` offset stays
+        # correct relative to surrounding text inserts (mirrors CreateHyperlink).
+        "CreateCitation",
         "CreateField",
         "CreateBookmark",
         "CreateFootnote",
@@ -1783,6 +1827,8 @@ def _mark_athena_extension_command(cls: type, issue: "str | None", description:
 for _cls, _issue, _desc in [
     (CreateHyperlink, "python-docx#74", "Hyperlink add"),
     (RemoveHyperlink, "python-docx#74", "Hyperlink remove"),
+    (CreateCitation, None, "Source citation marker create"),
+    (RemoveCitation, None, "Source citation remove"),
     (CreateField, "python-docx#498", "Field insert"),
     (FieldsRefresh, "python-docx#498", "Field refresh"),
     (FieldsList, "python-docx#498", "Field enumeration"),
@@ -1914,6 +1960,8 @@ __all__ = [
     # semantics))
     "CreateHyperlink",
     "RemoveHyperlink",
+    "CreateCitation",
+    "RemoveCitation",
     "CreateField",
     "FieldsRefresh",
     "FieldsList",

{athena_python_docx-0.18.3 → athena_python_docx-0.19.0}/docx/document.py

@@ -936,6 +936,23 @@ class Document:
             include_hyperlinks=include_hyperlinks,
         )
 
+    @athena_extension(
+        description="Document.remove_citation — remove a source citation by id.",
+    )
+    def remove_citation(self, *, citation_id: str, soft: bool = True) -> None:
+        """Remove a source citation by id (Athena extension).
+
+        Strips the citation marker and, by default (``soft=True``),
+        deactivates the metadata record so the removal is undoable;
+        ``soft=False`` splices the record out entirely. No-op if the id is
+        unknown. No upstream python-docx analog.
+        """
+        from docx.commands import RemoveCitation
+
+        run_sync(
+            self._session.send_command(RemoveCitation(citation_id=citation_id, soft=soft))
+        )
+
     @athena_extension(issue=179, description="Document.add_chart.")
     def add_chart(
         self,

{athena_python_docx-0.18.3 → athena_python_docx-0.19.0}/docx/errors.py

@@ -68,6 +68,40 @@ class DocxError(Exception):
         return self
 
 
+class DocxUnsupportedCommandWarning(UserWarning):
+    """Emitted (not raised) when docx-studio reports that one or more commands
+    in a batch were *skipped* because the docx-editor engine doesn't implement
+    them yet (the server's ``skipped[]`` response array).
+
+    The batch still succeeds: every supported command applied and persisted.
+    Surfacing each skip as a warning — instead of letting one unsupported op
+    abort the whole batch into an empty document — is the graceful-degradation
+    contract. ``warnings.warn`` lets agent code observe the skip (a
+    ``warnings.catch_warnings(record=True)`` block, or the executor's warning
+    capture) without the script blowing up. Subclasses :class:`UserWarning` so
+    it surfaces by default and matches the SDK's other pending/unsupported
+    warning classes.
+    """
+
+
+class DocxUnsupportedCommandError(DocxError):
+    """Raised when a caller AWAITS the result of a command the docx-editor
+    engine doesn't implement (the server skipped it, reporting it in
+    ``skipped[]`` rather than ``applied[]``).
+
+    The graceful-degradation contract skips unsupported FIRE-AND-FORGET
+    mutations and merely warns (:class:`DocxUnsupportedCommandWarning`) — a
+    fire-and-forget mutation never reads its result, so dropping it keeps the
+    rest of the batch alive instead of nuking the document. But a query or
+    response-bearing command (``ExportPDF``, ``SectionsGet``, ``Find``,
+    ``CommentsGet``, …) is flushed eagerly precisely because the caller is
+    about to read its result. Returning some earlier applied mutation's result
+    in its place would be silent WRONG DATA, so the awaited-result path raises
+    this instead. Subclasses :class:`DocxError` so existing ``except
+    DocxError`` handlers still catch it.
+    """
+
+
 class SessionError(DocxError):
     """Raised when the Superdoc SDK session cannot be established or used."""
 

{athena_python_docx-0.18.3 → athena_python_docx-0.19.0}/docx/text/paragraph.py

@@ -9,6 +9,7 @@ from docx._athena_extension import athena_extension
 from docx._batching import run_sync
 
 if TYPE_CHECKING:
+    from docx._references import Anchor, AssetReference
     from docx.bookmarks import Bookmark
     from docx.client import Session
     from docx.enum.text import WD_ALIGN_PARAGRAPH
@@ -1448,6 +1449,97 @@ class Paragraph:
             range_=(start, end_offset),
         )
 
+    @athena_extension(
+        description="Paragraph.add_citation — append a source-citation marker.",
+    )
+    def add_citation(
+        self,
+        *,
+        source: "AssetReference",
+        text: str | None = None,
+        anchor: "Anchor | None" = None,
+        display_value: str | None = None,
+        label: str | None = None,
+    ) -> str:
+        """Attach a source citation to this paragraph (Athena extension).
+
+        Appends a Word-style superscript citation marker. When ``text`` is
+        given it is inserted first (the cited span) and the marker follows;
+        otherwise the marker attaches at the paragraph end, citing the
+        preceding text. ``source`` is the cited Athena asset; ``anchor``
+        optionally narrows it to a sub-location (a sheet range, PDF page, …).
+        ``display_value`` is the label shown on the citations-panel card;
+        ``label`` overrides the marker glyph (defaults to a bullet).
+
+        Renders in Olympus as a clickable superscript with a hover preview and
+        a Citations-panel entry; clicking opens the source in a new tab. No
+        upstream python-docx analog.
+
+        Returns the citation id.
+        """
+        import uuid
+
+        from docx._references import AssetReference
+        from docx.commands import CreateCitation
+
+        if not isinstance(source, AssetReference):
+            raise TypeError(
+                f"Paragraph.add_citation source requires an AssetReference; "
+                f"got {type(source).__name__} {source!r}",
+            )
+        if text is not None and not isinstance(text, str):
+            raise TypeError(
+                f"Paragraph.add_citation text requires str or None; got "
+                f"{type(text).__name__} {text!r}",
+            )
+        source_anchor: dict | None = None
+        if anchor is not None:
+            if not hasattr(anchor, "to_dict"):
+                raise TypeError(
+                    "Paragraph.add_citation anchor must be an Anchor dataclass "
+                    "(SheetRangeAnchor, PageAnchor, …); got "
+                    f"{type(anchor).__name__}",
+                )
+            source_anchor = anchor.to_dict()
+
+        # Cell-inner paragraphs hit the same addressing gap as add_hyperlink
+        # (BlockNotFoundError on flush). Citations in table cells are a
+        # follow-up; warn and skip rather than fail the whole batch.
+        if self._in_cell:
+            warnings.warn(
+                "Paragraph.add_citation on a cell-inner paragraph is not yet "
+                "supported (same addressing gap as add_hyperlink); the "
+                "citation was skipped.",
+                CellInnerFormatNotSupportedWarning,
+                stacklevel=2,
+            )
+            return ""
+
+        citation_id = f"citation_{uuid.uuid4().hex[:12]}"
+        start: int = self._resolve_text_len()
+        cursor: dict = {
+            "kind": "text",
+            "blockId": self._node_id,
+            "offset": start,
+        }
+        cmd = CreateCitation(
+            source_ref=source.to_dict(),
+            source_anchor=source_anchor,
+            display_value=display_value,
+            label=label,
+            text=text,
+            at={"kind": "selection", "start": cursor, "end": cursor},
+            client_entity_id=citation_id,
+        )
+        run_sync(self._session.send_command(cmd))
+        # The applier inserts ``text`` (if any) then a marker glyph (``label``
+        # or a 1-char bullet); keep the cached text length in sync so a
+        # follow-up op targets the right offset before the snapshot re-fetch.
+        marker_len = len(label) if label else 1
+        self._text_len = start + (len(text) if text else 0) + marker_len
+        self._invalidate_node_info()
+        return citation_id
+
     @athena_extension(
         issue=425,
         description="Paragraph.add_bookmark — zero-width anchor at paragraph end.",

{athena_python_docx-0.18.3 → athena_python_docx-0.19.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.18.3"
+version = "0.19.0"
 description = "Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack"
 readme = "README.md"
 license = "MIT"
@@ -26,6 +26,12 @@ dependencies = [
     # (urllib3 1.26.0); requests 2.28 only pins urllib3>=1.21.1, so we
     # tighten here to avoid a runtime TypeError on import.
     "urllib3>=1.26.6",
+    # Canonical Python source of truth for AssetReference + the Anchor union,
+    # re-exported by docx/_references.py for Paragraph.add_citation. Deploy
+    # follow-up: the document-exec sandbox vendors this wheel via
+    # `pip download --no-deps athena-references` (no PyPI access at build time),
+    # mirroring presentation-exec.
+    "athena-references>=0.1.0",
 ]
 
 [project.optional-dependencies]