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

{athena_python_docx-0.6.1 → 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.1 → athena_python_docx-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.6.1
+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.1 → 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.1"
+__version__ = "0.7.0"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.6.1 → 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(
@@ -278,11 +272,15 @@ class CommandBuffer:
         # 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]
+            cmd._ptc_call_id = _ptc.emit_begin(  # type: ignore[attr-defined]
+                type(cmd).__name__,
+                cmd.to_dict(),
+                asset_id=self._asset_id,
+            )
         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:
@@ -290,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.
@@ -317,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()
@@ -371,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:
@@ -423,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.1 → athena_python_docx-0.7.0}/docx/_http_doc.py

@@ -68,6 +68,8 @@ from docx.commands import (
     Insert,
     InsertLineBreak,
     InsertTab,
+    ListsAttach,
+    ListsCreate,
     ListsMerge,
     ListsSplit,
     MarkdownToFragment,
@@ -91,6 +93,7 @@ from docx.commands import (
     SetSectionPageMargins,
     SetSectionPageSetup,
     SetSectionTitlePage,
+    SetSectionsOddEvenHeadersFooters,
     TablesGet,
     TablesGetCells,
     TablesGetProperties,
@@ -463,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,
@@ -503,9 +507,14 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "header_footers.get": HeaderFootersGet,
     "header_footers.resolve": HeaderFootersResolve,
     "header_footers.refs.set_linked_to_previous": HeaderFootersRefsSetLinkedToPrevious,
-    # Lists & Selection (SuperDoc 1.8.1 additions; not exposed on the
-    # python-docx parity surface — registered here for typed-bus
-    # completeness when advanced callers reach for them).
+    # Lists & Selection. ``lists.create`` and ``lists.attach`` are
+    # consumed internally by ``Document.add_paragraph`` to make
+    # ``style="List Bullet" | "List Number"`` produce real list
+    # structure (not just a style attribute on a flat paragraph).
+    # ``lists.merge``/``lists.split`` stay typed-bus-only — no
+    # python-docx parity surface for them.
+    "lists.create": ListsCreate,
+    "lists.attach": ListsAttach,
     "lists.merge": ListsMerge,
     "lists.split": ListsSplit,
     "selection.current": SelectionCurrent,

athena_python_docx-0.7.0/docx/_ptc.py

@@ -0,0 +1,138 @@
+"""Programmatic Tool Calling (PTC) — client side.
+
+Activated only when ``ATHENA_PTC_URL`` is set. The URL is a presigned
+endpoint URL with an HMAC-signed token embedded as ``?t=…``; the token
+carries the (thread, parent_tool_call_id, run) triple and an expiry.
+The SDK doesn't need to know that triple — it just POSTs to the URL
+verbatim, and the server derives identity from the token.
+
+Without ``ATHENA_PTC_URL`` set, every call here is a no-op.
+
+Emits are fire-and-forget on a background daemon thread:
+
+- Never raise into user code.
+- Never block the calling thread.
+- Re-read ``ATHENA_PTC_URL`` on every emit so updates between sandbox
+  executions take effect immediately (the SDK module itself is cached
+  across runs).
+- Snapshot the URL at ``emit_begin`` time and carry it to ``emit_end``
+  so late end events can't be misattributed if a new sandbox run
+  swapped in a different URL between begin and end.
+
+This module is *intentionally byte-identical* across the docx / pptx /
+xlsx SDKs — the three SDKs have no shared base. Duplicating ~100 LOC
+of stdlib code is cheaper than spinning up a 4th release pipeline.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import queue
+import threading
+import time
+import urllib.error
+import urllib.request
+import uuid
+from typing import Any
+
+_MAX_QUEUE = 4096
+_MAX_BODY = 64 * 1024
+_HTTP_TIMEOUT = 2.0
+
+# Singleton state. PTC has exactly one outbox per process.
+_outbox: queue.Queue[tuple[str, dict[str, Any]]] = queue.Queue(maxsize=_MAX_QUEUE)
+_thread_lock = threading.Lock()
+_thread_started = False
+# call_id -> URL snapshot at begin time; lets emit_end target the
+# original run's endpoint even if ATHENA_PTC_URL changed since.
+_call_url: dict[str, str] = {}
+
+
+def _drain() -> None:
+    while True:
+        item = _outbox.get()
+        if item is None:
+            return
+        url, body = item
+        try:
+            raw = json.dumps(body).encode("utf-8")
+            if len(raw) > _MAX_BODY:
+                key = "args" if body.get("phase") == "begin" else "result"
+                body[key] = {"__truncated__": True}
+                raw = json.dumps(body).encode("utf-8")
+            req = urllib.request.Request(
+                url,
+                data=raw,
+                method="POST",
+                headers={"Content-Type": "application/json"},
+            )
+            urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT).close()
+        except (urllib.error.URLError, OSError, ValueError):
+            pass  # never propagate
+
+
+def _ensure_thread() -> None:
+    global _thread_started
+    if _thread_started:
+        return
+    with _thread_lock:
+        if _thread_started:
+            return
+        threading.Thread(target=_drain, name="athena-ptc", daemon=True).start()
+        _thread_started = True
+
+
+def _send(url: str, body: dict[str, Any]) -> None:
+    _ensure_thread()
+    try:
+        _outbox.put_nowait((url, body))
+    except queue.Full:
+        pass  # drop on backpressure; never block user code
+
+
+def emit_begin(
+    tool_name: str,
+    args: dict[str, Any],
+    *,
+    asset_id: str | None = None,
+) -> str:
+    call_id = uuid.uuid4().hex
+    url = os.environ.get("ATHENA_PTC_URL")
+    if not url:
+        return call_id
+    _call_url[call_id] = url
+    body: dict[str, Any] = {
+        "callId": call_id,
+        "toolName": tool_name,
+        "phase": "begin",
+        "args": args,
+        "ts": time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime()),
+    }
+    if asset_id is not None:
+        body["assetId"] = asset_id
+    _send(url, body)
+    return call_id
+
+
+def emit_end(
+    *,
+    call_id: str,
+    tool_name: str,
+    result: dict[str, Any] | None,
+    is_error: bool,
+) -> None:
+    url = _call_url.pop(call_id, None)
+    if url is None:
+        return  # PTC was disabled at begin, or begin wasn't emitted
+    _send(
+        url,
+        {
+            "callId": call_id,
+            "toolName": tool_name,
+            "phase": "end",
+            "result": result,
+            "isError": is_error,
+            "ts": time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime()),
+        },
+    )

{athena_python_docx-0.6.1 → 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
 
 
@@ -619,6 +643,40 @@ class HeaderFootersRefsSetLinkedToPrevious(Command):
 # every other op.
 
 
+@dataclass
+class ListsCreate(Command):
+    """Create a new list — either an empty list at an anchor, or by
+    converting an existing paragraph (range) into a list.
+
+    SuperDoc: ``doc.lists.create``.
+
+    - ``mode="empty"`` requires ``at`` (BlockAddress).
+    - ``mode="fromParagraphs"`` requires ``target`` (BlockAddressOrRange).
+    - ``kind`` is ``"bullet"`` or ``"ordered"``.
+    """
+
+    mode: str = "fromParagraphs"
+    at: dict[str, Any] | None = None
+    target: dict[str, Any] | None = None
+    kind: str | None = None
+    level: int | None = None
+    preset: str | None = None
+
+
+@dataclass
+class ListsAttach(Command):
+    """Attach an existing paragraph to an existing list as a new item.
+
+    SuperDoc: ``doc.lists.attach``. ``attach_to`` is the list item to
+    attach next to (defines list membership); ``target`` is the
+    paragraph being converted.
+    """
+
+    attach_to: dict[str, Any] = dataclasses.field(default_factory=dict)
+    target: dict[str, Any] = dataclasses.field(default_factory=dict)
+    level: int | None = None
+
+
 @dataclass
 class ListsMerge(Command):
     """Merge a list item with an adjacent list / list item.
@@ -768,6 +826,12 @@ _RESPONSE_BEARING_TYPES: frozenset[str] = frozenset(
         # describing the entities affected by accept/reject — callers
         # need that synchronously to invalidate their Revision proxies.
         "TrackChangesDecide",
+        # ListsCreate / ListsAttach return {item: {nodeId: <listItemId>}}.
+        # Document.add_paragraph reads listItemId to (1) update the
+        # Paragraph proxy's node_id so subsequent ops target the
+        # listItem, and (2) chain the next list item via lists.attach.
+        "ListsCreate",
+        "ListsAttach",
     }
 )
 
@@ -816,6 +880,7 @@ __all__ = [
     "SetSectionHeaderFooterMargins",
     "SetSectionBreakType",
     "SetSectionTitlePage",
+    "SetSectionsOddEvenHeadersFooters",
     "SetSectionLinkToPrevious",
     # Tables (mutations)
     "TablesInsertRow",