athena-python-docx 0.5.1__tar.gz → 0.5.3__tar.gz

{athena_python_docx-0.5.1 → athena_python_docx-0.5.3}/CLAUDE.md

@@ -76,6 +76,44 @@ not file-backed. Each is documented in the relevant docstring.
   hits `POST {base_url}/docs/empty`. The constructor positional-arg
   shape (`Document(asset_id)`) is preserved for parity.
 
+- **`Document.save(path_or_stream=None)`** — argument is optional.
+  Stock python-docx requires it and `TypeError`s on no-arg, but in an
+  asset-backed SDK there is no local file to write — writes are always
+  in-place against the Y.Doc. Forcing the upstream signature broke
+  every agent invocation that reflexively called `doc.save()` (a
+  near-universal Python pattern), so we accept it for parity-friendly
+  call sites and ignore the value at runtime.
+
+- **`Document.track_revisions: bool`** — when `True`, all subsequent
+  mutations are recorded as tracked revisions instead of direct edits.
+  python-docx upstream has no top-level toggle (the closest is
+  hand-edited `<w:trackChanges/>` on `Document.settings.element`).
+  We expose this as a Document-level property because every SuperDoc
+  mutation accepts a per-call `changeMode` envelope field. The
+  python-docx-parity alias `Document.settings.track_revisions` reads
+  and writes the same flag so call sites that walk `doc.settings`
+  see consistent state.
+
+- **`Document.tracked_revisions()` context manager** — scope
+  `track_revisions=True` to a `with` block; restores the previous
+  value on exit (even on exception). Block-scoped track-changes is a
+  Pythonic ergonomic that doesn't exist in upstream python-docx
+  because the upstream package has no track-changes API at all.
+
+- **`Document.user_name: str | None` / `Document.user_email: str |
+  None`** — author identity threaded through to SuperDoc on session-
+  open for tracked-change attribution. python-docx's
+  `Document.core_properties.last_modified_by` is the closest upstream
+  surface; we use the SuperDoc-native fields directly because SuperDoc
+  bakes them into the change records.
+
+- **`Document.revisions: Revisions`** — collection of tracked changes
+  with iteration, `get(id)`, `accept_all()`, `reject_all()`,
+  `accept(id)`, `reject(id)`. Per-revision `Revision.accept()` /
+  `Revision.reject()` resolve a single change. python-docx upstream
+  has zero track-changes API, so this entire surface is an Athena
+  extension wired to SuperDoc's `doc.trackChanges.{list,get,decide}`.
+
 ### If you need a deviation
 
 If there is a genuine technical reason why a deviation from python-docx is necessary:
@@ -107,6 +145,13 @@ This is a **thin HTTP client** that mimics the sync python-docx API.
   resolve to `CommandBuffer.call(CreateParagraph(**p))`. Rewriting call
   sites to construct `Command` dataclasses directly is a possible
   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
+  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)
+  at the monorepo root.
 
 ## Development
 

{athena_python_docx-0.5.1 → athena_python_docx-0.5.3}/PKG-INFO

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

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

athena_python_docx-0.5.3/docx/_buffer.py

