athena-python-docx 0.21.8__tar.gz → 0.22.0__tar.gz

athena_python_docx-0.21.8/CLAUDE.md → athena_python_docx-0.22.0/AGENTS.md

@@ -367,8 +367,8 @@ Issue numbers reference `python-openxml/python-docx`.
   list metadata. Routes through `NumberingGet`.
 
 - **`Document.to_pdf(*, quality=None, destination=None,
-  include_revisions=False) -> bytes`** — render to PDF via the
-  Daytona-hosted LibreOffice. python-docx issue #113 was closed as
+  include_revisions=False) -> bytes`** — render to PDF. python-docx
+  issue #113 was closed as
   wontfix upstream but the request keeps recurring. Routes through
   `ExportPDF` (DOCX Studio handles the actual conversion).
 
@@ -447,6 +447,40 @@ Issue numbers reference `python-openxml/python-docx`.
   only when you already have a DOCX editor anchor id. For normal writing,
   cite the ``Paragraph`` proxy you just created or found.
 
+- **Table-cell citations** (0.22.0+): **`_Cell.add_citation(source, *,
+  anchor=None, citation_string=None, excerpt=None, display_value=None)
+  -> str`** + **`_Cell.clear_citations()`**, and ``Paragraph.add_citation``
+  / ``Paragraph.clear_citations`` on cell paragraphs (before 0.22.0 they
+  raised ``ValueError`` "top-level DOCX paragraphs only"). The SDK models a
+  cell as one paragraph addressed by the synthetic cell id
+  (``tc:table:row:col``; ``cell.paragraphs[0]`` stands for the whole cell),
+  so a cell citation sends that id. The docx-studio applier resolves it to
+  the cell's paragraph ids: one paragraph with text → ``pm_node``, several
+  → ``pm_node_range`` from the first to the last; a cell paragraph with no
+  paraId (or a repeated one) gets a new one. A horizontally merged cell
+  resolves to its master cell from any grid position it covers. A
+  paragraph that ``cell.add_paragraph(text)`` returned already carries its
+  own paraId and is cited alone. To cite one paragraph of a cell (or a
+  paragraph in a nested table), pass the ``data-id`` a Word read shows for
+  it: ``doc.add_citation(..., destination_anchor=PmNodeAnchor(node_id=...))``.
+  ``_Cell.clear_citations()`` removes every citation inside the cell.
+  Write the cell text first, then cite it:
+
+  ```python
+  table = doc.add_table(rows=2, cols=2)
+  table.cell(1, 0).text = "Revenue"
+  table.cell(1, 1).text = "$12.4M"
+  table.cell(1, 1).add_citation(
+      "/dashboard/spaces/?asset_ids=asset_sheet&type=spreadsheet"
+      "&anchor=sheet_range&sheet_id=0&range=C4",
+      excerpt="$12.4M",
+  )
+  ```
+
+  Needs a docx-studio API that resolves cell ids (the same release train);
+  an older API stores the record under the cell id, where nothing renders
+  it and the next edit retires it.
+
 - **`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
@@ -769,7 +803,7 @@ This is a **thin HTTP client** that mimics the sync python-docx API.
   drain pending ops before running; the 100 ms idle timer fires on
   inactivity so collab updates stream live; `Document.save()` and
   the context-manager exit drain explicitly; `docx.flush_all()` is
-  the Daytona-prelude hook that flushes every live buffer in the
+  the executor-postamble hook that flushes every live buffer in the
   process.
 - Execution scope: executor sandboxes may keep Python globals
   between tool calls so imports, constants, and helper functions can be

athena_python_docx-0.22.0/CLAUDE.md

@@ -0,0 +1,5 @@
+@AGENTS.md
+
+<!-- AGENTS.md next to this file is the single source of truth for agent
+     instructions. Claude Code does not read AGENTS.md natively, so this file
+     imports it. Add Claude-Code-only rules below this line. -->

{athena_python_docx-0.21.8 → athena_python_docx-0.22.0}/DOCX_EXEC_LAB.md

@@ -6,7 +6,7 @@ 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.
 
