athena-python-docx 0.42.0__tar.gz → 0.43.0__tar.gz

{athena_python_docx-0.42.0 → athena_python_docx-0.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.42.0
+Version: 0.43.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.42.0 → athena_python_docx-0.43.0}/docx/__init__.py

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

{athena_python_docx-0.42.0 → athena_python_docx-0.43.0}/docx/_buffer.py

@@ -29,6 +29,7 @@ alive.
 from __future__ import annotations
 
 import copy
+import dataclasses
 import json
 import sys
 import threading
@@ -58,6 +59,7 @@ from docx.errors import DocxError, DocxUnsupportedCommandError, FlushAllError
 def _apply_proxy_id_rewrites(
     results: list[Any],
     proxy_id_refs: "dict[str, list[tuple[object, str]]]",
+    resolved: "dict[str, str] | None" = None,
 ) -> None:
     """Walk ``results`` and rewrite registered proxy ids from client UUIDs
     to the real DOCX Studio ids the applier echoed back.
@@ -79,7 +81,7 @@ def _apply_proxy_id_rewrites(
     ``clientIdMap`` rewrite still resolves them server-side on the
     *next* call.
     """
-    if not proxy_id_refs:
+    if not proxy_id_refs and resolved is None:
         return
     for result in results:
         if not isinstance(result, dict):
@@ -92,6 +94,8 @@ def _apply_proxy_id_rewrites(
             real = result.get(real_key)
             if not (isinstance(cli, str) and isinstance(real, str)):
                 continue
+            if resolved is not None:
+                resolved[cli] = real
             refs = proxy_id_refs.pop(cli, [])
             for proxy, attr in refs:
                 try:
@@ -104,6 +108,44 @@ def _apply_proxy_id_rewrites(
                     pass
 
 
+_MINTED_ID_FIELDS: frozenset[str] = frozenset({"client_node_id", "client_entity_id"})
+
+
+def _with_resolved_ids(value: Any, resolved: "dict[str, str]") -> Any:
+    """``value`` with every string that is a client id in ``resolved`` swapped
+    for its real id; the same object when nothing changed."""
+    if isinstance(value, str):
+        return resolved.get(value, value)
+    if isinstance(value, dict):
+        out = {k: _with_resolved_ids(v, resolved) for k, v in value.items()}
+        return value if all(out[k] is value[k] for k in value) else out
+    if isinstance(value, list):
+        items = [_with_resolved_ids(v, resolved) for v in value]
+        return value if all(a is b for a, b in zip(items, value)) else items
+    return value
+
+
+def _resolve_client_ids(cmd: Command, resolved: "dict[str, str]") -> None:
+    """Point ``cmd`` at the real ids of the creates an earlier batch landed.
+
+    A proxy's own id is rewritten when its create's batch returns, but a copy
+    of the client id taken before then (a ``Run``'s paragraph id, the id
+    ``add_paragraph`` promotes to a list item) still names the client id. Only
+    the docx-studio pod that applied the create can resolve that id when the
+    replicas share no client-id map, so a later batch that reaches another pod
+    fails with ``block "p_…" not found``.
+    """
+    if not resolved or not dataclasses.is_dataclass(cmd):
+        return
+    for f in dataclasses.fields(cmd):
+        if f.name in _MINTED_ID_FIELDS:
+            continue
+        value = getattr(cmd, f.name)
+        new = _with_resolved_ids(value, resolved)
+        if new is not value:
+            setattr(cmd, f.name, new)
+
+
 _WRITES_UNAPPLIED = "_docx_writes_unapplied"
 
 
@@ -551,6 +593,10 @@ 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]]] = {}
+        # client id → real id of every create a batch landed, so a command
+        # that still names a client id is sent with the real one
+        # (:func:`_resolve_client_ids`).
+        self._resolved_client_ids: dict[str, str] = {}
         # The last command's ``GetNodeById`` key, result and time, while
         # nothing has been sent or buffered after it (see :meth:`call`), for a
         # docx-studio that gives no version.
@@ -866,6 +912,7 @@ class CommandBuffer:
                 user = None if self._user is None else dict(self._user)
             version = self._version_request()
             sent_at = _now()
