athena-python-docx 0.15.3__tar.gz → 0.15.5__tar.gz

{athena_python_docx-0.15.3 → athena_python_docx-0.15.5}/PKG-INFO

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

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

{athena_python_docx-0.15.3 → athena_python_docx-0.15.5}/docx/_buffer.py

@@ -21,9 +21,9 @@ 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.
+make sure pending writes hit Keryx and server-side edit sessions are
+checkpointed before the sandbox is suspended. It walks a weak-ref registry
+so dead Document instances don't keep their buffers alive.
 """
 
 from __future__ import annotations
@@ -180,11 +180,12 @@ def _unregister(buffer: "CommandBuffer") -> None:
 
 
 def flush_all(*, strict: bool = False) -> None:
-    """Flush every live CommandBuffer in this process.
+    """Flush and checkpoint 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).
+    buffered mutations make it to Keryx and server-side edit sessions are
+    durably released before the sandbox is suspended. 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
@@ -216,9 +217,9 @@ def flush_all(*, strict: bool = False) -> None:
                     sys.stderr.write(f"[docx-sdk] flush_all: {msg}\n")
             continue
         try:
-            buf.flush()
+            buf.commit()
         except Exception as e:  # noqa: BLE001
-            msg = f"buffer {buf.asset_id} flush failed: {e}"
+            msg = f"buffer {buf.asset_id} flush/commit failed: {e}"
             if strict:
                 failures.append(msg)
             else:
@@ -499,6 +500,20 @@ class CommandBuffer:
         _apply_proxy_id_rewrites(results, proxy_id_refs)
         return results
 
+    def commit(self) -> None:
+        """Flush pending commands and release the server-side edit session.
+
+        The HTTP command response tells us docx-studio applied the batch to its
+        pooled SuperDoc handle. Releasing the handle closes the collaboration
+        session without discard on the server, which is the durability
+        checkpoint for asset-backed document edits.
+        """
+        self._assert_current_execution()
+        self.flush()
+        release_asset = getattr(self._client, "release_asset", None)
+        if callable(release_asset):
+            release_asset(self._asset_id)
+
     def close(self) -> None:
         """Flush and disable. Idempotent."""
         if self._closed:
@@ -513,7 +528,7 @@ class CommandBuffer:
                     self._proxy_id_refs = {}
                 _ptc_emit_end_batch(pending, is_error=True)
             else:
-                self.flush()
+                self.commit()
         finally:
             self._closed = True
             _unregister(self)

{athena_python_docx-0.15.3 → athena_python_docx-0.15.5}/docx/_http_doc.py

@@ -699,6 +699,24 @@ class HttpClient:
         except Exception:  # noqa: BLE001
             pass
 
+    def release_asset(self, asset_id: str) -> None:
+        """Ask docx-studio to close its pooled SuperDoc session for ``asset_id``.
+
+        Command POSTs only prove that the server accepted and applied the
+        mutation batch to its live SuperDoc handle. The durable checkpoint for
+        collaborative sessions happens when that handle is closed without
+        discard, so ``Document.save()`` and the Daytona ``flush_all`` cleanup
+        call this endpoint after draining the command buffer.
+        """
+        url: str = f"{self._base_url}/docs/{asset_id}/session/release"
+        _http_post_json(
+            session=self._session,
+            url=url,
+            api_key=self._api_key,
+            body={},
+            timeout=30.0,
+        )
+
     def execute_batch(
         self,
         asset_id: str,

{athena_python_docx-0.15.3 → athena_python_docx-0.15.5}/docx/_timeouts.py

@@ -13,6 +13,13 @@ LONG_RUNNING_COMMAND_TIMEOUT_SECONDS: float = 300.0
 
 _LONG_RUNNING_COMMAND_TYPES: frozenset[str] = frozenset(
     {
+        # The first write to a large imported document can spend close to a
+        # minute opening/syncing the server-side SuperDoc session before the
+        # block creation itself is applied. These are ordinary agent primitives
+        # for "append a summary/TLDR", so give the first batch enough room.
+        "CreateHeading",
+        "CreateParagraph",
+        "CreateSectionBreak",
         "FindReplace",
         # Plain ``cell.text = value`` table fills are buffered as TableSetCell
         # commands. On dense legal documents, SuperDoc can spend well over the

{athena_python_docx-0.15.3 → athena_python_docx-0.15.5}/docx/client.py

@@ -231,8 +231,8 @@ class Session:
         handle = self._doc_handle
         buffer = getattr(handle, "buffer", None) if handle is not None else None
         if buffer is not None:
-            buffer.flush()
-        _log_info(f"Saved {self._asset_id} (buffer drained)")
+            buffer.commit()
+        _log_info(f"Saved {self._asset_id} (buffer drained and session released)")
 
     async def close(self) -> None:
         """Close the session. Idempotent."""

{athena_python_docx-0.15.3 → athena_python_docx-0.15.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.15.3"
+version = "0.15.5"
 description = "Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack"
 readme = "README.md"
 license = "MIT"

{athena_python_docx-0.15.3 → athena_python_docx-0.15.5}/tests/test_buffer.py

@@ -7,8 +7,9 @@ Verifies that:
 - Creates WITH a client id (the transparent-batching path) defer,
 - pending mutations drain in the same batch as an eager call,
 - ``flush()`` drains explicitly,
+- ``commit()`` drains and releases the server-side session,
 - the idle timer auto-flushes after a configurable window,
-- the process-wide ``flush_all`` walks every live buffer.
+- the process-wide ``flush_all`` walks every live buffer and commits it.
 """
 
 from __future__ import annotations
