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

{athena_python_docx-0.14.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.14.0 → athena_python_docx-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.14.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.14.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.14.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.14.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.14.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.14.0 → athena_python_docx-0.15.0}/docx/client.py

@@ -22,6 +22,7 @@ import os
 from contextlib import asynccontextmanager
 from typing import TYPE_CHECKING, Any
 
+from docx._execution import assert_current_execution, current_execution_id
 from docx.errors import (
     AuthenticationError,
     DocumentClosedError,
@@ -80,6 +81,7 @@ class Session:
         self._doc_handle: Any | None = None
         self._opened: bool = False
         self._closed: bool = False
+        self._execution_id: str | None = current_execution_id()
         # Collector for post-export OOXML rewrites (cell-inner format
         # ops + REF-field restorations + future Tier-B fidelity fixes).
         # Lives here so every proxy that reaches the session can stash;
@@ -109,6 +111,7 @@ class Session:
             AuthenticationError: missing or invalid api_key.
             SessionError: missing base_url or downstream open failure.
         """
+        self._assert_current_execution()
         if self._closed:
             raise DocumentClosedError(
                 f"Session for asset {self._asset_id} was already closed.",
@@ -121,18 +124,25 @@ class Session:
         base_url: str | None = self._http_base_url or os.environ.get(
             "ATHENA_DOCX_BASE_URL",
         )
-        api_key: str | None = self._http_api_key or os.environ.get(
-            "ATHENA_DOCX_API_KEY",
+        # 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.
+        api_key: str | None = (
+            self._http_api_key
+            or os.environ.get("ATHENA_DOCX_API_KEY")
+            or os.environ.get("ATHENA_API_KEY")
         )
         if not base_url:
             raise SessionError(
                 "Missing base_url. Pass base_url= to Document(...) or set "
-                "ATHENA_DOCX_BASE_URL.",
+                "the ATHENA_DOCX_BASE_URL environment variable (e.g. "
+                '"https://docx-studio.prd.athenaintel.com").',
             )
         if not api_key:
             raise AuthenticationError(
                 "Missing api_key. Pass api_key= to Document(...) or set "
-                "ATHENA_DOCX_API_KEY.",
+                "ATHENA_DOCX_API_KEY (or ATHENA_API_KEY as a fallback) in "
+                "the environment.",
             )
         client = HttpClient(base_url=base_url, api_key=api_key)
         self._client = client
@@ -143,6 +153,7 @@ class Session:
     @property
     def doc(self) -> Any:
         """Return the opened doc handle (the path-proxy entry point)."""
+        self._assert_current_execution()
         if not self._opened:
             raise SessionError(
                 "Session not yet opened; call await session.open() first "
@@ -170,6 +181,7 @@ class Session:
         call shape that the rest of the SDK uses; in practice every
         SDK call site wraps this in :func:`docx._batching.run_sync`.
         """
+        self._assert_current_execution()
         if not self._opened:
             raise SessionError(
                 "Session not yet opened; call await session.open() first "
@@ -194,6 +206,7 @@ class Session:
         ``in_place`` is accepted for back-compat with the legacy direct
         transport; writes are always against the asset's Y.Doc.
         """
+        self._assert_current_execution()
         if not self._opened:
             raise SessionError("Cannot save a session that was never opened.")
         if self._closed:
@@ -209,6 +222,7 @@ class Session:
         """Close the session. Idempotent."""
         if self._closed:
             return
+        self._assert_current_execution()
 
         handle = self._doc_handle
         buffer = getattr(handle, "buffer", None) if handle is not None else None
@@ -234,6 +248,12 @@ class Session:
         self._closed = True
         _log_info(f"Closed {self._asset_id}")
 
+    def _assert_current_execution(self) -> None:
+        assert_current_execution(
+            self._execution_id,
+            object_name=f"Document session for {self._asset_id}",
+        )
+
 
 @asynccontextmanager
 async def open_session(

{athena_python_docx-0.14.0 → athena_python_docx-0.15.0}/docx/document.py

@@ -1246,6 +1246,89 @@ class Document:
         # \r\n → \n\n (preserves paragraph-break semantics)
         return text.replace("\r\n", "\n\n").replace("\r", "\n")
 
+    @athena_extension(
+        since="0.14.0",
+        description="Document.clear — empty paragraphs + cells so writes start from a clean slate.",
+    )
+    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 SuperDoc 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.
+        """
+        from docx.text.paragraph import Paragraph as _Paragraph
+
+        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.
+        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 = "",

{athena_python_docx-0.14.0 → athena_python_docx-0.15.0}/docx/errors.py

@@ -111,6 +111,19 @@ class DocumentClosedError(DocxError):
     """Raised when operating on a closed Document."""
 
 
+class StaleDocumentHandleError(DocxError):
+    """Raised when an SDK proxy from an earlier executor call is reused."""
+
+
+class FlushAllError(DocxError):
+    """Raised by ``docx.flush_all(strict=True)`` when any live buffer fails."""
+
+    def __init__(self, failures: list[str]) -> None:
+        self.failures: list[str] = list(failures)
+        detail = "; ".join(self.failures)
+        super().__init__(f"docx.flush_all() failed: {detail}")
+
+
 class LocalSaveTargetNotSupportedError(DocxError, NotImplementedError):
     """Raised when ``Document.save(path_or_stream=...)`` is called with a
     non-None argument.