athena-python-docx 0.12.0__tar.gz → 0.14.0__tar.gz

{athena_python_docx-0.12.0 → athena_python_docx-0.14.0}/CLAUDE.md

@@ -355,11 +355,25 @@ Issue numbers reference `python-openxml/python-docx`.
   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, and pointing callers at
-  Olympus's Export DOCX action breaks every headless flow.
-  Routes through ``ExportDocx`` → SuperDoc's ``exportDocx``;
-  raises ``DocxError`` when the server build doesn't expose it
-  rather than silently writing zero bytes.
+  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
 
@@ -380,16 +394,101 @@ 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. Behavior pinned
-by ``tests/test_athena_extensions_registry.py`` and the buffer
-tests; ``add_hyperlink`` in a cell drops BOTH the URL and the link
-text (empirically, ``Insert`` on a cell-inner paragraph also fails
-with ``BlockNotFoundError`` — so the obvious ``add_run(text)``
-fallback can't even land the visible text without nuking the
-surrounding batch). The call returns a stub ``Hyperlink`` with an
-empty range so callers don't crash; insert any visible text via
-``cell.text = '...'`` before calling ``add_hyperlink`` if you need
-the link text to survive.
+``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
 
@@ -425,6 +524,37 @@ the link text to survive.
   ``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.12.0 → athena_python_docx-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.12.0
+Version: 0.14.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.12.0 → athena_python_docx-0.14.0}/docx/__init__.py

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

{athena_python_docx-0.12.0 → athena_python_docx-0.14.0}/docx/_http_doc.py

@@ -95,6 +95,11 @@ from docx.commands import (
     GetNodeById,
     HeaderFootersGet,
     HeaderFootersList,
+    HeaderFootersPartsCreate,
+    HeaderFootersPartsDelete,
+    HeaderFootersPartsList,
+    HeaderFootersRefsClear,
+    HeaderFootersRefsSet,
     HeaderFootersRefsSetLinkedToPrevious,
     HeaderFootersResolve,
     ImagesGet,
@@ -152,6 +157,7 @@ from docx.commands import (
     TablesSetColumnWidth,
     TablesSetLayout,
     TablesSetRowHeight,
+    TablesSetRowOptions,
     TablesSetStyle,
     TablesSetTableOptions,
     TableSetCell,
@@ -307,6 +313,7 @@ _TABLE_QUERY_COMMANDS: frozenset[str] = frozenset(
         "TablesSetCellProperties",
         "TablesSetColumnWidth",
         "TablesSetRowHeight",
+        "TablesSetRowOptions",
         "TablesInsertRow",
         "TablesInsertColumn",
         "TablesMergeCells",
@@ -490,12 +497,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
@@ -767,6 +828,7 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "tables.set_cell_properties": TablesSetCellProperties,
     "tables.set_column_width": TablesSetColumnWidth,
     "tables.set_row_height": TablesSetRowHeight,
+    "tables.set_row_options": TablesSetRowOptions,
     "tables.set_cell": TableSetCell,
     # Images (mutations)
     "images.set_size": SetImageSize,
@@ -797,6 +859,11 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "header_footers.get": HeaderFootersGet,
     "header_footers.resolve": HeaderFootersResolve,
     "header_footers.refs.set_linked_to_previous": HeaderFootersRefsSetLinkedToPrevious,
+    "header_footers.parts.create": HeaderFootersPartsCreate,
+    "header_footers.parts.list": HeaderFootersPartsList,
+    "header_footers.parts.delete": HeaderFootersPartsDelete,
+    "header_footers.refs.set": HeaderFootersRefsSet,
+    "header_footers.refs.clear": HeaderFootersRefsClear,
     # Lists & Selection. ``lists.create`` and ``lists.attach`` are
     # consumed internally by ``Document.add_paragraph`` to make
     # ``style="List Bullet" | "List Number"`` produce real list