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

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

@@ -34,6 +34,35 @@ These standard python-docx members don't apply to a Superdoc-backed SDK:
 - `Document.core_properties.last_modified_by` — we use Keryx attribution instead
 - `Document.settings` — Word app settings (not surfaced by Superdoc)
 - `InlineShape.chart` — charts (Phase 2+)
+- `Comment.add_paragraph` / `Comment.add_table` /
+  `Comment.iter_inner_content` / `Comment.paragraphs` /
+  `Comment.tables` — SuperDoc models a comment as a single text body,
+  not a `BlockItemContainer`. Use `Comment.text` instead. The
+  paragraph/table-bearing surface raises `CommentsNotImplementedError`.
+
+### Phase-3b upstream-blocked surface
+
+These are *shipped at the surface* but partially or fully no-op at
+runtime, pending SuperDoc SDK changes outside this repo. The
+upstream constraints have been verified against
+[SuperDoc's published docs](https://docs.superdoc.dev/document-api/reference/styles/apply)
+and the bundled TypeScript types in
+`node_modules/@superdoc-dev/sdk/dist/generated/client.d.ts`. See
+`docx-studio/PYTHON_DOCX_PARITY_GAPS.md` § *What unblocks the
+remaining work* for the exact wire-op shape needed to unblock each.
+
+- **24 setters on `BaseStyle` / `CharacterStyle` / `ParagraphStyle`**
+  (`name`, `style_id`, `hidden`, `locked`, `priority`, `quick_style`,
+  `unhide_when_used`, `base_style`, `next_paragraph_style`) emit
+  `PendingStyleMutationWarning` and stash on `_overrides`.
+  SuperDoc 1.7's `doc.styles.apply` is constrained to
+  `target.scope: "docDefaults"` — no per-style metadata variant.
+  Behavior pinned by `tests/test_style_setters_contract.py` (11
+  tests); when SuperDoc lands a metadata op, those tests will need
+  to flip to assert real bus calls.
+- **`Styles.latent_styles`** returns an empty `_LatentStyles` —
+  `DocInfoResult.styles` only surfaces `paragraphStyles[]` (a flat
+  usage-count list), not the OOXML `<w:latentStyles>` block.
 
 ### Intentional deviations (additions / different semantics)
 
@@ -56,14 +85,28 @@ If there is a genuine technical reason why a deviation from python-docx is neces
 3. Get explicit confirmation that the deviation is acceptable
 4. Document the deviation in the "Intentionally omitted" list above
 
-## Architecture
+## Architecture (0.5.0+)
 
-This is an **async-Superdoc-SDK-backed client** that mimics the sync python-docx API.
+This is a **thin HTTP client** that mimics the sync python-docx API.
 
 - Sync façade (matches python-docx) — `doc.save()`, `paragraph.add_run()`
-- Under the hood, a persistent event-loop thread in `_batching.py` runs `AsyncSuperDocClient` coroutines
-- No XML manipulation — calls translate to Superdoc SDK ops (insert, find, replace, tables.*, format.apply, create.image, hyperlinks.wrap)
-- Mutations write directly to Keryx Y.Doc; users and other agents see them live
+- Every internal call constructs a typed `Command` dataclass
+  (`docx.commands`) and ships it through a `CommandBuffer`
+  (`docx._buffer`) which POSTs to docx-studio's `/docs/:id/commands`.
+- HTTP transport: `requests.Session` with a Retry (3 attempts, 0.5s
+  backoff, 429/502/503/504). The legacy `transport="direct"` (embedded
+  Superdoc CLI + y-websocket from Python) was removed in 0.5.0; agent
+  pods no longer embed Superdoc.
+- Batching: queries and response-bearing creates flush eagerly (and
+  drain pending pure mutations in the same batch); pure mutations
+  buffer with a 100 ms idle timer. `Document.save()` and the context
+  manager exit drain explicitly. `docx.flush_all()` is the Daytona
+  prelude hook — flushes every live buffer in the process.
+- The path-proxy in `_http_doc.py` is an internal translation layer:
+  call sites that look like `await self._session.doc.create.paragraph(p)`
+  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.
 
 ## Development
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.4.0
+Version: 0.5.1
 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>
@@ -11,14 +11,18 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.11
-Requires-Dist: httpx>=0.27
-Requires-Dist: superdoc-sdk>=1.6.0.dev6
+Requires-Dist: requests>=2.28
+Requires-Dist: urllib3>=1.26.6
 Provides-Extra: dev
 Requires-Dist: mypy>=1.8; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: python-docx>=1.1; extra == 'dev'
+Requires-Dist: responses>=0.24; extra == 'dev'
 Requires-Dist: ruff>=0.3; extra == 'dev'
+Provides-Extra: fidelity
+Requires-Dist: httpx>=0.27; extra == 'fidelity'
+Requires-Dist: superdoc-sdk>=1.8.0; extra == 'fidelity'
 Description-Content-Type: text/markdown
 
 # athena-python-docx

{athena_python_docx-0.4.0 → athena_python_docx-0.5.1}/docx/__init__.py

@@ -6,9 +6,10 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.4.0"
+__version__ = "0.5.1"
 
 from docx.api import Document
+from docx._buffer import flush_all
 # Re-exports python-docx ships at docx top-level for convenience.
 from docx.shared import Emu, Inches, Pt, Cm, Mm, Twips, Length, RGBColor
 
@@ -22,5 +23,6 @@ __all__ = [
     "Twips",
     "Length",
     "RGBColor",
+    "flush_all",
     "__version__",
 ]

athena_python_docx-0.5.1/docx/_buffer.py

@@ -0,0 +1,248 @@
+"""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.commands import Command, must_flush_immediately
+
+if TYPE_CHECKING:
+    from docx._http_doc import HttpClient
+
+
+# ---------------------------------------------------------------------------
+# 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
+        _register(self)
+
+    @property
+    def asset_id(self) -> str:
+        return self._asset_id
+
+    @property
+    def pending_count(self) -> int:
+        with self._lock:
+            return len(self._pending)
+
+    def call(self, cmd: Command) -> Any:
+        """Execute or buffer ``cmd``.
+
+        For eager commands (queries, 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.
+        """
+        if self._closed:
+            raise RuntimeError(
+                f"CommandBuffer for {self._asset_id} is closed",
+            )
+
+        if must_flush_immediately(cmd):
+            return self._eager_flush_with(cmd)
+
+        with self._lock:
+            self._pending.append(cmd)
+            self._reset_timer_locked()
+        return 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.
+        """
+        with self._lock:
+            self._cancel_timer_locked()
+            pending = self._pending
+            self._pending = []
+        if not pending:
+            return []
+        return self._client.execute_batch(self._asset_id, pending)
+
+    @contextmanager
+    def batch(self) -> Generator[None, None, None]:
+        """Group calls into one HTTP batch.
+
+        Inside the ``with`` block, eager commands still flush immediately
+        (we can't buffer reads — the caller is awaiting their result), but
+        pure mutations accumulate without their idle timer firing.
+        On exit, drains anything left.
+        """
+        # Cancel the idle timer for the duration of the block; we'll flush
+        # explicitly on exit. New adds inside the block go straight onto
+        # _pending without rescheduling the timer.
+        with self._lock:
+            self._cancel_timer_locked()
+            old_window = self._auto_flush_seconds
+            self._auto_flush_seconds = 0.0  # disable scheduling
+        try:
+            yield
+        finally:
+            with self._lock:
+                self._auto_flush_seconds = old_window
+            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."""
+        with self._lock:
+            self._cancel_timer_locked()
+            pending = self._pending
+            self._pending = []
+        all_cmds: list[Command] = [*pending, cmd]
+        results: list[Any] = self._client.execute_batch(self._asset_id, all_cmds)
+        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"]