athena-python-docx 0.11.3__tar.gz → 0.13.0__tar.gz

{athena_python_docx-0.11.3 → athena_python_docx-0.13.0}/CLAUDE.md

@@ -349,6 +349,212 @@ Issue numbers reference `python-openxml/python-docx`.
   wontfix upstream but the request keeps recurring. Routes through
   `ExportPDF` (SuperDoc handles the actual conversion).
 
+- **`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
+  left by ``Document.save(path)`` raising
+  ``LocalSaveTargetNotSupportedError`` in this SDK: parity test
+  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
+  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})``.
+
+  Template seeding: ``Document.create()`` (no ``docx=``) already
+  produces an exportable asset because ``POST /docs/empty`` seeds
+  from the default Athena template, so ``export_docx`` works
+  out-of-the-box. Pass ``docx='template.docx'`` only when you need
+  brand-specific scaffolding (styles, numbering, headers, rels,
+  media) baked in — not as a workaround for empty rooms.
+
+### 0.11.4 behavior fixes for cell-inner paragraphs
+
+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
+``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
+mistake mid-script nuked every other unrelated create/format command
+queued before it (``applied: []``).
+
+As of 0.11.4 these setters check the paragraph proxy's ``_in_cell``
+flag (set by ``_Cell.add_paragraph`` and ``_Cell.paragraphs``) and
+emit ``docx.text.paragraph.CellInnerFormatNotSupportedWarning``
+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.
+
+**0.11.5 follow-up: post-export OOXML rewrite.** When the parent
+table was created via ``Document.add_table`` in this session
+(``Table._doc_index`` set), the format setters also stash the
+OOXML-shaped props (``alignment``, ``style``, ``left_twips``,
+``before_twips``, etc.) on ``Session._post_export_ops`` (a
+: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
+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
+address). Behavior pinned by ``tests/test_cell_inner_format_stash.py``
++ ``tests/test_postproc_cell_format_rewrite.py``.
+
+**0.13.0: cell-inner ``Paragraph.add_run(text)`` now materializes the
+text live (not just at export).** The agent's standard ``fill_cell``
+helper pattern —
+
+.. code-block:: python
+
+    p = cell.add_paragraph("")
+    r = p.add_run("Hello world")
+    r.bold = True
+
+— 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
+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
+(set by ``_Cell.add_paragraph`` / ``_Cell.paragraphs`` /
+``_Cell.iter_inner_content``). When ``Paragraph.add_run(text)`` is
+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
+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
+OOXML address, so subsequent ``r.bold = True``-style setters stash
+to the correct cell location for the post-export OOXML rewrite.
+
+Fallback: empty text (``add_run("")``) and paragraphs without a
+``_cell`` back-ref (constructed outside the ``_Cell`` paths) still
+hit the warn-and-stub fallback so the surrounding batch survives.
+Wire failures inside the materialization path also fall back
+silently — one ``add_run`` failure should never cascade-fail a
+whole agent script.
+
+**0.13.0: cell-inner per-run formatting + cell-inner ``add_hyperlink``
+land at export time.** When a cell-inner ``Run`` has a stable OOXML
+address (parent paragraph came from a ``Document.add_table`` table —
+same ``_doc_index`` tracking as the cell-paragraph format stash),
+every per-run setter (``run.bold = True``, ``run.italic``,
+``run.font.size = Pt(11)``, ``run.font.color.rgb = …``,
+``run.font.name``, ``run.font.highlight_color``,
+``run.font.strike``, ``run.underline``, ``run.style``) stashes the
+prop on ``Session._post_export_ops._cell_run_format_ops`` instead
+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
+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-
+inner inserts. Multi-run cell paragraphs with partial-run
+formatting are a documented limitation — agents should use one
+run per format intent.
+
+Same export-time machinery rescues ``paragraph.add_hyperlink`` on a
+cell-inner paragraph. Pre-0.13.0 the call dropped both the URL AND
+the visible link text (the SDK returned a stub ``Hyperlink`` with
+an empty range because ``Insert`` on a cell-inner paragraph also
+fails with ``BlockNotFoundError``). As of 0.13.0 the URL + visible
+text + optional tooltip + optional bookmark fragment are stashed
+on ``Session._post_export_ops._cell_hyperlink_ops`` and the post-
+export OOXML rewrite appends a real ``<w:hyperlink>`` to the cell
+paragraph plus a matching ``Relationship`` entry in
+``word/_rels/document.xml.rels``. External URLs use ``r:id`` and
+get the document's built-in ``Hyperlink`` character style for the
+standard blue + underline appearance; internal bookmark anchors
+(``fragment="MyBookmark"`` with no ``url``) use ``w:anchor`` and
+don't add a rels entry. Repeated same-URL inserts coalesce to one
+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 —
+``Document.export_docx`` is the source of truth for the
+deliverable until then.
+
+### 0.11.4 behavior fixes elsewhere
+
+- **`Sections.__getitem__` short-circuits on empty docs.**
+  ``Document.create()`` doesn't materialize a section client-side,
+  so ``sections.list`` returns ``[]`` or times out at the full
+  command-budget. Pre-0.11.4 ``doc.sections[0]`` either raised an
+  un-contextualized ``IndexError`` from ``items[index]`` or hung
+  for ~60s. The cache-then-raise path now fails fast with a clear
+  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
+  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
+  rotated proxies onto a single target, surfacing as
+  ``ValidationError: Cell (r,c) not found in table table-auto-…``
+  on the next cell access.
+- **`set_borders` accepts string and dict.** Both
+  ``cell.set_borders(top="single 0.5pt #DDDDDD")`` and
+  ``cell.set_borders(top={"style": "single", "size_pt": 0.5,
+  "color": "#DDDDDD"})`` work; the string form is normalized via
+  ``_normalize_border_spec`` to the wire shape the server's Zod
+  validator expects. Pre-0.11.4 only the dict was accepted —
+  the string variant documented in the skill produced an immediate
+  HTTP 400 from the server's validator.
+- **`Run.add_field` segments shape.** ``run.add_field("PAGE")`` (and
+  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``;
+  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
+(``<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.
+
+As of 0.11.5, ``Document.create(docx=template.docx)`` scans the
+local template bytes with a stdlib zipfile + xml.etree parser and
+captures every ``<w:p>`` containing 1+ REF fields. Captures are
+stashed on ``Session._post_export_ops._captured_refs`` (list of
+:class:`docx._postproc.CapturedRefParagraph`). On
+``Document.export_docx``, the post-export OOXML rewrite walks the
+exported body; if any captured paragraph's exported counterpart has
+fewer REFs AND fingerprint-matches (plain-text content excluding
+field result runs), the exported ``<w:p>`` element is replaced
+wholesale with the captured XML. Behavior pinned by
+``tests/test_postproc_ref_restore.py``.
+
+Limitations: (1) restoration is in-process only — works when the
+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
+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).
+
 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;

{athena_python_docx-0.11.3 → athena_python_docx-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.11.3
+Version: 0.13.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.3 → athena_python_docx-0.13.0}/docx/__init__.py

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

{athena_python_docx-0.11.3 → athena_python_docx-0.13.0}/docx/_http_doc.py

@@ -262,14 +262,24 @@ _CELL_PARAGRAPH_HINT: str = (
     "\n\nHint: SuperDoc 1.8.1 cannot format paragraphs nested inside "
     "table cells via SetParagraphAlignment / SetParagraphStyle / "
     "SetParagraphIndentation / SetParagraphSpacing / doc.insert with "
-    "a paragraph-block target, or any FormatApply on a cell-inner run. "
-    "The cell's inner paragraph id is returned by cell.getNodeById but "
-    "isn't a top-level addressable block. Materialize the cell's "
-    'paragraph first via ``cell.text = "value"``, then re-read '
-    "``cell.paragraphs[0]`` and apply format ops to that post-"
-    "materialization Paragraph proxy. Tracked upstream at "
-    "docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md § 'cell-inner paragraph "
-    "addressing'."
+    "a paragraph-block target. The cell's original inner paragraph id "
+    "(returned by ``cell.paragraphs[0]`` on a freshly-loaded cell) "
+    "isn't a top-level addressable block.\n\nWorkaround: create a "
+    "fresh paragraph in the cell via ``para = cell.add_paragraph(text)`` "
+    "— 0.11.1+ routes that through ``doc.insert`` against the cell "
+    "with ``placement: 'insideEnd'``, so the returned ``Paragraph`` "
+    "proxy points at an addressable block. Apply format ops to that "
+    "proxy:\n\n"
+    '    para = cell.add_paragraph("MAY 2026")\n'
+    "    para.alignment = WD_ALIGN_PARAGRAPH.RIGHT  # works\n"
+    "    para.add_run(...).bold = True             # also works\n\n"
+    "Do NOT use ``cell.paragraphs[0].alignment = X`` on a freshly-"
+    "loaded cell — that targets the original cell-inner paragraph "
+    "which can't be addressed for format ops. If the cell already "
+    "has agent-authored content, use ``cell.paragraphs[-1]`` (the "
+    "most-recently-inserted paragraph, which is addressable). "
+    "Tracked upstream at docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md "
+    "§ 'cell-inner paragraph addressing'."
 )
 
 
@@ -480,12 +490,66 @@ def _http_post_json(
             timeout=timeout,
         )
     except requests.ConnectionError as e:
+        # ``RemoteDisconnected`` (server closed the TCP connection
+        # without a response) and ``ProtocolError`` (connection
+        # aborted mid-response) typically surface on long-running
+        # batches — the docx-studio nginx ingress idle-timeout or
+        # the SuperDoc CLI worker watchdog can both kill an
+        # in-flight request after a few minutes. We don't
+        # auto-retry these because the server may have already
+        # committed the work; a transport-level retry would risk
+        # double-applying the prefix that succeeded server-side.
+        # Instead, surface a typed error with actionable guidance
+        # so the agent can split the work into smaller batches.
+        # Identify the underlying error class without importing it
+        # — ``urllib3.exceptions.ProtocolError`` /
+        # ``http.client.RemoteDisconnected`` sit several wrap-layers
+        # deep and the import paths are version-sensitive.
+        err_chain = repr(e)
+        is_remote_disconnect = (
+            "RemoteDisconnected" in err_chain
+            or "ProtocolError" in err_chain
+            or "Connection aborted" in err_chain
+        )
+        if is_remote_disconnect:
+            n_commands = (
+                len(body.get("commands", []))
+                if isinstance(body, dict)
+                and isinstance(body.get("commands"), list)
+                else 0
+            )
+            hint = (
+                "docx-studio dropped the connection before sending a "
+                f"response (RemoteDisconnected) on a batch of "
+                f"~{n_commands} commands. The most common cause is an "
+                "idle-timeout on the docx-studio nginx ingress (~60s "
+                "wall clock) firing on a long-running SuperDoc CLI "
+                "operation. The server may or may not have committed "
+                "the work — the SDK cannot safely retry because that "
+                "would risk double-applying the successful prefix.\n"
+                "Recovery options:\n"
+                "  1. Re-open the document (``doc = Document(asset_id)``) "
+                "and continue the work in smaller chunks — flush every "
+                "~30 commands via ``doc.save()`` so each batch fits "
+                "comfortably under the ingress idle window.\n"
+                "  2. Break paragraph-heavy sections into separate "
+                "tool calls. Each ``execute_word_document_code`` "
+                "invocation starts a fresh HTTP connection.\n"
+                "  3. If the document already contains everything you "
+                "expected, the connection drop happened AFTER the "
+                "server committed — re-open and inspect "
+                "``len(doc.paragraphs)`` / ``len(doc.tables)`` before "
+                "retrying."
+            )
+            raise SessionError(f"{hint}\n\nOriginal error: {e}") from e
         raise SessionError(
             f"Unable to reach docx-studio at {url}: {e}",
         ) from e
     except requests.Timeout as e:
         raise SessionError(
-            f"docx-studio timed out at {url}: {e}",
+            f"docx-studio timed out at {url}: {e}. Split the work "
+            "into smaller batches (~30 commands per ``doc.save()``) "
+            "to fit under the ingress idle window.",
         ) from e
 
     # 207 (Multi-Status) is the server's signal for partial-batch