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

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

@@ -39,6 +39,18 @@ These standard python-docx members don't apply to a Superdoc-backed SDK:
   `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`.
+- **`docx.oxml.*`** — the entire raw-OOXML module tree (``ns.qn``,
+  ``OxmlElement``, ``CT_*`` classes, etc.) is unavailable because the
+  SDK is HTTP-only against a SuperDoc Y.Doc; there is no local lxml
+  tree to manipulate. As of 0.8.0, ``docx.oxml`` is a real stub
+  package that raises a typed
+  :class:`docx.oxml.OxmlNotAvailableError` (subclass of
+  ``ImportError``) on any attribute access, with an inline pointer at
+  the high-level API (``Document.add_paragraph``, ``Run.bold``,
+  ``_Cell.text``, …) or the typed command surface in
+  ``docx.commands``. Pre-0.8.0 this used to fail with the stdlib's
+  generic ``ModuleNotFoundError: No module named 'docx.oxml'`` and
+  agents had to retry to discover the gap.
 
 ### Phase-3b upstream-blocked surface
 
@@ -135,11 +147,40 @@ 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.
+- **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`)
+  ignores the response — the Run proxy wraps a known client-side range
+  and doesn't need the server's echoed node id. Net result: a styled
+  run (one `add_run` + 6 format setters) ships as 1 HTTP request
+  instead of 2. The remaining response-bearing ops without a client id
+  (`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.
+- **Plain-text cell fast path (0.8.0+):** `_Cell.text = value` skips
+  the eager `doc.markdownToFragment` query when ``value`` contains no
+  markdown control characters (the dominant case for tabular data —
+  numbers, labels, currency strings). The fragment is built locally
+  and the follow-up `doc.insert` is buffered, so plain cell
+  assignments are 0 HTTP requests until the next flush. See
+  ``docx.table._is_plain_text`` for the trigger predicate.
 - 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.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.6.2
+Version: 0.8.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.8.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.8.0"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.6.2 → athena_python_docx-0.8.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.8.0}/docx/_http_doc.py

