athena-python-docx 0.6.2__tar.gz → 0.7.0__tar.gz

{athena_python_docx-0.6.2 → athena_python_docx-0.7.0}/CLAUDE.md

@@ -135,11 +135,27 @@ This is a **thin HTTP client** that mimics the sync python-docx API.
   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.
+- **Transparent batching (0.7.0+):** Create* commands
+  (`CreateParagraph`, `CreateHeading`, `CreateTable`, `CreateImage`)
+  ALWAYS pre-mint a client-side UUID (`client_node_id`) and defer
+  through the buffer. The applier resolves UUIDs to real SuperDoc
+  ids via per-batch `clientIdMap` on flush, and the buffer rewrites
+  each proxy's `_node_id` in-place. Net result: 30 `add_paragraph`
+  calls = 1 HTTP request, with no explicit `batch()` context manager
+  in the public API (1:1 python-docx parity).
+- Flush triggers: queries (`BlocksList`, `Find`, `GetNodeById`, …)
+  drain pending ops before running; the 100 ms idle timer fires on
+  inactivity so collab updates stream live; `Document.save()` and
+  the context-manager exit drain explicitly; `docx.flush_all()` is
+  the Daytona-prelude hook that flushes every live buffer in the
+  process.
+- Other response-bearing ops without a client id (`Insert`,
+  `ListsCreate`, `ListsAttach`, `CommentsCreate`, `CommentsPatch`,
+  `TrackChangesDecide`) keep their eager-flush semantics so callers
+  reading back ids still see real data. A `Document.add_paragraph`
+  with `style="List Bullet"` flushes the queued CreateParagraph in
+  the same batch as the follow-up `ListsCreate` — still one HTTP
+  request per logical operation.
 - 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

{athena_python_docx-0.6.2 → athena_python_docx-0.7.0}/PKG-INFO

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

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

{athena_python_docx-0.6.2 → athena_python_docx-0.7.0}/docx/_buffer.py

@@ -1,9 +1,17 @@
 """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.
+mutation routes through it; we flush eagerly for queries, and idle-batch
+all other ops — including Create* — so a burst of ``add_paragraph`` calls
+ships as one HTTP request instead of N.
+
+Create* commands are deferred because the SDK pre-mints a client-side
+UUID for every new node (see ``Document._mint_client_node_id``). The
+proxy returned to the caller is stamped with that UUID; the applier
+resolves UUIDs to real SuperDoc ids via ``clientIdMap`` and echoes the
+mapping back, at which point the buffer rewrites each proxy's
+``_node_id``. This makes batching invisible at the call site — user
+code looks like python-docx, runs at python-docx-batched speed.
 
 Concurrency model: the SDK serializes calls through ``_batching.run_sync``
 (one persistent event-loop thread), so the buffer's primary thread is the
@@ -23,11 +31,10 @@ from __future__ import annotations
 import sys
 import threading
 import weakref
-from contextlib import contextmanager
-from typing import TYPE_CHECKING, Any, Generator
+from typing import TYPE_CHECKING, Any
 
 from docx import _ptc
-from docx.commands import Command, must_flush_immediately
+from docx.commands import Command, is_response_bearing, must_flush_immediately
 
 if TYPE_CHECKING:
     from docx._http_doc import HttpClient
@@ -125,12 +132,17 @@ 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()``.
+    - Queries (BlocksList, Find, GetNodeById, …) flush immediately and
+      drain any pending mutations in the same batch so ordering is preserved.
+    - Every other op — formatters, setters, AND Create* — queues. The idle
+      timer flushes after :data:`DEFAULT_AUTO_FLUSH_SECONDS` of inactivity,
+      the next eager (query) call drains, or explicit ``flush()`` drains.
+
+    Create* commands defer because the SDK pre-mints a client-side UUID
+    (``client_node_id`` / ``client_entity_id``); the applier translates
+    the UUID to a real SuperDoc id in a per-batch ``clientIdMap`` and
+    echoes the mapping back so the SDK can rewrite each proxy's
+    ``_node_id`` on flush.
     """
 
     def __init__(
@@ -154,11 +166,6 @@ class CommandBuffer:
         # 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
@@ -168,22 +175,11 @@ class CommandBuffer:
         ] = {}
         _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.
