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

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

@@ -67,11 +67,7 @@ These standard python-docx members don't apply to a Superdoc-backed SDK:
 ### Phase-3b upstream-blocked surface
 
 These are *shipped at the surface* but partially or fully no-op at
-runtime, pending SuperDoc SDK changes outside this repo. The
-upstream constraints have been verified against
-[SuperDoc's published docs](https://docs.superdoc.dev/document-api/reference/styles/apply)
-and the bundled TypeScript types in
-`node_modules/@superdoc-dev/sdk/dist/generated/client.d.ts`. See
+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.
 
@@ -132,16 +128,15 @@ not file-backed. Each is documented in the relevant docstring.
 
 - **`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
+  for `Document(None)`; we can't fabricate a Word document 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.
+    constructor kwarg: when provided, the SDK creates a normal Word
+    document asset through Agora's docx-studio bridge, then imports the
+    local `.docx` into that asset. 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
@@ -222,22 +217,6 @@ 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"`,
@@ -405,6 +384,38 @@ Issue numbers reference `python-openxml/python-docx`.
   cleanup loops, which left horizontal-rule and scratch-content artifacts
   in the document during failed-run recoveries.
 
+- **`Paragraph.add_citation(source, *, anchor=None, excerpt=None,
+  display_value=None) -> str`** + **`Paragraph.clear_citations()`** +
+  **`Document.add_citation(source, *, destination_anchor, anchor=None,
+  ...)`** + **`Document.remove_citation(citation_id)`** (0.20.0+) —
+  SDK-native Athena citations. This is the programmatic equivalent of
+  the user selecting DOCX text and choosing "Use selection as citation
+  destination/source" in Olympus: it writes the canonical document
+  citation record into the document's ``citations`` Y.Array and applies
+  the citation-blue highlight to the destination paragraph/range. It is
+  not a live link and does not overwrite destination text.
+
+  Common agent pattern after writing a supported claim:
+
+  ```python
+  from docx import Document
+  from docx._references import AssetReference, SheetRangeAnchor
+
+  doc = Document("asset_word")
+  p = doc.add_paragraph("The combined assessment identified 20,049 total vulnerabilities.")
+  citation_id = p.add_citation(
+      AssetReference(id="asset_spreadsheet"),
+      anchor=SheetRangeAnchor(sheet_id=0, range="B2:B8"),
+      excerpt="20,049 total vulnerabilities",
+      display_value="Vulnerability total",
+  )
+  doc.save()
+  ```
+
+  Use ``Document.add_citation(..., destination_anchor=PmNodeAnchor(...))``
+  only when you already have a DOCX editor anchor id. For normal writing,
+  cite the ``Paragraph`` proxy you just created or found.
+
 - **`Document.export_docx(path=None, *, include_revisions=False)
   -> bytes`** (0.11.4+) — export the document's current state as
   ``.docx`` bytes, optionally writing to ``path``. Closes the gap
@@ -413,16 +424,13 @@ Issue numbers reference `python-openxml/python-docx`.
   harnesses and CI workflows need a programmatic .docx export to
   diff against ``python-docx`` output that doesn't require a
   human-driven Olympus UI action. Routes through ``ExportDocx`` →
-  apps/api → SuperDoc's official ``doc.save({out: <tmp>})`` (the
-  recommended backend export path per the SuperDoc team — Document
-  API, not the browser-side ``editor.exportDocx`` shim). apps/api
+  apps/api's backend export path. apps/api
   writes the session state to a temp ``.docx``, reads bytes back,
   base64-encodes for the wire, and unlinks the temp in a
   ``finally`` block. The SDK decodes and writes to ``path``.
   ``include_revisions=True`` raises ``DocxError`` pre-flight:
-  ``@superdoc-dev/sdk@1.8.1``'s ``DocSaveParams`` has no
-  ``includeRevisions`` field, so honoring the flag isn't possible
-  through ``doc.save({out})``.
+  the current backend export path has no ``includeRevisions`` support,
+  so honoring the flag isn't possible yet.
 
   Template seeding: ``Document.create()`` (no ``docx=``) already
   produces an exportable asset because ``POST /docs/empty`` seeds
