athena-python-docx 0.26.0__tar.gz → 0.28.0__tar.gz

{athena_python_docx-0.26.0 → athena_python_docx-0.28.0}/.gitignore

@@ -18,6 +18,8 @@ dist/
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/
+# The live parity runner's scoreboard and exports (python-sdk/tests/live/runner.py).
+/python-sdk/out/
 
 # Editors
 .vscode/

{athena_python_docx-0.26.0 → athena_python_docx-0.28.0}/AGENTS.md

@@ -25,6 +25,13 @@ Before adding or modifying any API surface:
 
 Run `uv run pytest tests/test_python_docx_api_parity.py -v -s` to verify parity.
 
+The API ratchet sees shape only. For behaviour, `uv run --extra dev python -m
+tests.live.runner --cases <name>` runs a battery case through stock
+python-docx 1.2.0 and through the SDK against a live in-memory DOCX Studio
+and compares what each reads, field by field (`tests/fidelity/METHODOLOGY.md`
+§ L9). CI fails on a live gap `tests/live/baseline.json` does not hold, and
+on a baseline gap that is gone.
+
 ### Intentionally omitted (current SDK limitations)
 
 These standard python-docx members don't apply to a DOCX Studio-backed SDK:
@@ -224,6 +231,11 @@ not file-backed. Each is documented in the relevant docstring.
   `Revision.reject()` resolve a single change. python-docx upstream
   has zero track-changes API, so this entire surface is an Athena
   extension wired to DOCX Studio's `doc.trackChanges.{list,get,decide}`.
+  A run's tracked formatting change (`w:rPrChange`) and a paragraph's
+  (`w:pPrChange`) are `"format"` revisions; `reject()` gives the run or
+  paragraph exactly the earlier properties the change recorded
+  (`tests/test_revisions.py`, docx-studio's
+  `tracked-run-property-changes.test.ts`).
 
 - **Style writes refuse what would write a broken document.** python-docx
   writes these into `styles.xml`; the SDK raises before anything is sent,
@@ -286,7 +298,9 @@ Issue numbers reference `python-openxml/python-docx`.
   `FootnotesGet` / `FootnotesPatch` / `FootnotesDelete`. The
   parallel **`Document.endnotes: Endnotes`** + **`Run.add_endnote
   (text, *, custom_mark=None)`** mirrors the same machinery for