+        ``client_id`` to the real node id once the queue flushes.
 
         Called by ``Document.add_paragraph`` (and equivalents) when they
         queue a Create with a ``client_node_id``. The flush loop walks
@@ -254,21 +250,19 @@ class CommandBuffer:
     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.
+        For queries (``BlocksList``, ``Find``, ``GetNodeById``, …)
+        AND response-bearing commands that don't carry a client-side
+        id, drains the pending queue and runs ``cmd`` in the same
+        batch; returns the per-cmd result dict.
+
+        Otherwise — pure mutations (formatters, setters) AND Create*
+        commands that carry a pre-minted ``client_node_id`` /
+        ``client_entity_id`` — appends to the queue, resets the idle
+        timer, and returns ``None``. Caller MUST NOT rely on the return
+        value of a buffered mutation. For deferred Creates, the
+        applier resolves the client UUID to a real SuperDoc id via
+        ``clientIdMap`` on flush and the buffer rewrites each registered
+        proxy's ``_node_id`` in-place.
         """
         if self._closed:
             raise RuntimeError(
@@ -286,7 +280,7 @@ class CommandBuffer:
         except Exception:  # noqa: BLE001
             pass
 
-        if must_flush_immediately(cmd) and not self._is_batched_create(cmd):
+        if must_flush_immediately(cmd) and not self._has_client_id(cmd):
             return self._eager_flush_with(cmd)
 
         with self._lock:
@@ -294,23 +288,25 @@ class CommandBuffer:
             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.
+    @staticmethod
+    def _has_client_id(cmd: Command) -> bool:
+        """Return ``True`` iff this command carries a pre-minted
+        client-side id (``client_node_id`` for nodes,
+        ``client_entity_id`` for comments).
+
+        Used by :meth:`call` to decide whether a response-bearing
+        Create can defer. Pure response-bearing ops without a client
+        id (``Insert``, ``CommentsPatch``, ``TrackChangesDecide``,
+        legacy callers) keep their eager-flush semantics so callers
+        that read the response still see real data.
         """
-        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
+        return (
+            is_response_bearing(cmd)
+            and (
+                getattr(cmd, "client_node_id", None) is not None
+                or getattr(cmd, "client_entity_id", None) is not None
+            )
+        )
 
     def flush(self) -> list[Any]:
         """Flush pending commands as one HTTP batch.
@@ -321,9 +317,10 @@ class CommandBuffer:
         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.