@@ -26,6 +27,7 @@ from docx._timeouts import DEFAULT_OP_TIMEOUT_SECONDS, LONG_RUNNING_COMMAND_TIME
 from docx.commands import (
     BlocksList,
     Command,
+    CreateHeading,
     CreateParagraph,
     FormatApply,
     Replace,
@@ -44,6 +46,7 @@ class _FakeClient:
         # Envelope-level fields recorded per batch — used by
         # track-changes tests to verify changeMode / user propagation.
         self.envelopes: list[dict[str, Any]] = []
+        self.releases: list[str] = []
         self._lock = threading.Lock()
 
     def execute_batch(
@@ -62,6 +65,10 @@ class _FakeClient:
         # Mimic per-command result envelope.
         return [{"index": i, "ok": True} for i, _ in enumerate(commands)]
 
+    def release_asset(self, asset_id: str) -> None:
+        with self._lock:
+            self.releases.append(asset_id)
+
 
 class _FakeDocHandle:
     def __init__(self, buffer: CommandBuffer) -> None:
@@ -109,6 +116,23 @@ def test_pending_timeout_extends_for_table_set_cell_batches() -> None:
     buf.close()
 
 
+def test_pending_timeout_extends_for_block_creation_batches() -> None:
+    fake = _FakeClient()
+    buf = CommandBuffer(fake, "asset_1", auto_flush_seconds=0.0)
+
+    buf.call(
+        CreateHeading(
+            text="TLDR",
+            level=1,
+            at={"kind": "documentEnd"},
+            client_node_id="h_test",
+        )
+    )
+
+    assert buf.pending_timeout_seconds == LONG_RUNNING_COMMAND_TIMEOUT_SECONDS
+    buf.close()
+
+
 def test_session_pending_timeout_reads_command_buffer_budget() -> None:
     from docx.client import Session
 
@@ -189,6 +213,19 @@ def test_flush_with_empty_queue_is_noop() -> None:
     buf.close()
 
 
+def test_commit_drains_pending_and_releases_server_session() -> None:
+    fake = _FakeClient()
+    buf = CommandBuffer(fake, "asset_1", auto_flush_seconds=0.0)
+
+    buf.call(FormatApply(target={"kind": "block"}, inline={"bold": True}))
+    buf.commit()
+
+    assert len(fake.batches) == 1
+    assert _types(fake.batches[0]) == ["FormatApply"]
+    assert fake.releases == ["asset_1"]
+    buf.close()
+
+
 def test_idle_timer_auto_flushes() -> None:
     """A non-zero idle window should flush after inactivity.
 
@@ -282,6 +319,8 @@ def test_flush_all_walks_every_live_buffer() -> None:
     flush_all()
     assert len(fake_a.batches) == 1
     assert len(fake_b.batches) == 1
+    assert fake_a.releases == ["asset_a"]
+    assert fake_b.releases == ["asset_b"]
     buf_a.close()
     buf_b.close()
 

{athena_python_docx-0.15.3 → athena_python_docx-0.15.5}/tests/test_http_transport.py

@@ -17,7 +17,7 @@ import requests
 from docx import __version__ as SDK_VERSION
 from docx._http_doc import HttpClient, HttpDocHandle
 from docx._timeouts import LONG_RUNNING_COMMAND_TIMEOUT_SECONDS
-from docx.commands import FindReplace, TableSetCell
+from docx.commands import CreateParagraph, FindReplace, TableSetCell
 from docx.errors import AuthenticationError, DocxError, SessionError
 
 
@@ -145,6 +145,73 @@ def test_table_set_cell_batch_uses_long_running_http_timeout() -> None:
     assert captured["timeout"] == LONG_RUNNING_COMMAND_TIMEOUT_SECONDS
 
 
+def test_block_creation_batch_uses_long_running_http_timeout() -> None:
+    captured: dict[str, Any] = {}
+
+    def _capture(url: str, **kwargs: Any) -> _FakeResponse:  # noqa: ARG001
+        captured["timeout"] = kwargs["timeout"]
+        return _FakeResponse(
+            status_code=200,
+            body=_ok_body(
+                [
+                    {
+                        "index": 0,
+                        "type": "CreateParagraph",
+                        "result": {
+                            "client_node_id": "p_test",
+                            "real_node_id": "paragraph_real",
+                        },
+                    }
+                ],
+            ),
+        )
+
+    client = HttpClient(base_url="https://example.com", api_key="bg_key")
+
+    with patch.object(client._session, "post", side_effect=_capture):
+        result = client.execute_batch(
+            "asset_test",
+            [
+                CreateParagraph(
+                    text="DLDR",
+                    at={"kind": "documentEnd"},
+                    client_node_id="p_test",
+                )
+            ],
+        )
+
+    assert result == [
+        {"client_node_id": "p_test", "real_node_id": "paragraph_real"}
+    ]
+    assert captured["timeout"] == LONG_RUNNING_COMMAND_TIMEOUT_SECONDS
+
+
+def test_release_asset_posts_to_session_release_endpoint() -> None:
+    captured: dict[str, Any] = {}
+
+    def _capture(url: str, **kwargs: Any) -> _FakeResponse:
+        captured["url"] = url
+        captured["body"] = json.loads(kwargs["data"].decode("utf-8"))
+        captured["auth"] = kwargs["headers"].get("Authorization")
+        captured["timeout"] = kwargs["timeout"]
+        return _FakeResponse(
+            status_code=200,
+            body=b'{"assetId":"asset_test","released":true}',
+        )
+
+    client = HttpClient(base_url="https://example.com", api_key="bg_key")
+
+    with patch.object(client._session, "post", side_effect=_capture):
+        client.release_asset("asset_test")
+
+    assert captured == {
+        "url": "https://example.com/docs/asset_test/session/release",
+        "body": {},
+        "auth": "Bearer bg_key",
+        "timeout": 30.0,
+    }
+
+
 def test_deeply_nested_paths() -> None:
     """``doc.format.paragraph.set_alignment(p)`` walks three levels and
     serializes as ``SetParagraphAlignment``. It's a pure mutation, so it

{athena_python_docx-0.15.3 → athena_python_docx-0.15.5}/uv.lock

@@ -21,7 +21,7 @@ wheels = [
 
 [[package]]
 name = "athena-python-docx"
-version = "0.15.2"
+version = "0.15.3"
 source = { editable = "." }
 dependencies = [
     { name = "requests" },