-Use this before waiting on a full Agent -> Daytona -> preview cycle when
+Use this before waiting on a full Agent -> executor sandbox -> preview cycle when
 debugging SDK behavior such as large-document replacement, table fills,
 unsupported OOXML internals, or export fidelity.
 

{athena_python_docx-0.21.8 → athena_python_docx-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.21.8
+Version: 0.22.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>
@@ -76,7 +76,7 @@ an Olympus Word document embed preview pane. See `DOCX_EXEC_LAB.md`.
 
 ## Environment variables
 
-Required when connecting to DOCX Studio (set by Athena backend when executing in Daytona):
+Required when connecting to DOCX Studio (set by the Athena backend in the `execute_word_document_code` executor sandbox):
 
 - `ATHENA_DOCX_BASE_URL` — DOCX Studio API base URL
 - `ATHENA_DOCX_API_KEY` — Athena API key or service-issued DOCX Studio token

{athena_python_docx-0.21.8 → athena_python_docx-0.22.0}/README.md

@@ -51,7 +51,7 @@ an Olympus Word document embed preview pane. See `DOCX_EXEC_LAB.md`.
 
 ## Environment variables
 
-Required when connecting to DOCX Studio (set by Athena backend when executing in Daytona):
+Required when connecting to DOCX Studio (set by the Athena backend in the `execute_word_document_code` executor sandbox):
 
 - `ATHENA_DOCX_BASE_URL` — DOCX Studio API base URL
 - `ATHENA_DOCX_API_KEY` — Athena API key or service-issued DOCX Studio token

{athena_python_docx-0.21.8 → athena_python_docx-0.22.0}/docx/__init__.py

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

{athena_python_docx-0.21.8 → athena_python_docx-0.22.0}/docx/_buffer.py

@@ -20,7 +20,7 @@ guard the pending list with an RLock and treat the timer flush as a
 best-effort coalesce — if the loop thread races us we just flush twice
 (or zero times; the next loop-thread call drains it).
 
-`flush_all` is a process-wide hook used by the Daytona sandbox prelude to
+`flush_all` is a process-wide hook used by Athena's sandbox executor to
 make sure pending writes hit Keryx before the sandbox is suspended. It walks
 a weak-ref registry so dead Workbook instances don't keep their buffers
 alive.
@@ -199,7 +199,7 @@ def _unregister(buffer: "CommandBuffer") -> None:
 def flush_all(*, strict: bool = False) -> None:
     """Flush every live CommandBuffer in this process.
 
-    Used by the Daytona sandbox prelude after user code returns, so
+    Used by Athena's sandbox executor after user code returns, so
     buffered mutations make it to Keryx before the sandbox is suspended.
     Safe to call when no Buffers exist (no-op).
 

{athena_python_docx-0.21.8 → athena_python_docx-0.22.0}/docx/_http.py

@@ -5,7 +5,7 @@ bootstrap and upload calls on urllib so ``Document.create()`` can provision
 Word document assets without pulling in extra runtime dependencies.
 
 We use ``urllib`` from stdlib to avoid pulling ``httpx`` / ``requests``
-into the runtime — this code runs in Daytona sandboxes where every MB
+into the runtime — this code runs in sandboxes where every MB
 matters, and the existing SDK already keeps its dep tree tight.
 """
 

{athena_python_docx-0.21.8 → athena_python_docx-0.22.0}/docx/_http_doc.py

@@ -46,6 +46,7 @@ from docx.commands import (
     BookmarksList,
     ChartsGet,
     ChartsList,
+    ClearBody,
     ClearParagraphAlignment,
     ClearParagraphIndentation,
     ClearParagraphSpacing,
@@ -1002,6 +1003,7 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "sdt.delete": ContentControlsDelete,
     "sections.set_columns": SetSectionColumns,
     "find_replace": FindReplace,
+    "clear_body": ClearBody,
     "find_text": FindText,
     "iter_runs": IterRuns,
     "export_pdf": ExportPDF,

{athena_python_docx-0.21.8 → athena_python_docx-0.22.0}/docx/_postproc.py

@@ -497,6 +497,27 @@ class PostExportOps:
             or bool(self._row_cant_split_ops)
         )
 
+    def discard_body_ops(self) -> None:
+        """Drop every rewrite that addresses body content by position.
+
+        Cell/table formatting, row heights, captured REF paragraphs and
+        header/footer relocations are all keyed by body-relative indices
+        (``table_doc_index``, ``source_paragraph_index``, body node ids).
+        Once the body story has been replaced they point at nodes that no
+        longer exist — and would silently re-target whatever the caller
+        creates next at the same index. Document-wide rewrites
+        (``font_override``) do not address the body and are kept.
+        """
+        self._cell_format_ops.clear()
+        self._cell_run_format_ops.clear()
+        self._cell_hyperlink_ops.clear()
+        self._cell_shading_ops.clear()
+        self._table_borders_ops.clear()
+        self._captured_refs.clear()
+        self._row_height_ops.clear()
+        self._row_cant_split_ops.clear()
+        self._header_footer_relocations.clear()
+
     def add_row_cant_split(
         self,
         *,

{athena_python_docx-0.21.8 → athena_python_docx-0.22.0}/docx/_ptc.py

@@ -23,6 +23,11 @@ Emits are **synchronous, best-effort** HTTP POSTs:
 - Snapshot the URL at ``emit_begin`` time and carry it to ``emit_end``
   so late end events can't be misattributed if a new sandbox run
   swapped in a different URL between begin and end.
+- Reuse one keep-alive connection per endpoint instead of a new TCP (and
+  TLS) connection per event. An idle connection the server has closed is
+  detected before sending and replaced; a send is never retried (the
+  registry does not deduplicate events). When a proxy applies to the URL
+  (``*_proxy`` env vars) each event goes through urllib as before.
 
 This module is *intentionally byte-identical* across the docx / pptx /
 xlsx SDKs — the three SDKs have no shared base. Duplicating ~100 LOC
@@ -31,10 +36,14 @@ of stdlib code is cheaper than spinning up a 4th release pipeline.
 
 from __future__ import annotations
 
+import http.client
 import json
 import os
+import select
+import threading
 import time
 import urllib.error
+import urllib.parse
 import urllib.request
 import uuid
 from typing import Any
@@ -46,6 +55,58 @@ _HTTP_TIMEOUT = 2.0
 # original run's endpoint even if ATHENA_PTC_URL changed since.
 _call_url: dict[str, str] = {}
 
+# (scheme, host:port) -> an idle keep-alive connection. Checked out while a
+# POST uses it, so no two threads ever share one.
+_idle: dict[tuple[str, str], http.client.HTTPConnection] = {}
+_idle_lock = threading.Lock()
+
+
+def _dropped(conn: http.client.HTTPConnection) -> bool:
+    """An idle connection the server has closed (or that has unexpected data
+    waiting) reads as ready: never send on it."""
+    sock = conn.sock
+    if sock is None:
+        return True
+    try:
+        return bool(select.select([sock], [], [], 0)[0])
+    except (OSError, ValueError):
+        return True
+
+
+def _post_keepalive(url: str, raw: bytes) -> None:
+    parts = urllib.parse.urlsplit(url)
+    if parts.scheme not in ("http", "https") or not parts.hostname:
+        raise ValueError(f"unsupported PTC URL: {url!r}")
+    target = (parts.path or "/") + (f"?{parts.query}" if parts.query else "")
+    key = (parts.scheme, parts.netloc)
+    with _idle_lock:
+        conn = _idle.pop(key, None)
+    if conn is not None and _dropped(conn):
+        conn.close()
+        conn = None
+    if conn is None:
+        factory = (
+            http.client.HTTPSConnection if parts.scheme == "https" else http.client.HTTPConnection
+        )
+        conn = factory(parts.netloc, timeout=_HTTP_TIMEOUT)
+    # Never retried: a failure after the request left may still have been
+    # processed, and the registry does not deduplicate events.
+    try:
+        conn.request("POST", target, body=raw, headers={"Content-Type": "application/json"})
+        response = conn.getresponse()
+        response.read()
+    except BaseException:
+        conn.close()
+        raise
+    if response.will_close:
+        conn.close()
+        return
+    with _idle_lock:
+        spare = _idle.pop(key, None)
+        _idle[key] = conn
+    if spare is not None:
+        spare.close()
+
 
 def _send(url: str, body: dict[str, Any]) -> None:
     """Synchronously POST one PTC event. Best-effort; never raises.
@@ -63,14 +124,19 @@ def _send(url: str, body: dict[str, Any]) -> None:
             key = "args" if body.get("phase") == "begin" else "result"
             body[key] = {"__truncated__": True}
             raw = json.dumps(body).encode("utf-8")
-        req = urllib.request.Request(
-            url,
-            data=raw,
-            method="POST",
-            headers={"Content-Type": "application/json"},
-        )
-        urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT).close()
-    except (urllib.error.URLError, OSError, ValueError):
+        parts = urllib.parse.urlsplit(url)
+        proxy = urllib.request.getproxies().get(parts.scheme)
+        if proxy and not urllib.request.proxy_bypass(parts.hostname or ""):
+            req = urllib.request.Request(
+                url,
+                data=raw,
+                method="POST",
+                headers={"Content-Type": "application/json"},
+            )
+            urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT).close()
+        else:
+            _post_keepalive(url, raw)
+    except (urllib.error.URLError, OSError, ValueError, http.client.HTTPException):
         pass  # never propagate — PTC is best-effort
 
 

{athena_python_docx-0.21.8 → athena_python_docx-0.22.0}/docx/_timeouts.py

@@ -19,6 +19,9 @@ _LONG_RUNNING_COMMAND_TYPES: frozenset[str] = frozenset(
         # ordinary 60s budget committing a table batch even when the Python code
         # uses the fast no-read cell path.
         "TableSetCell",
+        # ``Document.clear()`` replaces the whole body story in one write;
+        # on a large document that single command can outlast the 60s budget.
+        "ClearBody",
     }
 )
 

{athena_python_docx-0.21.8 → athena_python_docx-0.22.0}/docx/client.py

@@ -36,7 +36,7 @@ if TYPE_CHECKING:
 
 def _log_info(msg: str) -> None:
     """Minimal stderr logger; we avoid loguru to keep the SDK runtime
-    dependency tree small (this code runs inside Daytona sandboxes)."""
+    dependency tree small (this code runs inside sandboxes)."""
     import sys
 
     print(f"[docx-sdk] {msg}", file=sys.stderr)
@@ -84,6 +84,10 @@ class Session:
         from docx._postproc import PostExportOps
 
         self._post_export_ops: PostExportOps = PostExportOps()
+        # Bumped by ``Document.clear()``. ``Table`` proxies remember the
+        # generation they were created in, so a proxy from before a clear
+        # can never be re-anchored to a table created after it.
+        self._body_generation: int = 0
 
     @property
     def asset_id(self) -> str:

{athena_python_docx-0.21.8 → athena_python_docx-0.22.0}/docx/commands.py

@@ -136,6 +136,10 @@ class Insert(Command):
     # on the DOCX Studio call (renamed in transit so it doesn't collide with our
     # discriminator).
     value_type: str | None = None
+    # Text mode only. ``True`` continues the formatting of the run at the
+    # insertion point (``Run.add_text``); omitted means the inserted text is
+    # a fresh, unformatted run (``Paragraph.add_run``).
+    inherit_marks: bool | None = None
     placement: str | None = None
     content: dict[str, Any] | None = None
 
@@ -1543,6 +1547,18 @@ class FindReplace(Command):
     max_replacements: int | None = None
 
 
+@dataclass
+class ClearBody(Command):
+    """Replace the whole body story with a single empty paragraph.
+
+    Athena extension backing :meth:`Document.clear`. One server-side
+    write instead of a ``Replace`` per paragraph and per table-cell
+    paragraph; headers, footers and notes are untouched and the final
+    section's page setup survives. Returns ``{nodeId}`` of the new
+    empty paragraph.
+    """
+
+
 @dataclass
 class FindText(Command):
     """Search document text and return bounded match context.
@@ -1576,8 +1592,8 @@ class IterRuns(Command):
 
 # ---------------------------------------------------------------------------
 # PDF Export (Athena extension — python-docx issue #113 keeps getting
-# re-asked despite being closed wontfix. DOCX Studio renders via Daytona
-# (LibreOffice headless) to bytes the client can download or persist.)
+# re-asked despite being closed wontfix. DOCX Studio renders the document
+# to bytes the client can download or persist.)
 # ---------------------------------------------------------------------------
 
 
@@ -1759,6 +1775,9 @@ _RESPONSE_BEARING_TYPES: frozenset[str] = frozenset(
         "ExportDocx",
         # FindReplace returns a replacement count for the caller.
         "FindReplace",
+        # ClearBody replaces the whole body; Document.clear awaits it so a
+        # rejected clear raises instead of leaving stale content behind.
+        "ClearBody",
     }
 )
 
@@ -1852,6 +1871,7 @@ for _cls, _issue, _desc in [
     (ContentControlsDelete, "python-docx#155", "SDT delete"),
     (SetSectionColumns, "python-docx#167", "Section multi-column layout"),
     (FindReplace, "python-docx#30", "Formatting-preserving find/replace"),
+    (ClearBody, None, "Document.clear — bulk body reset"),
     (FindText, "python-docx#980", "Fast document text search"),
     (IterRuns, "python-docx#980", "Run stream for run-isolation"),
     (ExportPDF, "python-docx#113", "PDF export"),
@@ -1990,6 +2010,7 @@ __all__ = [
     "ContentControlsDelete",
     "SetSectionColumns",
     "FindReplace",
+    "ClearBody",
     "FindText",
     "IterRuns",
     "ExportPDF",

{athena_python_docx-0.21.8 → athena_python_docx-0.22.0}/docx/document.py

@@ -965,6 +965,7 @@ class Document:
         from docx.commands import CreateTOC
         from docx.toc import TableOfContents
 
+        self._ensure_open()
         cmd = CreateTOC(
             at=at or {"kind": "documentEnd"},
             levels=[levels[0], levels[1]],
@@ -1010,6 +1011,7 @@ class Document:
         from docx.charts import Chart
         from docx.commands import CreateChart
 
+        self._ensure_open()
         cmd = CreateChart(
             chart_type=chart_type,
             data=data,
@@ -1078,6 +1080,7 @@ class Document:
             mime = sniff_content_type(img_bytes, fallback_path=image_path or "")
             kwargs["src"] = f"data:{mime};base64,{base64.b64encode(img_bytes).decode()}"
         cmd = CreateWatermark(**kwargs)
+        self._ensure_open()
         result = run_sync(self._session.send_command(cmd))
         if isinstance(result, dict):
             return str(result.get("id") or result.get("watermarkId") or "")
@@ -1105,6 +1108,7 @@ class Document:
         from docx.commands import CreateContentControl
         from docx.sdt import ContentControl
 
+        self._ensure_open()
         cmd = CreateContentControl(
             control_kind=control_kind,
             at=at or {"kind": "documentEnd"},
@@ -1457,87 +1461,52 @@ class Document:
 
     @athena_extension(
         since="0.14.0",
-        description="Document.clear — empty paragraphs + cells so writes start from a clean slate.",
+        description="Document.clear — reset the body to one empty paragraph in a single server write.",
     )
     def clear(self) -> None:
         """Clear the document body so subsequent writes start from a clean slate.
 
-        Athena extension — python-docx has no equivalent. Empties every
-        top-level paragraph's text content and every table cell's text
-        content. The block structure (paragraphs and tables themselves)
-        is preserved because DOCX Studio does not yet expose a wire op to
-        delete blocks; an agent recovering from a failed run can call
-        ``doc.clear()`` then ``doc.add_paragraph(...)`` etc. without
-        worrying about stale content concatenating onto its new writes.
-
-        Notes / caveats:
-        - The post-clear document holds N empty paragraphs (one per
-          previously-existing block-level paragraph) plus any empty
-          tables. For most agent flows this is invisible because the
-          first ``add_paragraph`` / ``add_heading`` extends the doc
-          rather than overwriting block positions.
-        - To get a TRULY empty body (single empty paragraph, no tables)
-          create a fresh asset via ``Document.create()`` instead.
-        - This method is best-effort: per-paragraph clear errors are
-          swallowed so a partial clear doesn't take down the whole call.
+        Athena extension — python-docx has no equivalent. Replaces the
+        whole body story (paragraphs, headings, tables, images) with a
+        single empty paragraph in one server-side ``ClearBody`` command,
+        so the cost is one round-trip regardless of document size.
+        Headers, footers, footnotes and the final section's page setup
+        are untouched; header/footer references the final section
+        inherited from removed inline sections are kept.
+
+        Export-time rewrites queued against the old body (cell/table
+        formatting, row heights, captured REF paragraphs) are dropped
+        with it, and table numbering restarts from zero, so formatting
+        recorded for a deleted table can never land on one created
+        afterwards at the same position. :class:`~docx.table.Table`
+        proxies obtained before the clear are dead: using one raises
+        :class:`~docx.errors.ValidationError` instead of silently
+        targeting a new table at the same index.
+
+        Raises :class:`~docx.errors.DocxError` if the server rejects the
+        command; the body is never left half-cleared because the whole
+        replacement is applied atomically or not at all, and no local
+        state is touched unless the server accepted it.
         """
-        from docx.text.paragraph import Paragraph as _Paragraph
+        from docx.commands import ClearBody
 
         self._ensure_open()
 
-        # Clear the list-chain state — the next add_paragraph after
-        # clear() should start a new list, not attach to whatever the
-        # previous run was doing.
+        run_sync(
+            self._session.send_command(ClearBody()),
+            timeout=LONG_RUNNING_COMMAND_TIMEOUT_SECONDS,
+        )
+
+        self._session._post_export_ops.discard_body_ops()
+        self._table_doc_index_counter = None
+        self._session._table_session_count = 0  # type: ignore[attr-defined]
+        self._session._body_generation += 1
+
+        # The next add_paragraph after clear() should start a new list,
+        # not attach to whatever the previous run was doing.
         self._last_list_item_id = None
         self._last_list_kind = None
 
-        for paragraph in self.paragraphs:
-            try:
-                if not isinstance(paragraph, _Paragraph):
-                    continue
-                if paragraph.text:
-                    paragraph.clear()
-            except Exception as err:
-                _log_warn(f"Document.clear: skipped a paragraph: {err!r}")
-
-        # Cell clearing must NOT go through ``cell.text = ""``: ``self.tables``
-        # materializes fresh ephemeral ``Table`` proxies whose
-        # ``_written_cells`` set is empty, so the setter would take the
-        # fast (append) path — ``tables.set_cell insideEnd`` with an empty
-        # paragraph fragment — which leaves prior cell content untouched.
-        # Instead, drive ``doc.replace`` directly against each cell's
-        # inner paragraphs (mirroring the clear-then-insert branch in
-        # ``_Cell.text``) so the clear semantics don't depend on the
-        # in-session write tracking that this code path bypasses.
-        from docx.text.paragraph import _node_text
-
-        for table in self.tables:
-            for row in table.rows:
-                for cell in row.cells:
-                    try:
-                        existing_pids = cell._inner_paragraph_ids()
-                        for pid in existing_pids:
-                            existing_text = _node_text(self._session, pid)
-                            if not existing_text:
-                                continue
-                            run_sync(
-                                self._session.doc.replace(
-                                    {
-                                        "target": {
-                                            "kind": "text",
-                                            "blockId": pid,
-                                            "range": {
-                                                "start": 0,
-                                                "end": len(existing_text),
-                                            },
-                                        },
-                                        "text": "",
-                                    },
-                                ),
-                            )
-                    except Exception as err:
-                        _log_warn(f"Document.clear: skipped a cell: {err!r}")
-
     def add_paragraph(
         self,
         text: str = "",