@@ -93,6 +93,7 @@ from docx.commands import (
     SetSectionPageMargins,
     SetSectionPageSetup,
     SetSectionTitlePage,
+    SetSectionsOddEvenHeadersFooters,
     TablesGet,
     TablesGetCells,
     TablesGetProperties,
@@ -111,6 +112,7 @@ from docx.commands import (
 )
 from docx.errors import (
     AuthenticationError,
+    BlockNotFoundError,
     DocxError,
     NotFoundError,
     SessionError,
@@ -133,6 +135,39 @@ _NOT_FOUND_ERROR_NAMES: frozenset[str] = frozenset(
 )
 
 
+def _looks_like_block_not_found(err_obj: dict) -> bool:
+    """Detect SuperDoc's ``Block "<type>:<id>" was not found`` shape.
+
+    Triggers the typed :class:`BlockNotFoundError` so agent code can
+    distinguish a missing-block miss (cell-inner-paragraph addressing
+    bug, stale id from a different session) from a generic transport
+    or validation error.
+    """
+    msg = err_obj.get("message")
+    if not isinstance(msg, str):
+        return False
+    lower = msg.lower()
+    if "not found" not in lower:
+        return False
+    # Be conservative: require either ``block "`` (the SuperDoc CLI's
+    # quoted-id format) or ``block <id>`` followed by ``not found``.
+    return 'block "' in lower or ('block ' in lower and ' was not found' in lower)
+
+
+_CELL_PARAGRAPH_HINT: str = (
+    "\n\nHint: SuperDoc 1.8.1 cannot format paragraphs nested inside "
+    "table cells via SetParagraphAlignment / SetParagraphStyle / "
+    "SetParagraphIndentation / SetParagraphSpacing or doc.insert with "
+    "a paragraph-block target. The cell's inner paragraph id is "
+    "returned by cell.getNodeById but isn't a top-level addressable "
+    "block. Materialize the cell's paragraph first via "
+    '``cell.text = "value"``, then re-read ``cell.paragraphs[0]`` and '
+    "apply format ops to that post-materialization Paragraph proxy. "
+    "Tracked upstream at docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md "
+    "§ 'cell-inner paragraph addressing'."
+)
+
+
 def _looks_like_not_found(parsed: dict) -> bool:
     """Inspect a docx-studio partial-failure dict and decide whether it
     describes a "no such entity" miss (vs. a real transport / validation
@@ -284,11 +319,30 @@ def _http_post_json(
         # sites (``Comments.get``) can coerce it to ``None`` without
         # swallowing real transport / validation failures.
         err_obj = parsed.get("error") if isinstance(parsed, dict) else None
-        if isinstance(err_obj, dict) and _looks_like_not_found(err_obj):
-            raise NotFoundError(
-                f"docx-studio batch reported a partial failure: {parsed!r}",
-                payload=err_obj,
-            )
+        if isinstance(err_obj, dict):
+            base_msg = f"docx-studio batch reported a partial failure: {parsed!r}"
+            # ``BlockNotFoundError`` is the narrower miss — caller is most
+            # likely targeting a cell-inner paragraph or stale-session
+            # block id. Surface the typed exception plus an agent-readable
+            # workaround so the next attempt doesn't repeat the same
+            # mistake. The cell-paragraph hint only applies when the
+            # missing id has the ``paragraph:`` prefix (SuperDoc's quoted-
+            # id error format) — stale list-item / table-row / image ids
+            # would benefit from a different hint or none at all, and a
+            # red-herring "use cell.text" pointer would just waste the
+            # next retry.
+            if _looks_like_block_not_found(err_obj):
+                msg_str = err_obj.get("message")
+                paragraph_block = (
+                    isinstance(msg_str, str)
+                    and "paragraph:" in msg_str.lower()
+                )
+                raise BlockNotFoundError(
+                    base_msg + (_CELL_PARAGRAPH_HINT if paragraph_block else ""),
+                    payload=err_obj,
+                )
+            if _looks_like_not_found(err_obj):
+                raise NotFoundError(base_msg, payload=err_obj)
         raise DocxError(
             f"docx-studio batch reported a partial failure: {parsed!r}",
         )
@@ -465,6 +519,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.8.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
 
 
@@ -790,8 +814,15 @@ _RESPONSE_BEARING_TYPES: frozenset[str] = frozenset(
         # CreateImage returns {image: {nodeId}}; SetImageSize and the
         # InlineShape proxy both need that nodeId, so it must flush.
         "CreateImage",
-        # Insert sometimes returns an id; treat as response-bearing for safety.
-        "Insert",
+        # Insert is INTENTIONALLY not here as of 0.8.0. All in-tree
+        # callers (``Paragraph._insert_run_text_segments``, ``Run.add_text``,
+        # ``_Cell.text``) wrap a known client-side range/cell target and
+        # never read Insert's response; deferring it lets a styled
+        # ``add_run`` flow ship its text-insert in the same HTTP batch
+        # as the format setters that follow it. If a future caller needs
+        # the Insert response, route it through ``CommandBuffer._eager_flush_with``
+        # at the call site rather than re-adding Insert here, so the
+        # batched path isn't penalized for the one outlier.
         # CreateSectionBreak intentionally NOT here — it returns no node id;
         # the caller resolves the new section via sections.list afterwards.
         # CommentsCreate returns the new comment's entityId — caller wraps
@@ -856,6 +887,7 @@ __all__ = [
     "SetSectionHeaderFooterMargins",
     "SetSectionBreakType",
     "SetSectionTitlePage",
+    "SetSectionsOddEvenHeadersFooters",
     "SetSectionLinkToPrevious",
     # Tables (mutations)
     "TablesInsertRow",