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

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

@@ -349,6 +349,18 @@ Issue numbers reference `python-openxml/python-docx`.
   wontfix upstream but the request keeps recurring. Routes through
   `ExportPDF` (SuperDoc handles the actual conversion).
 
+- **`Document.clear()`** (0.14.0+) — empty the document body so subsequent
+  writes start from a clean slate. python-docx has no equivalent (it
+  operates on local files where the caller can simply construct a new
+  ``Document``). Iterates every top-level paragraph and table cell and
+  empties their text content. Block structure is preserved (SuperDoc has
+  no wire op to delete blocks today), so post-clear the doc holds N
+  empty paragraphs rather than collapsing to a single one — for a truly
+  empty body, call ``Document.create()`` to mint a fresh asset instead.
+  Closes the gap that prompted the 0.14 series' agent-side ``find_replace``
+  cleanup loops, which left horizontal-rule and scratch-content artifacts
+  in the document during failed-run recoveries.
+
 - **`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
@@ -602,6 +614,16 @@ This is a **thin HTTP client** that mimics the sync python-docx API.
   the context-manager exit drain explicitly; `docx.flush_all()` is
   the Daytona-prelude 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
+  reused. Live SDK objects are different. The executor calls
+  `docx.begin_execution(request_id)` at the start of each tool call;
+  `Session` and `CommandBuffer` stamp that id and raise
+  `StaleDocumentHandleError` if a later call tries to reuse old
+  `Document`/paragraph/run/table/cell handles. `docx.flush_all(strict=True)`
+  is the executor path and raises `FlushAllError` for failed flushes or
+  stale pending buffers; plain `docx.flush_all()` keeps the historical
+  log-and-swallow behavior for local scripts.
 - **Insert deferral (0.8.0+):** `Insert` was removed from the
   response-bearing set because every in-tree caller
   (`Paragraph._insert_run_text_segments`, `Run.add_text`, `_Cell.text`)
@@ -650,7 +672,7 @@ This is a **thin HTTP client** that mimics the sync python-docx API.
   follow-up — the wire format is typed end-to-end either way.
 - **Programmatic Tool Calling (PTC):** every `CommandBuffer.call` and
   `flush` emits begin/end events to agora via `docx/_ptc.py` when run
-  inside a Daytona sandbox with `ATHENA_PTC_URL` set. Each method call
+  inside an execution sandbox with `ATHENA_PTC_URL` set. Each method call
   surfaces as a nested sub-tool-card under the parent
   `run_python_code` tool. See
   [`docs/PROGRAMMATIC_TOOL_CALLING_GUIDE.md`](../../docs/PROGRAMMATIC_TOOL_CALLING_GUIDE.md)

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

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

@@ -6,8 +6,9 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.13.0"
+__version__ = "0.15.0"
 
+from docx._execution import begin_execution
 from docx.api import Document
 from docx._buffer import flush_all
 # Re-exports python-docx ships at docx top-level for convenience.
@@ -23,6 +24,7 @@ __all__ = [
     "Twips",
     "Length",
     "RGBColor",
+    "begin_execution",
     "flush_all",
     "__version__",
 ]

{athena_python_docx-0.13.0 → athena_python_docx-0.15.0}/docx/_buffer.py

@@ -34,8 +34,13 @@ import weakref
 from typing import TYPE_CHECKING, Any
 
 from docx import _ptc
+from docx._execution import (
+    assert_current_execution,
+    current_execution_id,
+    is_stale_execution,
+)
 from docx.commands import Command, is_response_bearing, must_flush_immediately
-from docx.errors import DocxError
+from docx.errors import DocxError, FlushAllError
 
 
 def _apply_proxy_id_rewrites(
@@ -172,13 +177,17 @@ def _unregister(buffer: "CommandBuffer") -> None:
         ]
 
 
-def flush_all() -> 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
     buffered mutations make it to Keryx before the sandbox is suspended.
-    Safe to call when no Buffers exist (no-op). Failures are logged and
-    swallowed — we don't want one stuck buffer to mask the rest.
+    Safe to call when no Buffers exist (no-op).
+
+    By default, failures are logged and swallowed for backwards
+    compatibility with existing local scripts. The executor calls
+    ``flush_all(strict=True)`` so failed or stale writes surface as real tool
+    failures instead of being hidden in stderr.
     """
     with _registry_lock:
         snapshot = list(_active_buffers)
@@ -186,16 +195,35 @@ def flush_all() -> None:
         live = [ref for ref in snapshot if ref() is not None]
         _active_buffers[:] = live
 
+    failures: list[str] = []
     for ref in live:
         buf = ref()
         if buf is None:
             continue
+        if buf.is_stale_for_current_execution:
+            pending_count = buf.pending_count
+            if pending_count > 0:
+                msg = (
+                    f"buffer {buf.asset_id} belongs to a previous "
+                    f"execute_word_document_code call and still has "
+                    f"{pending_count} unflushed command(s)"
+                )
+                if strict:
+                    failures.append(msg)
+                else:
+                    sys.stderr.write(f"[docx-sdk] flush_all: {msg}\n")
+            continue
         try:
             buf.flush()
         except Exception as e:  # noqa: BLE001
-            sys.stderr.write(
-                f"[docx-sdk] flush_all: buffer {buf.asset_id} flush failed: {e}\n",
-            )
+            msg = f"buffer {buf.asset_id} flush failed: {e}"
+            if strict:
+                failures.append(msg)
+            else:
+                sys.stderr.write(f"[docx-sdk] flush_all: {msg}\n")
+
+    if failures:
+        raise FlushAllError(failures)
 
 
 # ---------------------------------------------------------------------------
@@ -240,6 +268,7 @@ class CommandBuffer:
         self._timer: threading.Timer | None = None
         self._auto_flush_seconds: float = auto_flush_seconds
         self._closed: bool = False
+        self._execution_id: str | None = current_execution_id()
         # Track-changes envelope state — propagated as request-level
         # ``changeMode`` and ``user`` on every batch. ``Document``
         # mutates these via :meth:`set_change_mode` / :meth:`set_user`,
@@ -263,6 +292,7 @@ class CommandBuffer:
         the per-cmd result for ``real_node_id`` / ``real_entity_id``
         echoes and applies setattr to every registered ref.
         """
+        self._assert_current_execution()
         with self._lock:
             self._proxy_id_refs.setdefault(client_id, []).append((proxy, attr))
 
@@ -275,6 +305,10 @@ class CommandBuffer:
         with self._lock:
             return len(self._pending)
 
+    @property
+    def is_stale_for_current_execution(self) -> bool:
+        return is_stale_execution(self._execution_id)
+
     @property
     def change_mode(self) -> str | None:
         return self._change_mode
@@ -291,6 +325,7 @@ class CommandBuffer:
         retro-actively re-tag earlier mutations. ``mode`` is one of
         ``"direct"``, ``"tracked"``, or ``None`` to clear.
         """
+        self._assert_current_execution()
         if mode is not None and mode not in ("direct", "tracked"):
             raise ValueError(f"change_mode must be 'direct', 'tracked', or None; got {mode!r}")
         with self._lock:
@@ -311,6 +346,7 @@ class CommandBuffer:
         a pooled session ignore the value, but the payload is still
         included so a fresh session picks it up.
         """
+        self._assert_current_execution()
         if name is None:
             with self._lock:
                 self._user = None
@@ -339,6 +375,7 @@ class CommandBuffer:
         ``clientIdMap`` on flush and the buffer rewrites each registered
         proxy's ``_node_id`` in-place.
         """
+        self._assert_current_execution()
         if self._closed:
             raise RuntimeError(
                 f"CommandBuffer for {self._asset_id} is closed",
@@ -397,6 +434,7 @@ class CommandBuffer:
         proxies pick up real ids without the caller ever seeing the
         UUID swap.
         """
+        self._assert_current_execution()
         with self._lock:
             self._cancel_timer_locked()
             pending = self._pending
@@ -436,6 +474,7 @@ class CommandBuffer:
         """Flush and disable. Idempotent."""
         if self._closed:
             return
+        self._assert_current_execution()
         try:
             self.flush()
         finally:
@@ -453,6 +492,7 @@ class CommandBuffer:
         still get their real ids written back via the same flush-time
         rewrite that :meth:`flush` does.
         """
+        self._assert_current_execution()
         with self._lock:
             self._cancel_timer_locked()
             pending = self._pending
@@ -515,5 +555,11 @@ class CommandBuffer:
                 f"[docx-sdk] auto-flush failed for {self._asset_id}: {e}\n",
             )
 
+    def _assert_current_execution(self) -> None:
+        assert_current_execution(
+            self._execution_id,
+            object_name=f"CommandBuffer for {self._asset_id}",
+        )
+
 
 __all__ = ["CommandBuffer", "flush_all", "DEFAULT_AUTO_FLUSH_SECONDS"]

athena_python_docx-0.15.0/docx/_execution.py

@@ -0,0 +1,64 @@
+"""Execution-scope helpers for long-lived sandbox processes.
+
+Document execution sandboxes intentionally keep Python globals alive between
+tool calls so agents can reuse helper functions and imports. Live SDK handles
+are different: a ``Document``/``Paragraph``/``Run`` proxy captures a transport
+session and a snapshot of node ids from the moment it was opened. Reusing that
+proxy in a later tool call can overwrite manual user edits made between calls.
+
+The executor calls :func:`begin_execution` once per tool call. Sessions and
+buffers created after that stamp themselves with the active execution id; any
+later operation under a different id fails before issuing HTTP.
+"""
+
+from __future__ import annotations
+
+from docx.errors import StaleDocumentHandleError
+
+_current_execution_id: str | None = None
+
+
+def begin_execution(execution_id: str | None) -> None:
+    """Mark the start of a logical executor call.
+
+    Passing ``None`` disables stale-handle checks, which keeps local scripts
+    and existing tests behaving like normal in-memory Python programs.
+    """
+    global _current_execution_id
+    _current_execution_id = str(execution_id) if execution_id else None
+
+
+def current_execution_id() -> str | None:
+    """Return the active executor id, if one has been declared."""
+    return _current_execution_id
+
+
+def is_stale_execution(owner_execution_id: str | None) -> bool:
+    """Whether an object stamped with ``owner_execution_id`` is stale."""
+    current = current_execution_id()
+    return current is not None and owner_execution_id != current
+
+
+def assert_current_execution(
+    owner_execution_id: str | None,
+    *,
+    object_name: str,
+) -> None:
+    """Raise if an SDK object belongs to a prior executor call."""
+    if not is_stale_execution(owner_execution_id):
+        return
+    raise StaleDocumentHandleError(
+        f"{object_name} belongs to a previous execute_word_document_code call. "
+        "Reopen the document inside the current tool call with "
+        "Document('asset_xxx') and pass that fresh Document into reusable "
+        "helper functions. Imports, constants, and function definitions can "
+        "still persist across calls."
+    )
+
+
+__all__ = [
+    "assert_current_execution",
+    "begin_execution",
+    "current_execution_id",
+    "is_stale_execution",
+]

{athena_python_docx-0.13.0 → athena_python_docx-0.15.0}/docx/_http.py

@@ -100,17 +100,24 @@ def create_empty_document(
         DocxError: any other 4xx/5xx from the server.
     """
     resolved_base: str | None = base_url or os.environ.get(_BASE_URL_ENV)
-    resolved_key: str | None = api_key or os.environ.get(_API_KEY_ENV)
+    # api_key falls back to ATHENA_API_KEY (the canonical Athena user API
+    # key) so code running in sandboxes that only inject ATHENA_API_KEY
+    # still authenticates without an extra env var.
+    resolved_key: str | None = (
+        api_key or os.environ.get(_API_KEY_ENV) or os.environ.get("ATHENA_API_KEY")
+    )
 
     if not resolved_base:
         raise SessionError(
             f"Missing base_url and {_BASE_URL_ENV} env var. "
-            "Pass base_url= to Document.create() or set the env var.",
+            "Pass base_url= to Document.create() or set the env var "
+            '(e.g. ATHENA_DOCX_BASE_URL="https://docx-studio.prd.athenaintel.com").',
         )
     if not resolved_key:
         raise AuthenticationError(
             f"Missing api_key and {_API_KEY_ENV} env var. "
-            "Pass api_key= to Document.create() or set the env var.",
+            "Pass api_key= to Document.create() or set the env var "
+            "(or set ATHENA_API_KEY as a fallback).",
         )
 
     url: str = resolved_base.rstrip("/") + "/docs/empty"
@@ -256,7 +263,12 @@ def upload_document(
     import uuid
 
     resolved_docx_base: str | None = docx_base_url or os.environ.get(_BASE_URL_ENV)
-    resolved_key: str | None = api_key or os.environ.get(_API_KEY_ENV)
+    # api_key falls back to ATHENA_API_KEY (the canonical Athena user API
+    # key) so code running in sandboxes that only inject ATHENA_API_KEY
+    # still authenticates without an extra env var.
+    resolved_key: str | None = (
+        api_key or os.environ.get(_API_KEY_ENV) or os.environ.get("ATHENA_API_KEY")
+    )
     resolved_agora_base: str | None = (
         agora_base_url
         or os.environ.get(_AGORA_BASE_URL_ENV)
@@ -273,7 +285,8 @@ def upload_document(
     if not resolved_key:
         raise AuthenticationError(
             f"Missing api_key and {_API_KEY_ENV} env var. "
-            "Pass api_key= to Document.create() or set the env var.",
+            "Pass api_key= to Document.create() or set the env var "
+            "(or set ATHENA_API_KEY as a fallback).",
         )
 
     if not os.path.exists(docx_path):
@@ -297,9 +310,7 @@ def upload_document(
         qs["parent_folder_id"] = parent_folder_id
 
     url: str = (
-        resolved_agora_base.rstrip("/")
-        + "/api/super-docs/create-from-upload?"
-        + urlencode(qs)
+        resolved_agora_base.rstrip("/") + "/api/super-docs/create-from-upload?" + urlencode(qs)
     )
 
     # Build a minimal multipart/form-data body without pulling in

{athena_python_docx-0.13.0 → athena_python_docx-0.15.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",
@@ -821,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,
@@ -851,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