@@ -617,6 +625,80 @@ natively, the SDK should swap to the upstream signature in place;
 this section is the canonical reference for what each Athena
 extension wires up.
 
+### Behavioral-parity deviations (2026 deep-dive, v0.19.0)
+
+A deep behavioral audit against python-docx 1.2.0 (the structural
+parity ratchet only sees shape, not runtime behavior) fixed ~40
+divergences so they now match upstream exactly — `Pt`/`RGBColor`
+coercion, `Font.size` bare-int-is-EMU, `Font.underline`
+SINGLE→`True`/NONE→`False`, `line_spacing` integer multipliers,
+`line_spacing_rule` rule-only members, `Hyperlink.url`/`.address`,
+`Table.autofit`/`_Row.cells`/`_Column.cells`, `Section`
+orientation/start-type defaults + `Sections` slicing,
+`Styles.get_by_id`/`get_style_id`/`default(LIST)`/`add_style`,
+`Document.add_heading` (`ValueError`), `add_paragraph` strict heading
+routing, `add_picture` native size + aspect ratio, `WD_BUILTIN_STYLE`
+(now the 132-member int enum aliased to `WD_STYLE`),
+`docx.enum.shape.WD_INLINE_SHAPE`, `InlineShape.type`/zero-dimensions,
+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:
+
+- **`WD_*` enum `.value` is the SuperDoc 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
+  `enum.value` directly onto the wire (`underline=value.value`,
+  `WD_COLOR_INDEX(v).value`, …), so int-valuing the enums would require
+  re-plumbing the entire command layer. Members are accessed by name
+  (`WD_ALIGN_PARAGRAPH.CENTER`), so the drift is academic for normal
+  use. (`WD_STYLE`/`WD_BUILTIN_STYLE` and `WD_INLINE_SHAPE_TYPE` are NOT
+  wire-load-bearing and DO carry the upstream int values.)
+
+- **`RGBColor.from_string` additionally accepts a leading `#`.** Upstream
+  rejects `"#FF0000"`; agents routinely pass it, so a single `#` is
+  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
+  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
+  `ValueError`).
+
+- **`Table.cell(row, col)` bounds-checks each axis independently** and
+  raises `IndexError` for an out-of-range row or column. Upstream
+  indexes a single flat row-major `_cells` list, so a column overflow
+  spills into the next row and `cell(-1, -1)` resolves against the flat
+  list (NOT the bottom-right cell). Athena's per-axis contract is the
+  more intuitive, stricter behavior for an HTTP-backed proxy that can't
+  cheaply enumerate every cell. `(0,0)` and in-range negative indices
+  behave identically to upstream.
+
+- **`BaseStyle.style_id` returns the display name for built-ins** (so
+  `style_id == name`). The SDK is HTTP-only and can't read `styles.xml`
+  to recover the OOXML styleId (`"Heading 1"` → `"Heading1"`); the wire
+  format also uses the display name as the style id. Consequently
+  `get_by_id("Heading1", …)` / `"Heading1" in styles` won't resolve the
+  OOXML-id form (use the display name).
+
+- **`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
+  raises eagerly rather than failing opaquely on the wire.
+
+- **`Comment.comment_id` returns `str`, not `int`.** SuperDoc uses
+  non-numeric entity ids (`"c-42"`), so the upstream `int` contract
+  can't be honored. Tracked in `SUPERDOC_UPSTREAM_REQUESTS.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
+  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`.
+
 ### If you need a deviation
 
 If there is a genuine technical reason why a deviation from python-docx is necessary:

{athena_python_docx-0.19.0 → athena_python_docx-0.21.0}/DOCX_EXEC_LAB.md

@@ -1,7 +1,7 @@
 # DocX Execution Lab
 
 `scripts/docx_exec_lab.py` is a headless runner for quickly testing
-`athena-python-docx` snippets against Athena SuperDocument assets. It
+`athena-python-docx` snippets against Athena Word document 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.
@@ -85,10 +85,10 @@ uv run python scripts/docx_exec_lab.py \
   --export-docx
 ```
 
-## Local UI With SuperDoc Embed
+## Local UI With DOCX Editor Embed
 
 The lab also includes a local-only HTML UI that wraps the same headless