+            self._resolve_drained(cmds)
             try:
                 outcome = self._client.execute_batch(
                     self._asset_id,
@@ -944,6 +991,7 @@ class CommandBuffer:
         proxy's ``_node_id`` in-place.
         """
         self.ensure_usable()
+        _resolve_client_ids(cmd, self._resolved_client_ids)
         # A write whose text holds a character XML does not allow raises
         # python-docx's ValueError here, before anything is sent: every command
         # comes through, a path-proxy op's and a direct ``send_command``'s.
@@ -1073,6 +1121,7 @@ class CommandBuffer:
             self._proxy_id_refs = {}
         if not pending:
             return []
+        self._resolve_drained(pending)
         try:
             results, _skipped_by_index = self._client.execute_batch(
                 self._asset_id,
@@ -1088,7 +1137,9 @@ class CommandBuffer:
             # batch ships REAL ids for the survivors (vs. dead client
             # UUIDs that would cascade into another "Block not found").
             # See ``_apply_proxy_id_rewrites`` for the full rationale.
-            _apply_proxy_id_rewrites(_extract_partial_results(exc), proxy_id_refs)
+            _apply_proxy_id_rewrites(
+                _extract_partial_results(exc), proxy_id_refs, self._resolved_client_ids
+            )
             _ptc_emit_end_batch(pending, is_error=True)
             _unapplied_writes(exc)
             raise
@@ -1099,7 +1150,7 @@ class CommandBuffer:
         finally:
             _forget_reads_of_others(self)
         _ptc_emit_end_batch(pending, is_error=False)
-        _apply_proxy_id_rewrites(results, proxy_id_refs)
+        _apply_proxy_id_rewrites(results, proxy_id_refs, self._resolved_client_ids)
         return results
 
     def close(self) -> None:
@@ -1126,6 +1177,14 @@ class CommandBuffer:
 
     # ----- internals -----
 
+    def _resolve_drained(self, cmds: "list[Command]") -> None:
+        """Point ``cmds``, about to be sent under ``_post_lock``, at the real
+        ids every earlier batch returned: one queued while the idle timer's
+        batch with its create was still in flight missed that id in
+        :meth:`call`."""
+        for queued in cmds:
+            _resolve_client_ids(queued, self._resolved_client_ids)
+
     def _eager_flush_with(self, cmd: Command) -> Any:
         """Drain pending + run ``cmd`` in one batch; return cmd's result.
 
@@ -1151,6 +1210,7 @@ class CommandBuffer:
             self._proxy_id_refs = {}
             writes = self._writes
         all_cmds: list[Command] = [*pending, cmd]
+        self._resolve_drained(all_cmds)
         trailing_index = len(all_cmds) - 1
         # A batch that answers a read asks for the document's version (a
         # docx-studio that predates it ignores the question).
@@ -1175,7 +1235,9 @@ class CommandBuffer:
             # ``table.cell(0, 0)`` → ``tables.get``), so a failure on
             # the trailing ``cmd`` would otherwise abandon every
             # buffered Create's rewrite at once.
-            _apply_proxy_id_rewrites(_extract_partial_results(exc), proxy_id_refs)
+            _apply_proxy_id_rewrites(
+                _extract_partial_results(exc), proxy_id_refs, self._resolved_client_ids
+            )
             _ptc_emit_end_batch([cmd], is_error=True)
             if pending:
                 self._settle_writes_of_failed_read(
@@ -1198,7 +1260,7 @@ class CommandBuffer:
         # Proxy-id rewrites still run for the buffered prefix that DID apply —
         # the trailing skip (if any) doesn't strand the supported Creates that
         # flushed alongside it.
-        _apply_proxy_id_rewrites(results, proxy_id_refs)
+        _apply_proxy_id_rewrites(results, proxy_id_refs, self._resolved_client_ids)
         # This is the AWAITED-result path: the caller is about to read the
         # trailing command's result. If the server skipped that command
         # (capability gap), there is no result to return — returning some
@@ -1260,11 +1322,13 @@ class CommandBuffer:
             # ``MAX_BATCH_COMMANDS``: those a failed request's earlier ones
             # applied keep their ids, as a flush's do, and only the rest are
             # the failure's unapplied writes.
-            _apply_proxy_id_rewrites(_extract_partial_results(again), proxy_id_refs)
+            _apply_proxy_id_rewrites(
+                _extract_partial_results(again), proxy_id_refs, self._resolved_client_ids
+            )
             _ptc_emit_end_batch(pending, is_error=True)
             raise _unapplied_writes(again) from exc
         _ptc_emit_end_batch(pending, is_error=False)
-        _apply_proxy_id_rewrites(results, proxy_id_refs)
+        _apply_proxy_id_rewrites(results, proxy_id_refs, self._resolved_client_ids)
         _as_the_read_s_own_failure(exc, failed)
 
     def _reset_timer_locked(self) -> None:

{athena_python_docx-0.42.0 → athena_python_docx-0.43.0}/docx/_http.py

@@ -38,6 +38,20 @@ _API_KEY_ENV = "ATHENA_DOCX_API_KEY"  # noqa: S105
 _AGORA_BASE_URL_ENV = "ATHENA_AGORA_BASE_URL"
 
 
+def _resolve_api_key(api_key: str | None) -> str | None:
+    """The key a create or upload sends: ``api_key``, else the studio key.
+
+    ``ATHENA_DOCX_API_KEY`` comes first, as on every other call this SDK
+    makes. Both create paths land outside Athena's public API (docx-studio's
+    ``/docs/empty``, agora's ``/api/docx-studio/assets``), and inside an Athena
+    session VM or computer ``ATHENA_API_KEY`` is a credential only that public
+    API (``/api/v0``) accepts. ``ATHENA_API_KEY`` stays the fallback for an
+    environment that sets no studio key (local use with one personal key).
+    The new document is owned by the user the key belongs to.
+    """
+    return api_key or os.environ.get(_API_KEY_ENV) or os.environ.get("ATHENA_API_KEY")
+
+
 def _derive_agora_base_url(docx_base_url: str) -> str | None:
     """Best-effort derive an Agora base URL from a docx-studio base URL.
 
@@ -99,11 +113,11 @@ def create_empty_document(
             Falls back to ``$ATHENA_DOCX_BASE_URL``.
         api_key: Athena API key (PropelAuth user API key) or PropelAuth
             access token. Sent as ``Authorization: Bearer <api_key>``.
-            Falls back to ``$ATHENA_DOCX_API_KEY``.
+            Falls back to ``$ATHENA_DOCX_API_KEY``, then ``$ATHENA_API_KEY``.
         name: Optional display title.
         parent_folder_id: Optional parent folder; defaults to workspace root.
-        workspace_id: Optional workspace UUID; defaults to caller's
-            current workspace.
+        workspace_id: Optional workspace UUID; defaults to the sandbox run's
+            ATHENA_WORKSPACE_ID, then the caller's current workspace.
         timeout: Request timeout in seconds.
 
     Returns:
@@ -115,17 +129,7 @@ def create_empty_document(
         DocxError: any other 4xx/5xx from the server.
     """
     resolved_base: str | None = base_url or os.environ.get(_BASE_URL_ENV)
-    # Create must authenticate as the REAL user so the new asset's ``created_by``
-    # is the user, not a service identity. ``ATHENA_API_KEY`` is the canonical
-    # per-user Athena key (a local API key in BYO/SSO mode that agora resolves to
-    # the real user); the docx-studio studio key (``ATHENA_DOCX_API_KEY``) is a
-    # deployment service credential used only for studio access-checks on
-    # EXISTING assets, and agora's create gate rejects it (no backing user). So
-    # prefer the user key here; only fall back to the studio key for callers that
-    # set just that.
-    resolved_key: str | None = (
-        api_key or os.environ.get("ATHENA_API_KEY") or os.environ.get(_API_KEY_ENV)
-    )
+    resolved_key: str | None = _resolve_api_key(api_key)
 
     if not resolved_base:
         raise SessionError(
@@ -141,17 +145,22 @@ def create_empty_document(
         )
 
     url: str = resolved_base.rstrip("/") + "/docs/empty"
-    body: dict[str, str] = {}
+    # The document is born as its creator's: its first write is signed as the
+    # caller, with the agent run's attributions when the script runs in one
+    # (``X-Custom-Attributions``), so the run's turn replay starts with it.
+    body: dict[str, str] = {"seedAuthor": "requester"}
     if name is not None:
         body["name"] = name
     if parent_folder_id is not None:
         body["parentFolderId"] = parent_folder_id
-    if workspace_id is not None:
-        body["workspaceId"] = workspace_id
+    resolved_workspace = workspace_id or os.environ.get("ATHENA_WORKSPACE_ID")
+    if resolved_workspace:
+        body["workspaceId"] = resolved_workspace
 
     # Lazy import — _http is loaded lazily by Document.create(), so the
     # package is fully initialized by the time we reach this code.
     from docx import __version__
+    from docx._http_doc import _delegation_headers
 
     payload: bytes = json.dumps(body).encode("utf-8")
     req = urllib.request.Request(  # noqa: S310
@@ -163,6 +172,7 @@ def create_empty_document(
             "Authorization": f"Bearer {resolved_key}",
             "Accept": "application/json",
             "User-Agent": f"athena-python-docx/{__version__}",
+            **_delegation_headers(),
         },
     )
 
@@ -227,6 +237,7 @@ def upload_document(
     name: str | None = None,
     parent_folder_id: str | None = None,
     workspace_id: str | None = None,
+    source_asset_id: str | None = None,
     timeout: float = 120.0,
 ) -> UploadAssetResult:
     """Upload a local ``.docx`` to agora and create a new Word document asset.
@@ -242,11 +253,12 @@ def upload_document(
         agora_base_url: Explicit Agora base URL. Falls back to
             ``$ATHENA_AGORA_BASE_URL`` and finally to a host substitution
             of ``docx-studio`` → ``agora`` against ``docx_base_url``.
-        api_key: Athena API key. Falls back to ``$ATHENA_DOCX_API_KEY``.
+        api_key: Athena API key. Falls back to ``$ATHENA_DOCX_API_KEY``, then
+            ``$ATHENA_API_KEY``.
         name: Optional asset title (defaults to the file's stem).
         parent_folder_id: Optional parent folder for the new asset.
-        workspace_id: Optional workspace UUID; defaults to the caller's
-            current workspace as resolved by Agora.
+        workspace_id: Optional workspace UUID; defaults to the sandbox run's
+            ATHENA_WORKSPACE_ID, then the caller's current workspace in Agora.
         timeout: Request timeout in seconds (uploads can be slow for big
             decks/templates).
 
@@ -262,17 +274,7 @@ def upload_document(
     import os
 
     resolved_docx_base: str | None = docx_base_url or os.environ.get(_BASE_URL_ENV)
-    # Create must authenticate as the REAL user so the new asset's ``created_by``
-    # is the user, not a service identity. ``ATHENA_API_KEY`` is the canonical
-    # per-user Athena key (a local API key in BYO/SSO mode that agora resolves to
-    # the real user); the docx-studio studio key (``ATHENA_DOCX_API_KEY``) is a
-    # deployment service credential used only for studio access-checks on
-    # EXISTING assets, and agora's create gate rejects it (no backing user). So
-    # prefer the user key here; only fall back to the studio key for callers that
-    # set just that.
-    resolved_key: str | None = (
-        api_key or os.environ.get("ATHENA_API_KEY") or os.environ.get(_API_KEY_ENV)
-    )
+    resolved_key: str | None = _resolve_api_key(api_key)
     resolved_agora_base: str | None = (
         agora_base_url
         or os.environ.get(_AGORA_BASE_URL_ENV)
@@ -308,15 +310,28 @@ def upload_document(
     with open(docx_path, "rb") as f:
         file_bytes: bytes = f.read()
 
-    create_body: dict[str, str] = {"name": title}
+    # The document is born holding the uploaded file: the create seeds no
+    # template (``seed_template``), and the import below is its first write,
+    # signed as the caller with the agent run's attributions when the script
+    # runs in one (``seed_author``, ``X-Custom-Attributions``). An agora that
+    # predates both seeds the template, which the overwrite import replaces.
+    create_body: dict[str, str | bool] = {
+        "name": title,
+        "seed_author": "requester",
+        "seed_template": False,
+    }
+    if source_asset_id is not None:
+        create_body["source_asset_id"] = source_asset_id
     if parent_folder_id is not None:
         create_body["parent_folder_id"] = parent_folder_id
-    if workspace_id is not None:
-        create_body["workspace_id"] = workspace_id
+    resolved_workspace = workspace_id or os.environ.get("ATHENA_WORKSPACE_ID")
+    if resolved_workspace:
+        create_body["workspace_id"] = resolved_workspace
 
     create_url: str = resolved_agora_base.rstrip("/") + "/api/docx-studio/assets"
 
     from docx import __version__
+    from docx._http_doc import _delegation_headers
 
     req = urllib.request.Request(  # noqa: S310
         create_url,
@@ -327,6 +342,7 @@ def upload_document(
             "Authorization": f"Bearer {resolved_key}",
             "Accept": "application/json",
             "User-Agent": f"athena-python-docx/{__version__}",
+            **_delegation_headers(),
         },
     )
 
@@ -374,6 +390,7 @@ def upload_document(
     import_body = {
         "docx_base64": base64.b64encode(file_bytes).decode("ascii"),
         "overwrite": True,
+        "seed_author": "requester",
     }
     import_req = urllib.request.Request(  # noqa: S310
         import_url,
@@ -384,6 +401,7 @@ def upload_document(
             "Authorization": f"Bearer {resolved_key}",
             "Accept": "application/json",
             "User-Agent": f"athena-python-docx/{__version__}",
+            **_delegation_headers(),
         },
     )
 

{athena_python_docx-0.42.0 → athena_python_docx-0.43.0}/docx/_http_doc.py

@@ -33,6 +33,7 @@ from __future__ import annotations
 import dataclasses
 import json
 import os
+import re
 import urllib.parse
 import warnings
 from typing import Any, TypedDict
@@ -477,6 +478,9 @@ _PARAGRAPH_TARGETING_COMMANDS: frozenset[str] = frozenset(
 )
 
 
+# The id ``Document._mint_client_node_id`` gives a node it creates.
+_SDK_MINTED_ID = re.compile(r"[a-z]+_[0-9a-f]{12}")
+
 _CELL_PARAGRAPH_HINT: str = (
     "\n\nHint: DOCX Studio 1.8.1 cannot format paragraphs nested inside "
     "table cells via SetParagraphAlignment / SetParagraphStyle / "
@@ -534,6 +538,15 @@ _TABLE_QUERY_COMMANDS: frozenset[str] = frozenset(
 )
 
 
+_SDK_CLIENT_ID_HINT: str = (
+    "\n\nHint: this id is one the SDK minted for a block it created "
+    "(``p_xxxxxxxxxxxx``), not one docx-studio assigned. The create that "
+    "minted it failed or was discarded in an earlier batch, or it belongs "
+    "to a previous execution. This is not a table-cell problem: re-read "
+    "the block (``doc.paragraphs`` / ``doc.tables``) and use the proxy it "
+    "returns, or create the block again."
+)
+
 _TABLE_CLIENT_ID_HINT: str = (
     "\n\nHint: this looks like a stale client-side table UUID "
     "(``t_xxxxxxxxxxxx``). Either an earlier batch in this execution "
@@ -882,8 +895,12 @@ def _http_post_json(
                     isinstance(cmd_type, str) and cmd_type in _PARAGRAPH_TARGETING_COMMANDS
                 )
                 table_query = isinstance(cmd_type, str) and cmd_type in _TABLE_QUERY_COMMANDS
-                if _missing_block_id(err_obj.get("message")) in header_footer_block_ids:
+                missing = _missing_block_id(err_obj.get("message"))
+                if missing in header_footer_block_ids:
                     hint = _HEADER_FOOTER_PARAGRAPH_HINT
+                elif missing is not None and _SDK_MINTED_ID.fullmatch(missing):
+                    # A block this SDK created, not a cell's own paragraph.
+                    hint = _SDK_CLIENT_ID_HINT
                 elif paragraph_targeting:
                     hint = _CELL_PARAGRAPH_HINT
                 elif table_query:

{athena_python_docx-0.42.0 → athena_python_docx-0.43.0}/docx/document.py

@@ -259,6 +259,7 @@ class Document:
         track_revisions: bool = False,
         docx: str | None = None,
         agora_base_url: str | None = None,
+        source_asset_id: str | None = None,
     ) -> "Document":
         """Create a new Word document asset and return an opened Document.
 
@@ -279,9 +280,14 @@ class Document:
             base_url: docx-studio API base URL. Falls back to
                 ``$ATHENA_DOCX_BASE_URL``.
             api_key: Athena API key (PropelAuth user API key) or
-                access token. Falls back to ``$ATHENA_DOCX_API_KEY``.
+                access token. Falls back to ``$ATHENA_DOCX_API_KEY``, then
+                ``$ATHENA_API_KEY``, as every other call does; the upload path
+                (``docx=``) sends the same key to agora.
             parent_folder_id: Optional parent folder; defaults to
-                workspace root.
+                the source document's folder when source_asset_id is set,
+                otherwise workspace root.
+            source_asset_id: Original asset when creating a copy from an export.
+                Agora checks source access and destination edit permission.
             workspace_id: Optional workspace UUID; defaults to the
                 caller's current workspace as resolved by Agora.
             docx: Optional path to a local ``.docx`` file. When provided,
@@ -325,6 +331,7 @@ class Document:
                     name=name,
                     parent_folder_id=parent_folder_id,
                     workspace_id=workspace_id,
+                    source_asset_id=source_asset_id,
                 )
                 asset_id = upload_result["asset_id"]
             else:

{athena_python_docx-0.42.0 → athena_python_docx-0.43.0}/pyproject.toml

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

{athena_python_docx-0.42.0 → athena_python_docx-0.43.0}/tests/live/fixture_scripts.py

@@ -752,6 +752,44 @@ FIXTURE_SCRIPTS: list[FixtureScript] = [
             'row.cells[0].text = "Delta"\n'
         ),
     ),
+    FixtureScript(
+        # Writes to a table merged the legacy way (w:hMerge), which python-docx
+        # reads as written, each w:tc its own cell: text added after the
+        # nested table of a merge's first cell, a merge's first cell and a
+        # cell that continues it rewritten, bold on a row's runs, and a row
+        # added. The export writes each cell's w:hMerge back, as python-docx
+        # keeps it.
+        name="fixture-tables-horizontal-merges-writes",
+        fixture="tables-horizontal-merges",
+        script=(
+            "table = doc.tables[0]\n"
+            'table.cell(0, 0).paragraphs[-1].add_run("Issued")\n'
+            'table.cell(2, 0).text = "Merged text rewritten"\n'
+            'table.cell(2, 1).text = "Continued"\n'
+            "for run in table.cell(1, 3).paragraphs[0].runs:\n"
+            "    run.bold = True\n"
+            "row = table.add_row()\n"
+            'row.cells[0].text = "Beta"\n'
+        ),
+    ),
+    FixtureScript(
+        # Writes to tables whose rows of one cell set no span in a grid of two
+        # columns: python-docx reads such a row's one cell as written, and
+        # writes it so; a row added after one, and a column added, as
+        # python-docx adds them (a w:tc in every row).
+        name="fixture-tables-implied-span-writes",
+        fixture="tables-implied-span",
+        script=(
+            "form = doc.tables[0]\n"
+            'form.rows[2].cells[0].text = "Reviewed"\n'
+            'form.rows[4].cells[0].paragraphs[0].add_run(" (internal)")\n'
+            'form.rows[5].cells[1].text = "Closed"\n'
+            "closing = doc.tables[1]\n"
+            "row = closing.add_row()\n"
+            'row.cells[0].text = "Total"\n'
+            "closing.add_column(Pt(72))\n"
+        ),
+    ),
     FixtureScript(
         # Writes to a footer part written with a header's root element and to
         # a header part written with a footer's: python-docx edits the part's

{athena_python_docx-0.42.0 → athena_python_docx-0.43.0}/tests/test_block_not_found_error.py

@@ -123,6 +123,30 @@ def test_insert_block_not_found_carries_cell_hint() -> None:
     )
 
 
+def test_sdk_minted_id_block_not_found_names_the_stale_client_id() -> None:
+    """A miss on an id the SDK minted (``p_<12 hex>``) is a create that never
+    landed, not a cell paragraph: the hint says so instead of the cell one."""
+
+    def _capture(url: str, **kwargs: Any) -> _FakeResponse:  # noqa: ARG001
+        return _FakeResponse(
+            status_code=207,
+            body=_partial_failure_body(
+                cmd_type="Insert",
+                message='Block "p_7b3a2a6afbf3" not found.',
+            ),
+        )
+
+    client = HttpClient(base_url="https://example.com", api_key="bg_key")
+
+    with patch.object(client._session, "post", side_effect=_capture):
+        with pytest.raises(BlockNotFoundError) as exc_info:
+            _execute_setalignment(client)
+
+    msg = str(exc_info.value)
+    assert "the SDK minted" in msg
+    assert "cell.add_paragraph" not in msg
+
+
 def test_non_paragraph_command_block_not_found_skips_hint() -> None:
     """A ``Block ... not found`` miss on a non-paragraph-targeting
     command (a stale image id from ``SetImageSize``, a deleted list

{athena_python_docx-0.42.0 → athena_python_docx-0.43.0}/tests/test_buffer.py

@@ -670,3 +670,89 @@ def test_discard_all_skips_stale_buffers() -> None:
             buf.close()
         finally:
             begin_execution(None)
+
+
+class _EchoingClient(_FakeClient):
+    """Answers each create with its real id, as docx-studio echoes it."""
+
+    def execute_batch(
+        self, asset_id: str, commands: list[Command], **kw: Any
+    ) -> tuple[list[Any], dict[int, dict[str, Any]]]:
+        super().execute_batch(asset_id, commands, **kw)
+        results: list[Any] = []
+        for cmd in commands:
+            cli = getattr(cmd, "client_node_id", None)
+            results.append({"client_node_id": cli, "real_node_id": f"REAL-{cli}"} if cli else {})
+        return results, {}
+
+
+def test_a_client_id_copied_before_its_create_landed_is_sent_as_the_real_id() -> None:
+    """``add_paragraph(style="List Bullet")`` and ``p.add_run().add_break()``
+    keep the paragraph's client id; when a read flushed the create first, the
+    next batch may reach a docx-studio pod that never minted it."""
+    fake = _EchoingClient()
+    buf = CommandBuffer(fake, "asset_1", auto_flush_seconds=0.0)
+    buf.call(CreateParagraph(text="one", at={"kind": "documentEnd"}, client_node_id="p_abc"))
+    buf.flush()
+    buf.call(
+        Replace(
+            target={
+                "kind": "selection",
+                "start": {"kind": "text", "blockId": "p_abc", "offset": 0},
+            },
+            text="y",
+        )
+    )
+    buf.call(
+        CreateParagraph(
+            text="two", at={"kind": "after", "target": {"nodeId": "p_abc"}}, client_node_id="p_def"
+        )
+    )
+    buf.flush()
+    replace, create = fake.batches[1]
+    assert replace.target == {
+        "kind": "selection",
+        "start": {"kind": "text", "blockId": "REAL-p_abc", "offset": 0},
+    }
+    assert create.at == {"kind": "after", "target": {"nodeId": "REAL-p_abc"}}
+    assert create.client_node_id == "p_def"
+    buf.close()
+
+
+class _HeldEchoingClient(_EchoingClient):
+    """An echoing client whose first batch waits for ``release``."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.sent = threading.Event()
+        self.release = threading.Event()
+
+    def execute_batch(
+        self, asset_id: str, commands: list[Command], **kw: Any
+    ) -> tuple[list[Any], dict[int, dict[str, Any]]]:
+        if not self.batches:
+            self.sent.set()
+            assert self.release.wait(5)
+        return super().execute_batch(asset_id, commands, **kw)
+
+
+def test_a_command_queued_while_its_create_is_in_flight_is_sent_as_the_real_id() -> None:
+    """The idle timer's batch carries the create; an edit queued before that
+    batch answers still goes out naming the paragraph by its real id."""
+    fake = _HeldEchoingClient()
+    buf = CommandBuffer(fake, "asset_1", auto_flush_seconds=0.0)
+    buf.call(CreateParagraph(text="one", at={"kind": "documentEnd"}, client_node_id="p_abc"))
+    in_flight = threading.Thread(target=buf.flush)
+    in_flight.start()
+    assert fake.sent.wait(5)
+    buf.call(
+        CreateParagraph(
+            text="two", at={"kind": "after", "target": {"nodeId": "p_abc"}}, client_node_id="p_def"
+        )
+    )
+    fake.release.set()
+    in_flight.join(5)
+    buf.flush()
+    (create,) = fake.batches[1]
+    assert create.at == {"kind": "after", "target": {"nodeId": "REAL-p_abc"}}
+    buf.close()