-  end-of-section notes.
+  end-of-section notes. Both list the notes a reference reaches, as
+  Word and the export do: a note whose reference was deleted in the
+  editor stays in the package for undo, and is not listed.
 
 - **`Document.add_toc(*, levels=(1, 3), style_id=None,
   include_hyperlinks=True, title=None, tab_leader="dot", at=None)
@@ -413,6 +427,8 @@ Issue numbers reference `python-openxml/python-docx`.
   inspection. Use this when an agent needs to sample or inspect runs
   without issuing one ``getNodeById`` query per paragraph through
   ``doc.paragraphs`` + ``paragraph.runs``. Routes through `IterRuns`.
+  These three see a footnote or endnote only while a reference reaches
+  it, as `Document.footnotes` / `Document.endnotes` list them.
 
 - **`Paragraph.list_id` / `Paragraph.list_level` /
   `Paragraph.list_format` / `Paragraph.list_number`** — list-item
@@ -956,6 +972,13 @@ architecture or a DOCX Studio constraint:
   sends a column break (`breakType: "column"`), which docx-studio writes after
   the paragraph's content. `DOCX_STUDIO_LIMITATIONS.md` §26.
 
+- **`CoreProperties.modified` is the time of the last save.** The asset is a
+  live Word document, and docx-studio stamps `dcterms:modified` when it saves
+  a change to the package: a section, style or property write, and the export
+  of a changed document. Word stamps it on every save; upstream leaves the
+  value it read until the script sets it. Owner decision, 2026-10-12. Recorded
+  in `tests/parity/intentional_deviations.json` (`live_deviations`).
+
 - **Tracked changes read as Word's final view.** `Paragraph.text`, `runs`,
   `iter_inner_content()`, `Hyperlink.text` / `runs` and `_Cell.text` include
   the runs of a tracked insertion (`w:ins`) and leave out a deletion's
@@ -968,6 +991,78 @@ architecture or a DOCX Studio constraint:
   Markup) show insertions and hide deletions, as these reads do.
   `doc.revisions` lists every change (`tests/test_run_text_python_docx.py`).
 
+- **A citation link Athena added reads as its text, as the export writes it**
+  (owner decision #40122). Athena's citation flow stamps the links it writes
+  with the `Athena citation` tooltip. These links only navigate inside Athena,
+  so the export leaves them out and keeps their text: no `w:hyperlink`, and no
+  citation highlight on that text.
+  - **The reads match the export.** The run reads with no `hyperlink` and no
+    highlight in `Paragraph.runs`, `Paragraph.hyperlinks`, a cell's paragraphs
+    and docx-studio's markdown read.
+  - **Where upstream differs.** Upstream reads the room's `w:hyperlink` as a
+    link.
+  - **Which links are Athena's** is decided by the room's provenance, not by
+    the tooltip alone. A link with the tooltip that came in the uploaded file
+    (the room's source package holds it) is a link everywhere, as Word keeps
+    it.
+  - **Tests:** `applier.test.ts` › `applier — citations`.
+
+- **A field's runs read as python-docx reads them; some writes to them
+  differ.** `Paragraph.text` includes a complex field's displayed result and
+  `Paragraph.runs` holds its begin, field code, separate, result and end runs
+  (each with its own formatting), as python-docx reads the `w:r` children of
+  a `w:p`; a simple field (`w:fldSimple`) reads as nothing (one in a tracked
+  change, which the export writes as a complex field, reads that field's
+  runs), a result run of a note reference reads `""`, and a field in a link
+  is the link's, as in python-docx. Each paragraph of a field that spans
+  paragraphs (a table of contents) holds the field character runs it has
+  (`tests/test_field_reads_python_docx_parity.py`, against stock python-docx
+  on the same `.docx`; `DOCX_STUDIO_LIMITATIONS.md` § 27). A field takes no
+  room in the text-address space, so its runs stand at one offset. Writes:
+  - setting a result run's `.text` changes the field's displayed result,
+    as in python-docx (`Replace` with a `field` target): the export keeps
+    the result's runs where the new text allows (text still there stays in
+    its run, new text goes in the run whose text it replaced; another result
+    run's tab or Word character stays as the source wrote it, and a note
+    reference stays where it is, where python-docx's write of its run would
+    delete it), but writes no result run left with no text, where
+    python-docx keeps an empty `w:r`, and a result run read before the
+    field's result changed (through another read's run, or by a
+    collaborator) raises `FieldRunWriteError` rather than write over that
+    change, where python-docx's run is live;
+  - formatting a result run formats the field's whole result (`FormatApply`
+    with a `field` target), from its source formatting, where python-docx
+    formats that run alone;
+  - `.text` (and `clear()`) on a field character or field code run raises
+    `docx.errors.FieldRunWriteError` naming the field: python-docx replaces
+    the run's `w:fldChar` or `w:instrText` with the text, which breaks the
+    field;
+  - formatting set on a field character or field code run is not applied and
+    emits `PendingFieldRunFormatWarning` (those runs show nothing; docx-studio
+    has no command that writes their own `w:rPr`), where python-docx writes
+    it, so `for run in p.runs: run.bold = True` formats the text and the
+    field's result and warns for the rest;
+  - `add_text`, `add_tab`, `add_break`, `add_picture`, `add_field`,
+    `add_footnote`, `add_endnote`, `add_math` and `add_cross_reference` on
+    any of a field's runs raise `FieldRunWriteError`; python-docx appends to
+    that `w:r`.
+  A field that `Run.add_field` adds is a complex field, as Word's Insert
+  Field writes one, so its paragraph reads its runs, as python-docx reads the
+  exported file. Against a docx-studio that predates `fieldRun` reads, a
+  field reads as no runs and no text, as before (`tests/test_field_runs.py`).
+
+- **`Font.name = "…"` also clears the theme fonts of the two slots it
+  sets.** python-docx writes the name to `w:rFonts`' `w:ascii` and `w:hAnsi`
+  and leaves a `w:asciiTheme` / `w:hAnsiTheme` beside them; Word reads a
+  theme font over the name in its slot (ISO/IEC 29500-1 §17.3.2.26), so
+  after python-docx's write Word still shows the theme font. The SDK sets the
+  same two slots and docx-studio drops their theme fonts with them, so Word
+  shows the font that was set. The run's other slots (`w:eastAsia`, `w:cs`
+  and their theme fonts) and its `w:hint` stay as they were, as in
+  python-docx. The export writes exactly the slots the run's fonts hold
+  (#42248). Recorded in `tests/parity/intentional_deviations.json`
+  (`_comment_behavioral_deviations`).
+
 ### If you need a deviation
 
 If there is a genuine technical reason why a deviation from python-docx is necessary:

{athena_python_docx-0.26.0 → athena_python_docx-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.26.0
+Version: 0.28.0
 Summary: Drop-in replacement for python-docx that connects to Athena's DOCX Studio collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>

{athena_python_docx-0.26.0 → athena_python_docx-0.28.0}/docx/__init__.py

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

athena_python_docx-0.28.0/docx/_batching.py

@@ -0,0 +1,137 @@
+"""Sync→async bridge. Runs a single event loop in a background thread
+and dispatches coroutines from sync callers.
+
+This is the only place in the SDK that uses threading.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import contextvars
+import threading
+from typing import Any, Coroutine, TypeVar
+
+from docx._timeouts import DEFAULT_OP_TIMEOUT_SECONDS
+from docx.errors import OperationTimeoutError
+
+T = TypeVar("T")
+
+_loop: asyncio.AbstractEventLoop | None = None
+_thread: threading.Thread | None = None
+_lock = threading.Lock()
+
+
+class _Progress:
+    """What the thread waiting on a call (:func:`run_sync`) and the call share:
+    the steps the call has finished, and whether the waiter gave up."""
+
+    __slots__ = ("abandoned", "steps")
+
+    def __init__(self) -> None:
+        self.steps = 0
+        self.abandoned = False
+
+
+_progress: contextvars.ContextVar[_Progress | None] = contextvars.ContextVar(
+    "docx_sdk_call_progress", default=None
+)
+
+
+def note_progress() -> None:
+    """A step of the running call finished: one batch of a flush that goes
+    out in several (``HttpClient.execute_batch``). :func:`run_sync` gives the
+    call its ``timeout`` again, so each batch has the budget its request has."""
+    progress = _progress.get()
+    if progress is not None:
+        progress.steps += 1
+
+
+def call_abandoned() -> bool:
+    """True once the caller of the running call timed out
+    (:class:`OperationTimeoutError`): a call of several steps starts no more."""
+    progress = _progress.get()
+    return progress is not None and progress.abandoned
+
+
+def _ensure_loop() -> asyncio.AbstractEventLoop:
+    """Return the persistent background event loop. Starts it lazily."""
+    global _loop, _thread
+
+    with _lock:
+        if _loop is not None and _loop.is_running():
+            return _loop
+
+        loop = asyncio.new_event_loop()
+        loop_ready = threading.Event()
+
+        def _run() -> None:
+            asyncio.set_event_loop(loop)
+            loop_ready.set()
+            loop.run_forever()
+
+        thread = threading.Thread(
+            target=_run,
+            name="docx-sdk-loop",
+            daemon=True,
+        )
+        thread.start()
+        loop_ready.wait(timeout=5)
+        _loop = loop
+        _thread = thread
+        return loop
+
+
+def run_sync(
+    coro: Coroutine[Any, Any, T],
+    *,
+    timeout: float | None = DEFAULT_OP_TIMEOUT_SECONDS,
+) -> T:
+    """Run a coroutine on the background loop and block until it returns.
+
+    Args:
+        coro: The coroutine to execute.
+        timeout: Maximum seconds to wait, counted again whenever the call
+            finishes a step (:func:`note_progress`). ``None`` blocks
+            indefinitely (use sparingly — prefer the default so stalls
+            surface early).
+
+    Raises:
+        OperationTimeoutError: if the coroutine neither completes nor
+            finishes a step within `timeout` seconds. The call then starts
+            no further step (:func:`call_abandoned`).
+        The coroutine's exception, re-raised in the calling thread.
+    """
+    loop = _ensure_loop()
+    progress = _Progress()
+    # The call runs in a copy of this thread's context (call_soon_threadsafe
+    # and the task each copy the current one), so it finds `progress`.
+    token = _progress.set(progress)
+    try:
+        future = asyncio.run_coroutine_threadsafe(coro, loop)
+    finally:
+        _progress.reset(token)
+    seen = 0
+    while True:
+        try:
+            return future.result(timeout=timeout)
+        except concurrent.futures.TimeoutError as exc:
+            if progress.steps > seen:
+                seen = progress.steps
+                continue
+            progress.abandoned = True
+            future.cancel()
+            raise OperationTimeoutError(timeout_seconds=timeout) from exc
+
+
+def shutdown() -> None:
+    """Stop the background event loop. For test teardown."""
+    global _loop, _thread
+    with _lock:
+        if _loop is None:
+            return
+        _loop.call_soon_threadsafe(_loop.stop)
+        if _thread is not None:
+            _thread.join(timeout=5)
+        _loop = None
+        _thread = None

{athena_python_docx-0.26.0 → athena_python_docx-0.28.0}/docx/_buffer.py

@@ -28,8 +28,11 @@ alive.
 
 from __future__ import annotations
 
+import copy
+import json
 import sys
 import threading
+import time
 import weakref
 from typing import TYPE_CHECKING, Any
 
@@ -40,7 +43,7 @@ from docx._execution import (
     is_stale_execution,
 )
 from docx._timeouts import timeout_for_commands
-from docx.commands import Command, is_response_bearing, must_flush_immediately
+from docx.commands import Command, GetNodeById, is_response_bearing, must_flush_immediately
 from docx.errors import DocxError, DocxUnsupportedCommandError, FlushAllError
 
 
@@ -93,6 +96,24 @@ def _apply_proxy_id_rewrites(
                     pass
 
 
+def _repeatable_read_key(cmd: Command) -> str | None:
+    """The key a repeat of ``cmd`` answers from (:meth:`CommandBuffer.call`):
+    a ``GetNodeById``'s wire form; ``None`` for any other command."""
+    if isinstance(cmd, GetNodeById):
+        return json.dumps(cmd.to_dict(), sort_keys=True)
+    return None
+
+
+# How long a node read answers a repeat of it (:meth:`CommandBuffer.call`):
+# long enough for one script statement's property reads of a paragraph or
+# run, short enough that a collaborator's edit since reads.
+READ_REUSE_SECONDS: float = 1.0
+
+
+def _now() -> float:
+    return time.monotonic()
+
+
 def _extract_partial_results(exc: BaseException) -> list[Any]:
     """Pull per-command ``result`` dicts out of a partial-failure error.
 
@@ -196,6 +217,17 @@ def _unregister(buffer: "CommandBuffer") -> None:
         ]
 
 
+def _forget_reads_of_others(sender: "CommandBuffer") -> None:
+    """Every other buffer of ``sender``'s document in this process sends its
+    next node read to the server: ``sender`` sent the document a batch, which
+    a read those buffers reuse (:meth:`CommandBuffer.call`) would not show."""
+    with _registry_lock:
+        buffers = [buffer for ref in _active_buffers if (buffer := ref()) is not None]
+    for buffer in buffers:
+        if buffer is not sender and buffer.asset_id == sender.asset_id:
+            buffer.forget_reads()
+
+
 def flush_all(*, strict: bool = False) -> None:
     """Flush every live CommandBuffer in this process.
 
@@ -367,6 +399,9 @@ class CommandBuffer:
         # ``add_heading`` / etc. when they queue a Create with a
         # client-assigned id. Drained on every flush.
         self._proxy_id_refs: dict[str, list[tuple[object, str]]] = {}
+        # The last command's ``GetNodeById`` key, result and time, while
+        # nothing has been sent or buffered after it (see :meth:`call`).
+        self._last_read: tuple[str, Any, float] | None = None
         _register(self)
 
     def register_proxy_id_ref(self, client_id: str, proxy: object, attr: str = "_node_id") -> None:
@@ -450,6 +485,12 @@ class CommandBuffer:
             if email:
                 self._user["email"] = email
 
+    def forget_reads(self) -> None:
+        """The next node read goes to the server, not to the read before it
+        (:meth:`call`): for a read that checks the document before a write."""
+        with self._lock:
+            self._last_read = None
+
     def call(self, cmd: Command) -> Any:
         """Execute or buffer ``cmd``.
 
@@ -474,6 +515,24 @@ class CommandBuffer:
                 f"CommandBuffer for {self._asset_id} is closed",
             )
 
+        # A read of the node the last command read, with nothing sent or
+        # buffered since and within READ_REUSE_SECONDS of it, answers from
+        # that read: python-docx reads several properties of one paragraph or
+        # run in a row, and each of the SDK's property getters reads the
+        # whole node. A read that guards a write calls forget_reads() first,
+        # and a batch another handle of the document sends clears the read
+        # (_forget_reads_of_others).
+        read_key = _repeatable_read_key(cmd)
+        with self._lock:
+            last_read = self._last_read if not self._pending else None
+        if (
+            read_key is not None
+            and last_read is not None
+            and last_read[0] == read_key
+            and _now() - last_read[2] <= READ_REUSE_SECONDS
+        ):
+            return copy.deepcopy(last_read[1])
+
         # PTC begin: emit only for commands in the allow-list. Other
         # commands still flow through the buffer (and through the batched
         # HTTP POST), they just don't produce a sub-tool-card. ``emit_end``
@@ -489,9 +548,17 @@ class CommandBuffer:
                 pass
 
         if must_flush_immediately(cmd) and not self._has_client_id(cmd):
-            return self._eager_flush_with(cmd)
+            with self._lock:
+                self._last_read = None
+            result = self._eager_flush_with(cmd)
+            if read_key is not None:
+                with self._lock:
+                    if not self._pending:
+                        self._last_read = (read_key, copy.deepcopy(result), _now())
+            return result
 
         with self._lock:
+            self._last_read = None
             self._pending.append(cmd)
             self._reset_timer_locked()
         return None
@@ -577,6 +644,8 @@ class CommandBuffer:
         except Exception:
             _ptc_emit_end_batch(pending, is_error=True)
             raise
+        finally:
+            _forget_reads_of_others(self)
         _ptc_emit_end_batch(pending, is_error=False)
         _apply_proxy_id_rewrites(results, proxy_id_refs)
         return results
@@ -650,6 +719,10 @@ class CommandBuffer:
         except Exception:
             _ptc_emit_end_batch(all_cmds, is_error=True)
             raise
+        finally:
+            # A batch of one node read changes nothing another buffer read.
+            if pending or _repeatable_read_key(cmd) is None:
+                _forget_reads_of_others(self)
         _ptc_emit_end_batch(all_cmds, is_error=False)
         # Proxy-id rewrites still run for the buffered prefix that DID apply —
         # the trailing skip (if any) doesn't strand the supported Creates that

{athena_python_docx-0.26.0 → athena_python_docx-0.28.0}/docx/_http_doc.py

@@ -39,6 +39,7 @@ import requests
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
+from docx._batching import call_abandoned, note_progress
 from docx._buffer import CommandBuffer
 from docx._timeouts import DEFAULT_OP_TIMEOUT_SECONDS, timeout_for_commands
 from docx.commands import (
@@ -187,6 +188,39 @@ from docx.errors import (
 )
 from docx.exceptions import InvalidSpanError
 
+# The most commands docx-studio takes in one batch request
+# (``CommandsRequestSchema`` in ``apps/api/src/commands/types.ts``).
+MAX_BATCH_COMMANDS: int = 500
+
+
+def _minted_ids(results: list[Any]) -> dict[str, str]:
+    """The client → real ids that the Creates among a batch's ``results`` echo."""
+    ids: dict[str, str] = {}
+    for result in results:
+        if not isinstance(result, dict):
+            continue
+        for client_key, real_key in (
+            ("client_node_id", "real_node_id"),
+            ("client_entity_id", "real_entity_id"),
+        ):
+            client, real = result.get(client_key), result.get(real_key)
+            if isinstance(client, str) and isinstance(real, str) and client and real:
+                ids[client] = real
+    return ids
+
+
+def _with_real_ids(value: Any, ids: dict[str, str]) -> Any:
+    """A command's wire form with each value that is a client id in ``ids``
+    replaced by its real id. A client id is a random id the SDK mints, so no
+    other value equals one."""
+    if isinstance(value, str):
+        return ids.get(value, value)
+    if isinstance(value, list):
+        return [_with_real_ids(item, ids) for item in value]
+    if isinstance(value, dict):
+        return {key: _with_real_ids(item, ids) for key, item in value.items()}
+    return value
+
 
 _NOT_FOUND_ERROR_NAMES: frozenset[str] = frozenset(
     {
@@ -850,7 +884,83 @@ class HttpClient:
         change_mode: str | None = None,
         user: dict[str, str] | None = None,
     ) -> tuple[list[Any], dict[int, dict[str, Any]]]:
-        """POST a batch of typed commands.
+        """POST ``commands`` in batches of at most :data:`MAX_BATCH_COMMANDS`,
+        the most docx-studio takes in one request (it answers HTTP 400 to
+        more), and return their results as one batch's
+        (:meth:`_execute_one_batch`): positionally aligned, skips by index.
+
+        A buffer that a loop filled with more commands than that (``for i in
+        range(1000): doc.add_paragraph(...)``) flushes as consecutive
+        batches. Each batch is atomic on the server; a batch that fails
+        leaves the batches before it applied, and its ``DocxError`` carries
+        their results in ``partial_applied`` (input indexes), so the proxies
+        of the Creates that landed still get their real ids.
+
+        A later batch addresses the nodes and comments an earlier one created
+        by the real ids that batch returned, not by the client ids the
+        commands were built with: docx-studio keeps an asset's client ids for
+        a while and evicts some past 4,096, and a flush can create more.
+
+        Each batch that lands gives the waiting caller its timeout again
+        (``run_sync``), so every batch has the budget its request has. Once
+        the caller has timed out, no further batch is sent: the
+        ``DocxError`` names the commands that were not, and carries the
+        results of those that were.
+        """
+        if len(commands) <= MAX_BATCH_COMMANDS:
+            return self._execute_one_batch(asset_id, commands, change_mode=change_mode, user=user)
+        results: list[Any] = []
+        skipped_by_index: dict[int, dict[str, Any]] = {}
+        applied: list[dict[str, Any]] = []
+        minted: dict[str, str] = {}
+        for start in range(0, len(commands), MAX_BATCH_COMMANDS):
+            chunk = commands[start : start + MAX_BATCH_COMMANDS]
+            if start and call_abandoned():
+                raise DocxError(
+                    f"docx-studio batch not sent: the call timed out after the first {start} "
+                    f"of {len(commands)} commands went out; the other "
+                    f"{len(commands) - start} were not sent",
+                ).with_partial_applied(applied)
+            try:
+                chunk_results, chunk_skipped = self._execute_one_batch(
+                    asset_id, chunk, change_mode=change_mode, user=user, ids=minted
+                )
+            except DocxError as exc:
+                failed: object = getattr(exc, "partial_applied", None)
+                failed_applied = [
+                    {**entry, "index": entry["index"] + start}
+                    for entry in (failed if isinstance(failed, list) else [])
+                    if isinstance(entry, dict) and isinstance(entry.get("index"), int)
+                ]
+                raise exc.with_partial_applied(applied + failed_applied)
+            for offset, result in enumerate(chunk_results):
+                if result is not None:
+                    command = chunk[offset]
+                    applied.append(
+                        {
+                            "index": start + offset,
+                            "type": getattr(command, "type", type(command).__name__),
+                            "result": result,
+                        }
+                    )
+            results.extend(chunk_results)
+            for index, entry in chunk_skipped.items():
+                skipped_by_index[start + index] = {**entry, "index": start + index}
+            minted.update(_minted_ids(chunk_results))
+            note_progress()
+        return results, skipped_by_index
+
+    def _execute_one_batch(
+        self,
+        asset_id: str,
+        commands: list[Command],
+        *,
+        change_mode: str | None = None,
+        user: dict[str, str] | None = None,
+        ids: dict[str, str] | None = None,
+    ) -> tuple[list[Any], dict[int, dict[str, Any]]]:
+        """POST a batch of typed commands, each client id in ``ids`` sent as
+        the real id it maps to (:meth:`execute_batch`).
 
         Returns ``(results, skipped_by_index)``:
 
@@ -897,7 +1007,9 @@ class HttpClient:
         url: str = f"{self._base_url}/docs/{asset_id}/commands"
         body: dict[str, Any] = {
             "client": {"type": "python-sdk", "version": _sdk_version()},
-            "commands": [c.to_dict() for c in commands],
+            "commands": [
+                _with_real_ids(c.to_dict(), ids) if ids else c.to_dict() for c in commands
+            ],
             "return": {"snapshot": False},
         }
         if change_mode is not None:

{athena_python_docx-0.26.0 → athena_python_docx-0.28.0}/docx/client.py

@@ -115,6 +115,13 @@ class Session:
             return float(timeout)
         return DEFAULT_OP_TIMEOUT_SECONDS
 
+    def forget_reads(self) -> None:
+        """The next node read goes to the server (``CommandBuffer.forget_reads``)."""
+        handle = self._doc_handle
+        forget = getattr(getattr(handle, "buffer", None), "forget_reads", None)
+        if callable(forget):
+            forget()
+
     async def open(self) -> None:
         """Construct the HTTP client + buffered doc handle.
 

{athena_python_docx-0.26.0 → athena_python_docx-0.28.0}/docx/errors.py

@@ -129,6 +129,16 @@ class NotNumberedListItemError(DocxError, ValueError):
     """
 
 
+class FieldRunWriteError(DocxError, ValueError):
+    """Raised for a write to a run of a Word field that the SDK refuses:
+    text written to a field character or field code run (python-docx's write
+    replaces the run's ``w:fldChar`` or ``w:instrText`` and breaks the field),
+    and content appended to any of a field's runs. The message names the
+    field. Subclasses :class:`ValueError` so ``except ValueError`` also
+    catches it.
+    """
+
+
 class SessionError(DocxError):
     """Raised when the DOCX Studio SDK session cannot be established or used."""
 

{athena_python_docx-0.26.0 → athena_python_docx-0.28.0}/docx/text/hyperlink.py

@@ -122,15 +122,15 @@ class Hyperlink:
         Mirrors python-docx 1.x: a hyperlink's ``text`` is the visible
         anchor text, which for a multi-run hyperlink is the
         concatenation of every child run's text, each read as
-        :attr:`Run.text` reads it; a tracked deletion's run is left out, as
-        Word's final view shows the link.
+        :attr:`Run.text` reads it (a note reference as none); a tracked
+        deletion's run is left out, as Word's final view shows the link.
         """
-        from docx.text.paragraph import _deleted, _symbol_font, _word_text
+        from docx.text.paragraph import _deleted, _note_reference, _symbol_font, _word_text
 
         parts: list[str] = []
         for run_data, _ in self._segments:
             t = run_data.get("text")
-            if isinstance(t, str) and not _deleted(run_data):
+            if isinstance(t, str) and not _deleted(run_data) and not _note_reference(run_data):
                 parts.append(_word_text(t, _symbol_font(run_data)))
         return "".join(parts)