@@ -0,0 +1,503 @@
+"""HTTP command buffer for the docx-studio SDK.
+
+The buffer sits between SDK call sites and the HTTP transport. Every SDK
+mutation routes through it; we flush eagerly for queries and response-bearing
+ops (creates), and idle-batch pure mutations so a burst of setters becomes
+one HTTP request instead of N.
+
+Concurrency model: the SDK serializes calls through ``_batching.run_sync``
+(one persistent event-loop thread), so the buffer's primary thread is the
+loop thread. The auto-flush timer fires on a *different* thread, so we
+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
+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.
+"""
+
+from __future__ import annotations
+
+import sys
+import threading
+import weakref
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, Generator
+
+from docx import _ptc
+from docx.commands import Command, must_flush_immediately
+
+if TYPE_CHECKING:
+    from docx._http_doc import HttpClient
+
+
+def _ptc_emit_end_batch(cmds: list[Command], *, is_error: bool) -> None:
+    """Emit a PTC ``end`` event for every cmd that received a ``begin``.
+
+    Tolerant: missing call_ids (cmd was added before PTC env was set) and
+    PTC client exceptions both silently no-op.
+    """
+    for c in cmds:
+        call_id = getattr(c, "_ptc_call_id", None)
+        if not call_id:
+            continue
+        try:
+            _ptc.emit_end(
+                call_id=call_id,
+                tool_name=type(c).__name__,
+                result={"ok": not is_error}
+                if not is_error
+                else {"ok": False, "error": "command batch failed"},
+                is_error=is_error,
+            )
+        except Exception:  # noqa: BLE001
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Process-wide registry for flush_all()
+# ---------------------------------------------------------------------------
+
+_active_buffers: list[weakref.ref["CommandBuffer"]] = []
+_registry_lock = threading.Lock()
+
+
+def _register(buffer: "CommandBuffer") -> None:
+    with _registry_lock:
+        _active_buffers.append(weakref.ref(buffer))
+
+
+def _unregister(buffer: "CommandBuffer") -> None:
+    """Drop ``buffer`` from the active-registry list.
+
+    Called from :meth:`CommandBuffer.close` so a long-lived process that
+    opens and closes many Documents doesn't accumulate dead weak-refs in
+    the registry between ``flush_all`` calls.
+    """
+    with _registry_lock:
+        _active_buffers[:] = [
+            ref
+            for ref in _active_buffers
+            if (b := ref()) is not None and b is not buffer
+        ]
+
+
+def flush_all() -> 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.
+    """
+    with _registry_lock:
+        snapshot = list(_active_buffers)
+        # Compact dead refs while we hold the lock.
+        live = [ref for ref in snapshot if ref() is not None]
+        _active_buffers[:] = live
+
+    for ref in live:
+        buf = ref()
+        if buf is None:
+            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",
+            )
+
+
+# ---------------------------------------------------------------------------
+# CommandBuffer
+# ---------------------------------------------------------------------------
+
+# Idle window before a pure-mutation buffer auto-flushes. Short by design —
+# the SDK's main consumer is agent code that fires sequential property
+# setters within milliseconds of each other; we just need to coalesce those
+# without holding writes back from Keryx for human-perceptible time.
+DEFAULT_AUTO_FLUSH_SECONDS: float = 0.1
+
+
+class CommandBuffer:
+    """Buffers commands for one Document/asset.
+
+    Behaviour:
+    - Queries and response-bearing mutations (creates, inserts that return
+      ids) flush immediately. Pending pure mutations are flushed in the
+      same batch so ordering is preserved.
+    - Pure mutations (formatters, setters) are queued. An idle timer flushes
+      them after :data:`DEFAULT_AUTO_FLUSH_SECONDS` of inactivity, OR on
+      the next eager call, OR on explicit ``flush()``.
+    """
+
+    def __init__(
+        self,
+        client: "HttpClient",
+        asset_id: str,
+        *,
+        auto_flush_seconds: float = DEFAULT_AUTO_FLUSH_SECONDS,
+    ) -> None:
+        self._client: "HttpClient" = client
+        self._asset_id: str = asset_id
+        self._pending: list[Command] = []
+        self._lock: threading.RLock = threading.RLock()
+        self._timer: threading.Timer | None = None
+        self._auto_flush_seconds: float = auto_flush_seconds
+        self._closed: bool = False
+        # 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`,
+        # which flush before changing so prior buffered ops keep their
+        # original semantics.
+        self._change_mode: str | None = None
+        self._user: dict[str, str] | None = None
+        # Batch mode flag — when True, Create* commands buffer instead
+        # of flushing immediately, and proxies bind to a client-side
+        # UUID instead of waiting for the server response. See
+        # :meth:`Document.batch` and ``PERFORMANCE_BATCHING_ANALYSIS.md``.
+        self._batch_depth: int = 0
+        # client_node_id → list of (proxy, attr) pairs to update with the
+        # real nodeId after flush. Populated by ``add_paragraph`` /
+        # ``add_heading`` / etc. when they queue a Create with a
+        # client-assigned id. Drained on every flush.
+        self._proxy_id_refs: dict[
+            str, list[tuple[object, str]]
+        ] = {}
+        _register(self)
+
+    @property
+    def is_batching(self) -> bool:
+        """``True`` if a ``with doc.batch():`` block is currently open.
+
+        SDK call sites read this to decide whether to defer Create*
+        commands or eager-flush them. Reentrant — nested ``batch()``
+        blocks increment the counter and decrement on exit; the outer
+        block is what actually flushes.
+        """
+        return self._batch_depth > 0
+
+    def register_proxy_id_ref(
+        self, client_id: str, proxy: object, attr: str = "_node_id"
+    ) -> None:
+        """Register that ``proxy.<attr>`` should be rewritten from
+        ``client_id`` to the real node id once the current batch flushes.
+
+        Called by ``Document.add_paragraph`` (and equivalents) when they
+        queue a Create with a ``client_node_id``. The flush loop walks
+        the per-cmd result for ``real_node_id`` / ``real_entity_id``
+        echoes and applies setattr to every registered ref.
+        """
+        with self._lock:
+            self._proxy_id_refs.setdefault(client_id, []).append((proxy, attr))
+
+    @property
+    def asset_id(self) -> str:
+        return self._asset_id
+
+    @property
+    def pending_count(self) -> int:
+        with self._lock:
+            return len(self._pending)
+
+    @property
+    def change_mode(self) -> str | None:
+        return self._change_mode
+
+    @property
+    def user(self) -> "dict[str, str] | None":
+        return None if self._user is None else dict(self._user)
+
+    def set_change_mode(self, mode: str | None) -> None:
+        """Set the batch-level change mode and flush prior pending ops.
+
+        Flushing first means commands queued under the previous mode
+        retain those semantics — switching modes mid-stream doesn't
+        retro-actively re-tag earlier mutations. ``mode`` is one of
+        ``"direct"``, ``"tracked"``, or ``None`` to clear.
+        """
+        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:
+            current = self._change_mode
+        if current == mode:
+            return
+        # Drain any queued commands with the *previous* mode before
+        # adopting the new one.
+        self.flush()
+        with self._lock:
+            self._change_mode = mode
+
+    def set_user(self, name: str | None, email: str | None = None) -> None:
+        """Set the batch-level user identity.
+
+        Sent on every commands request envelope. SuperDoc honors the
+        identity at session-open time only — subsequent batches against
+        a pooled session ignore the value, but the payload is still
+        included so a fresh session picks it up.
+        """
+        if name is None:
+            with self._lock:
+                self._user = None
+            return
+        if not name:
+            raise ValueError("user name must be a non-empty string")
+        with self._lock:
+            self._user = {"name": name}
+            if email:
+                self._user["email"] = email
+
+    def call(self, cmd: Command) -> Any:
+        """Execute or buffer ``cmd``.
+
+        For eager commands (queries, response-bearing creates), drains
+        the pending queue and runs ``cmd`` in the same batch; returns
+        the per-cmd result dict.
+
+        For pure mutations, appends to the queue, resets the idle timer,
+        and returns ``None``. The caller MUST NOT rely on the return
+        value of a buffered mutation — it's not available until flush.
+
+        **Batch mode:** when ``self.is_batching`` is True AND the command
+        carries a non-None ``client_node_id`` / ``client_entity_id``
+        (Create*, CommentsCreate), the command is buffered rather than
+        eager-flushed. The caller is expected to have pre-stamped a
+        proxy with the client-side id; after the batch flushes, the
+        applier's ``real_node_id`` / ``real_entity_id`` echo lets the
+        SDK rewrite the proxy in-place.
+        """
+        if self._closed:
+            raise RuntimeError(
+                f"CommandBuffer for {self._asset_id} is closed",
+            )
+
+        # PTC begin: one event per user-facing method call, before any
+        # batching. Failures here can't crash the user's code path.
+        try:
+            cmd._ptc_call_id = _ptc.emit_begin(type(cmd).__name__, cmd.to_dict())  # type: ignore[attr-defined]
+        except Exception:  # noqa: BLE001
+            pass
+
+        if must_flush_immediately(cmd) and not self._is_batched_create(cmd):
+            return self._eager_flush_with(cmd)
+
+        with self._lock:
+            self._pending.append(cmd)
+            self._reset_timer_locked()
+        return None
+
+    def _is_batched_create(self, cmd: Command) -> bool:
+        """Return True iff this command can be safely deferred because
+        the caller pre-assigned a client-side id and the buffer is in
+        batch mode.
+
+        We only defer Create-shape commands (those with
+        ``client_node_id`` / ``client_entity_id`` set). Pure queries
+        like ``BlocksList`` must still eager-flush — the caller is
+        awaiting their data. Read-bearing creates without a client id
+        (legacy callers / non-batch path) also stay eager so we don't
+        change their semantics.
+        """
+        if not self.is_batching:
+            return False
+        cli_node = getattr(cmd, "client_node_id", None)
+        cli_ent = getattr(cmd, "client_entity_id", None)
+        return cli_node is not None or cli_ent is not None
+
+    def flush(self) -> list[Any]:
+        """Flush pending commands as one HTTP batch.
+
+        Returns the list of per-command result dicts. Empty list if nothing
+        was pending. Cancels any active idle timer.
+
+        After the batch returns, walks per-cmd results for
+        ``real_node_id`` / ``real_entity_id`` echoes and updates any
+        proxies registered via :meth:`register_proxy_id_ref` with the
+        resolved server ids. This is what completes the round-trip for
+        ``with doc.batch():`` — the SDK's caller-facing proxies pick up
+        real ids transparently after the block exits.
+        """
+        with self._lock:
+            self._cancel_timer_locked()
+            pending = self._pending
+            self._pending = []
+            change_mode = self._change_mode
+            user = None if self._user is None else dict(self._user)
+            proxy_id_refs = self._proxy_id_refs
+            self._proxy_id_refs = {}
+        if not pending:
+            return []
+        try:
+            results = self._client.execute_batch(
+                self._asset_id,
+                pending,
+                change_mode=change_mode,
+                user=user,
+            )
+        except Exception:
+            _ptc_emit_end_batch(pending, is_error=True)
+            raise
+        _ptc_emit_end_batch(pending, is_error=False)
+        # Rewrite registered proxies from client-side UUIDs to the real
+        # SuperDoc ids the applier echoed back. Defensive: tolerate
+        # missing fields (legacy or transitional applier without the
+        # client-id support).
+        if proxy_id_refs:
+            for result in results:
+                if not isinstance(result, dict):
+                    continue
+                for cli_key, real_key in (
+                    ("client_node_id", "real_node_id"),
+                    ("client_entity_id", "real_entity_id"),
+                ):
+                    cli = result.get(cli_key)
+                    real = result.get(real_key)
+                    if not (isinstance(cli, str) and isinstance(real, str)):
+                        continue
+                    refs = proxy_id_refs.pop(cli, [])
+                    for proxy, attr in refs:
+                        try:
+                            setattr(proxy, attr, real)
+                        except Exception:  # noqa: BLE001
+                            # A proxy that rejected setattr (slots without
+                            # the attr, frozen dataclass, etc.) silently
+                            # keeps its client_id — the rewriter in the
+                            # applier will still resolve it correctly
+                            # for the next batch.
+                            pass
+        return results
+
+    @contextmanager
+    def batch(self) -> Generator[None, None, None]:
+        """Group calls into one HTTP batch.
+
+        Inside the ``with`` block:
+
+        - Queries (``BlocksList``, ``Find``, ``GetNodeById``, …) still
+          eager-flush — the caller is awaiting their result, so we have
+          no choice.
+        - Pure mutations (formatters, setters) accumulate without their
+          idle timer firing.
+        - Create*-shape commands that carry a ``client_node_id`` /
+          ``client_entity_id`` (set by ``Document.add_paragraph`` and
+          friends when they detect batch mode) also accumulate — the
+          server resolves the client UUIDs to real SuperDoc ids in a
+          single batch via the per-request ``clientIdMap``.
+
+        On exit, drains anything left. Reentrant: nested ``batch()``
+        blocks share the same accumulating queue; only the outermost
+        block flushes.
+        """
+        with self._lock:
+            self._cancel_timer_locked()
+            old_window = self._auto_flush_seconds
+            self._auto_flush_seconds = 0.0  # disable timer-scheduled flush
+            self._batch_depth += 1
+        try:
+            yield
+        finally:
+            with self._lock:
+                self._batch_depth -= 1
+                outermost = self._batch_depth == 0
+                if outermost:
+                    self._auto_flush_seconds = old_window
+            if outermost:
+                self.flush()
+
+    def close(self) -> None:
+        """Flush and disable. Idempotent."""
+        if self._closed:
+            return
+        try:
+            self.flush()
+        finally:
+            self._closed = True
+            _unregister(self)
+
+    # ----- internals -----
+
+    def _eager_flush_with(self, cmd: Command) -> Any:
+        """Drain pending + run ``cmd`` in one batch; return cmd's result.
+
+        When pending commands include batched Creates with registered
+        proxy refs (e.g. a query mid-batch triggers an eager flush
+        before the ``with doc.batch():`` block ends), the proxies still
+        get their real ids written back via the same flush-time rewrite
+        that :meth:`flush` does.
+        """
+        with self._lock:
+            self._cancel_timer_locked()
+            pending = self._pending
+            self._pending = []
+            change_mode = self._change_mode
+            user = None if self._user is None else dict(self._user)
+            proxy_id_refs = self._proxy_id_refs
+            self._proxy_id_refs = {}
+        all_cmds: list[Command] = [*pending, cmd]
+        try:
+            results: list[Any] = self._client.execute_batch(
+                self._asset_id,
+                all_cmds,
+                change_mode=change_mode,
+                user=user,
+            )
+        except Exception:
+            _ptc_emit_end_batch(all_cmds, is_error=True)
+            raise
+        _ptc_emit_end_batch(all_cmds, is_error=False)
+        # Apply the same proxy-rewrite pass as ``flush()`` — see comment
+        # there for the contract.
+        if proxy_id_refs:
+            for result in results:
+                if not isinstance(result, dict):
+                    continue
+                for cli_key, real_key in (
+                    ("client_node_id", "real_node_id"),
+                    ("client_entity_id", "real_entity_id"),
+                ):
+                    cli = result.get(cli_key)
+                    real = result.get(real_key)
+                    if not (isinstance(cli, str) and isinstance(real, str)):
+                        continue
+                    refs = proxy_id_refs.pop(cli, [])
+                    for proxy, attr in refs:
+                        try:
+                            setattr(proxy, attr, real)
+                        except Exception:  # noqa: BLE001
+                            pass
+        if not results:
+            return {}
+        return results[-1]
+
+    def _reset_timer_locked(self) -> None:
+        # Caller must hold self._lock.
+        self._cancel_timer_locked()
+        if self._auto_flush_seconds <= 0:
+            return  # disabled (e.g. inside batch())
+        self._timer = threading.Timer(
+            self._auto_flush_seconds,
+            self._auto_flush,
+        )
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _cancel_timer_locked(self) -> None:
+        # Caller must hold self._lock.
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+
+    def _auto_flush(self) -> None:
+        try:
+            self.flush()
+        except Exception as e:  # noqa: BLE001
+            sys.stderr.write(
+                f"[docx-sdk] auto-flush failed for {self._asset_id}: {e}\n",
+            )
+
+
+__all__ = ["CommandBuffer", "flush_all", "DEFAULT_AUTO_FLUSH_SECONDS"]