-runner and iframes Olympus's existing SuperDoc embed route.
+runner and iframes Olympus's existing DOCX editor embed route.
 
 ```bash
 cd docx-studio/python-sdk
@@ -107,7 +107,7 @@ Defaults:
 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.
+URL, so changes render in the real Olympus DOCX editor viewer.
 
 If the staging Agora URL differs, pass:
 

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.19.0
-Summary: Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack
+Version: 0.21.0
+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>
 License-Expression: MIT
@@ -28,7 +28,7 @@ Description-Content-Type: text/markdown
 
 # athena-python-docx
 
-Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that connects to Athena's Superdoc + Keryx collaborative document stack.
+Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that connects to Athena's Keryx-backed Word document stack.
 
 ## Quick start
 
@@ -36,7 +36,7 @@ Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that
 from docx import Document
 from docx.shared import Inches, Pt, RGBColor
 
-# Open an existing SuperDoc asset by its Athena asset_id
+# Open an existing Word document asset by its Athena asset_id
 with Document("asset_abc123") as doc:
     doc.add_heading("Market Analysis", level=1)
 
@@ -75,15 +75,14 @@ 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`.
+an Olympus Word document embed preview pane. See `DOCX_EXEC_LAB.md`.
 
 ## Environment variables
 
-Required when connecting to Keryx (set by Athena backend when executing in Daytona):
+Required when connecting to DOCX Studio (set by Athena backend when executing in Daytona):
 
-- `SUPERDOC_COLLAB_TOKEN` — short-lived Keryx JWT
-- `KERYX_WS_URL` — Keryx WebSocket base URL
-- `ATHENA_WORKSPACE_ID` — workspace routing segment
+- `ATHENA_DOCX_BASE_URL` — DOCX Studio API base URL
+- `ATHENA_DOCX_API_KEY` — Athena API key or service-issued DOCX Studio token
 
 ## License
 

{athena_python_docx-0.19.0 → athena_python_docx-0.21.0}/README.md

@@ -1,6 +1,6 @@
 # athena-python-docx
 
-Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that connects to Athena's Superdoc + Keryx collaborative document stack.
+Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that connects to Athena's Keryx-backed Word document stack.
 
 ## Quick start
 
@@ -8,7 +8,7 @@ Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that
 from docx import Document
 from docx.shared import Inches, Pt, RGBColor
 
-# Open an existing SuperDoc asset by its Athena asset_id
+# Open an existing Word document asset by its Athena asset_id
 with Document("asset_abc123") as doc:
     doc.add_heading("Market Analysis", level=1)
 
@@ -47,15 +47,14 @@ 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`.
+an Olympus Word document embed preview pane. See `DOCX_EXEC_LAB.md`.
 
 ## Environment variables
 
-Required when connecting to Keryx (set by Athena backend when executing in Daytona):
+Required when connecting to DOCX Studio (set by Athena backend when executing in Daytona):
 
-- `SUPERDOC_COLLAB_TOKEN` — short-lived Keryx JWT
-- `KERYX_WS_URL` — Keryx WebSocket base URL
-- `ATHENA_WORKSPACE_ID` — workspace routing segment
+- `ATHENA_DOCX_BASE_URL` — DOCX Studio API base URL
+- `ATHENA_DOCX_API_KEY` — Athena API key or service-issued DOCX Studio token
 
 ## License
 

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

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

athena_python_docx-0.21.0/docx/_citations.py

@@ -0,0 +1,74 @@
+"""Helpers for SDK-native Athena citations."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from docx._references import AssetReference
+from docx.commands import AddCitation
+
+
+def new_citation_id() -> str:
+    return f"citation_{uuid.uuid4().hex[:12]}"
+
+
+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 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,
+    anchor: object | None,
+    excerpt: str | None,
+    display_value: str | None,
+) -> tuple[str, AddCitation]:
+    citation_id = new_citation_id()
+    return citation_id, AddCitation(
+        destination_anchor=destination_anchor_to_dict(destination_anchor),
+        source_ref=source_ref_to_dict(source),
+        source_anchor=anchor_to_dict(anchor),
+        citation_id=citation_id,
+        excerpt=excerpt,
+        display_value=display_value,
+    )