+        resolved server ids. This completes the round-trip for the
+        always-on transparent batching path — the SDK's caller-facing
+        proxies pick up real ids without the caller ever seeing the
+        UUID swap.
         """
         with self._lock:
             self._cancel_timer_locked()
@@ -375,43 +372,6 @@ class CommandBuffer:
                             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:
@@ -427,11 +387,11 @@ class CommandBuffer:
     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.
+        When pending commands include Creates with registered proxy
+        refs (queries mid-stream cause this — the caller is awaiting
+        their result and the queue must drain first), 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()

{athena_python_docx-0.6.2 → athena_python_docx-0.7.0}/docx/_http_doc.py

@@ -93,6 +93,7 @@ from docx.commands import (
     SetSectionPageMargins,
     SetSectionPageSetup,
     SetSectionTitlePage,
+    SetSectionsOddEvenHeadersFooters,
     TablesGet,
     TablesGetCells,
     TablesGetProperties,
@@ -465,6 +466,7 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "sections.set_header_footer_margins": SetSectionHeaderFooterMargins,
     "sections.set_break_type": SetSectionBreakType,
     "sections.set_title_page": SetSectionTitlePage,
+    "sections.set_odd_even_headers_footers": SetSectionsOddEvenHeadersFooters,
     "sections.set_link_to_previous": SetSectionLinkToPrevious,
     # Tables (mutations)
     "tables.insert_row": TablesInsertRow,

{athena_python_docx-0.6.2 → athena_python_docx-0.7.0}/docx/commands.py

@@ -59,17 +59,19 @@ class Command:
 
 # --- Create* commands carry an optional client-assigned node id ---
 #
-# When the SDK runs inside ``with doc.batch():`` (see
-# ``Document.batch()``) every Create* command pre-generates a UUID and
-# stamps the new Paragraph/Heading/Table/Image proxy with it. The
-# applier translates ``client_node_id`` → real SuperDoc nodeId in a
-# per-batch map (see ``apps/api/src/commands/applier.ts``), so
-# subsequent commands in the same batch can target the new block by
-# its client-side id before the response has even returned. After
-# flush, the buffer reads the resolved ``real_node_id`` out of each
-# Create's response and updates the proxy. Outside batch mode the
-# field is left empty and Create* still flushes immediately
-# (response-bearing) to preserve the existing eager-id behavior.
+# The SDK pre-generates a UUID for every new Paragraph/Heading/Table/
+# Image and stamps the proxy with it. The applier translates
+# ``client_node_id`` → real SuperDoc nodeId in a per-batch map (see
+# ``apps/api/src/commands/applier.ts``), so subsequent commands in the
+# same batch can target the new block by its client-side id before the
+# response has even returned. After flush, the buffer reads the
+# resolved ``real_node_id`` out of each Create's response and updates
+# the proxy in-place.
+#
+# Direct internal callers that bypass ``Document`` (legacy helpers,
+# fidelity tests) may leave the field unset; the buffer then eager-
+# flushes the Create immediately so callers that read the response
+# still see real data.
 #
 # The field is ``client_node_id`` on the Python side and arrives at
 # the server as ``clientNodeId`` via ``_snake_to_camel`` — matches the
@@ -283,6 +285,23 @@ class SetSectionTitlePage(Command):
     enabled: bool
 
 
+@dataclass
+class SetSectionsOddEvenHeadersFooters(Command):
+    """Toggle the document-level ``<w:evenAndOddHeaders/>`` setting.
+
+    Despite living under the ``sections.*`` namespace on the SuperDoc
+    bound-doc API, this op carries no ``target`` — it sets a single
+    doc-level flag that applies to every section. Word stores the
+    underlying value on ``word/settings.xml`` as
+    ``<w:evenAndOddHeaders/>``, which is what python-docx's
+    ``Settings.odd_and_even_pages_header_footer`` writes to.
+
+    Available since SuperDoc 1.8.1 (``DocSectionsSetOddEvenHeadersFooters``).
+    """
+
+    enabled: bool
+
+
 @dataclass
 class SetSectionLinkToPrevious(Command):
     """Toggle the section-side ``linked-to-previous`` flag for one
@@ -532,8 +551,13 @@ class CommentsCreate(Command):
     text: str | None = None
     target: dict[str, Any] | None = None
     parent_id: str | None = None
-    # Optional client-assigned entity id for true-batched CommentsCreate
-    # inside ``with doc.batch():`` — see Create* dataclass docstrings.
+    # Optional client-assigned entity id for transparent-batched
+    # CommentsCreate (parallel to ``client_node_id`` on Create*; the
+    # server applier resolves UUIDs via the same per-batch
+    # ``clientIdMap``). ``Comments.add_comment`` currently leaves this
+    # unset, so CommentsCreate eager-flushes — left in place for
+    # future callers that want to defer comment creates alongside
+    # other ops.
     client_entity_id: str | None = None
 
 
@@ -856,6 +880,7 @@ __all__ = [
     "SetSectionHeaderFooterMargins",
     "SetSectionBreakType",
     "SetSectionTitlePage",
+    "SetSectionsOddEvenHeadersFooters",
     "SetSectionLinkToPrevious",
     # Tables (mutations)
     "TablesInsertRow",