athena-python-docx 0.23.0__tar.gz → 0.25.0__tar.gz

{athena_python_docx-0.23.0 → athena_python_docx-0.25.0}/AGENTS.md

@@ -268,7 +268,14 @@ Issue numbers reference `python-openxml/python-docx`.
   inside_horizontal=, inside_vertical=)`** + **`_Cell.borders`**
   property + **`Table.set_borders(...)`** — per-edge border control.
   python-docx issue #201 (5 👍), #1238 demand a cell-borders API.
-  Routes through `SetCellBorders` / `SetTableBorders`.
+  Routes through `SetCellBorders` / `SetTableBorders`. Each edge is
+  `{"style", "size_pt", "color", "space"}` (points; `sizePt` also
+  accepted) or `"single 0.5pt #D9D9D9"`; the SDK validates it and sends
+  `{style, sizePt, color: "#RRGGBB", space}`. Any other key (`val`, `sz`,
+  `size`, `width`) raises `ValueError` naming the accepted form, and
+  docx-studio refuses it too (`InvalidBorderSpec`): such edges were once
+  stored without their size and colour, and one with no style broke every
+  later export of the document.
 
 - **`_Cell.set_shading(*, fill=, pattern=, color=)`** +
   **`_Cell.shading`** property — cell fill / shading. python-docx
@@ -370,7 +377,29 @@ Issue numbers reference `python-openxml/python-docx`.
   include_revisions=False) -> bytes`** — render to PDF. python-docx
   issue #113 was closed as
   wontfix upstream but the request keeps recurring. Routes through
-  `ExportPDF` (DOCX Studio handles the actual conversion).
+  `ExportPDF` (0.25.0+ opens the session first and sends buffered edits in
+  the same request). DOCX Studio lays the document out with the engine the
+  editor paginates with and paints every page onto Skia's PDF backend: a
+  vector PDF with selectable text in embedded fonts that matches
+  `render_page` — no LibreOffice anywhere, so never install it in a sandbox.
+  `quality` is `"draft"` (pictures as JPEG), `"standard"` (default) or
+  `"high"`; `include_revisions=True` shows tracked changes as markup (the
+  default renders them accepted); `destination` writes a local file and
+  refuses asset ids and URLs with `ValueError`. A deployment that cannot
+  produce the PDF raises `DocxUnsupportedCommandError` naming the reason.
+  `GET /docs/:id/export.pdf` serves the same PDF read-only (VIEW gate).
+
+- **`Document.render_page(page_number=1, scale=2, as_pil=False)`** +
+  **`Document.screenshot_to_path(path, page=1, scale=2) -> Path`** +
+  **`Document.page_count`** (0.25.0+) — look at the document as the editor
+  lays it out: one page (numbered from 1) as PNG bytes or a Pillow image,
+  written to disk, and the page count. Names follow
+  athena-python-pptx's `slide.render(scale=2, as_pil=True)` and
+  athena-openpyxl's `Worksheet.screenshot_to_path`. Buffered edits flush
+  first. Backed by docx-studio's read-only `GET /docs/:id/pages/:n.png` and
+  `GET /docs/:id/layout.json` (VIEW gate, the SDK's API key); a page past
+  the end raises `PageOutOfRangeError` (an `IndexError`) carrying
+  `page_count`.
 
 - **`Document.clear()`** (0.14.0+) — empty the document body so subsequent
   writes start from a clean slate. python-docx has no equivalent (it
@@ -754,12 +783,19 @@ architecture or a DOCX Studio constraint:
   cheaply enumerate every cell. `(0,0)` and in-range negative indices
   behave identically to upstream.
 
-- **`BaseStyle.style_id` returns the display name for built-ins** (so
-  `style_id == name`). The SDK is HTTP-only and can't read `styles.xml`
-  to recover the OOXML styleId (`"Heading 1"` → `"Heading1"`); the wire
-  format also uses the display name as the style id. Consequently
-  `get_by_id("Heading1", …)` / `"Heading1" in styles` won't resolve the
-  OOXML-id form (use the display name).
+- **Unknown paragraph style names raise only when Word has no such
+  built-in.** Style names and ids follow python-docx: `.name` is the UI
+  name (`"Heading 1"`), `.style_id` the id (`"Heading1"`), read from the
+  document's style table (docx-studio `Info` with `includeStyles`, fetched
+  once per session in `docx/styles/_table.py`). A style set by name or id
+  is sent as the document's id, and an unstyled paragraph reads as the
+  default paragraph style. `paragraph.style = …` raises `KeyError` for a
+  name the document defines no style for, like python-docx — except Word's
+  built-in styles (`"Heading 4"`, `"List Bullet"`, `"Title"`…), which many
+  templates never write into `styles.xml` until used. Those are sent by
+  their Word id; Word and docx-studio apply the built-in definition. Against
+  an older docx-studio (no style table) a built-in name is sent as its id
+  and anything else as given.
 
 - **`Document.add_table(rows, cols)` requires `rows >= 1` and
   `cols >= 1`.** Upstream allows a 0-row/0-col grid you later populate,

{athena_python_docx-0.23.0 → athena_python_docx-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.23.0
+Version: 0.25.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.23.0 → athena_python_docx-0.25.0}/docx/__init__.py

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

{athena_python_docx-0.23.0 → athena_python_docx-0.25.0}/docx/_buffer.py

@@ -341,6 +341,10 @@ class CommandBuffer:
         self._asset_id: str = asset_id
         self._pending: list[Command] = []
         self._lock: threading.RLock = threading.RLock()
+        # Held for the whole of a flush (drain + POST), so batches reach the
+        # server one at a time and in order, and a flush returns only once
+        # every batch taken before it has been delivered.
+        self._post_lock: threading.RLock = threading.RLock()
         self._timer: threading.Timer | None = None
         self._auto_flush_seconds: float = auto_flush_seconds
         self._closed: bool = False
@@ -532,6 +536,14 @@ class CommandBuffer:
         proxies pick up real ids without the caller ever seeing the
         UUID swap.
         """
+        # One batch in flight at a time: a flush that finds the queue empty
+        # still waits for a batch the idle timer already took and is posting,
+        # so a read that follows (a query, a page render) sees those edits and
+        # a failure of that batch is raised here.
+        with self._post_lock:
+            return self._flush_in_order()
+
+    def _flush_in_order(self) -> list[Any]:
         self._assert_current_execution()
         self._raise_deferred_flush_error()
         with self._lock:
@@ -599,7 +611,12 @@ class CommandBuffer:
         still get their real ids written back via the same flush-time
         rewrite that :meth:`flush` does.
         """
+        with self._post_lock:
+            return self._eager_flush_in_order(cmd)
+
+    def _eager_flush_in_order(self, cmd: Command) -> Any:
         self._assert_current_execution()
+        self._raise_deferred_flush_error()
         with self._lock:
             self._cancel_timer_locked()
             pending = self._pending

{athena_python_docx-0.23.0 → athena_python_docx-0.25.0}/docx/_http_doc.py

@@ -31,15 +31,16 @@ from __future__ import annotations
 
 import json
 import os
+import urllib.parse
 import warnings
-from typing import Any
+from typing import Any, TypedDict
 
 import requests
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
 from docx._buffer import CommandBuffer
-from docx._timeouts import timeout_for_commands
+from docx._timeouts import DEFAULT_OP_TIMEOUT_SECONDS, timeout_for_commands
 from docx.commands import (
     BlocksList,
     BookmarksGet,
@@ -177,6 +178,7 @@ from docx.errors import (
     DocxUnsupportedCommandWarning,
     NotFoundError,
     SessionError,
+    _missing_block_id,
 )
 
 
@@ -338,6 +340,19 @@ _TABLE_CLIENT_ID_HINT: str = (
 )
 
 
+_HEADER_FOOTER_PARAGRAPH_HINT: str = (
+    "\n\nHint: this paragraph is in a header or footer (``section.header`` / "
+    "``section.footer``), not in a table cell. docx-studio found no "
+    "paragraph with this id: the header/footer part that held it was "
+    "deleted, or the docx-studio server predates run and paragraph edits "
+    "in headers and footers. Add the paragraph again with "
+    "``section.footer.add_paragraph(text)`` (or ``section.header``) and edit "
+    "the paragraph it returns; until the server supports those edits, pass "
+    "the paragraph's full text to ``add_paragraph`` and set only its style "
+    "and alignment."
+)
+
+
 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
@@ -446,7 +461,9 @@ def _build_retry_session() -> requests.Session:
         "other": 0,
         "backoff_factor": 2.0,
         "status_forcelist": (429, 502, 503, 504),
-        "allowed_methods": frozenset(["POST"]),
+        # GET serves only the read-only render routes (page PNGs, layout),
+        # which are always safe to retry.
+        "allowed_methods": frozenset(["POST", "GET"]),
         "raise_on_status": False,
         "respect_retry_after_header": True,
     }
@@ -482,6 +499,16 @@ def _parse_retry_after(value: str | None) -> float | None:
         return None
 
 
+def _delegation_headers() -> dict[str, str]:
+    """The user a service-key caller acts for, as ``X-Custom-Attributions``.
+
+    docx-studio's ownership gate reads it (``delegatedUserId``) and agora's
+    ``/access`` refuses a service-key call that delegates no one, so every
+    request carries it: commands and the read-only GETs alike."""
+    custom_attr = os.environ.get("ATHENA_DOCX_CUSTOM_ATTRIBUTIONS")
+    return {"X-Custom-Attributions": custom_attr} if custom_attr else {}
+
+
 def _http_post_json(
     *,
     session: requests.Session,
@@ -489,17 +516,21 @@ def _http_post_json(
     api_key: str,
     body: dict,
     timeout: float = 60.0,
+    header_footer_block_ids: "set[str] | frozenset[str]" = frozenset(),
 ) -> dict:
-    """POST JSON, parse JSON, raise typed errors on non-2xx."""
+    """POST JSON, parse JSON, raise typed errors on non-2xx.
+
+    ``header_footer_block_ids`` are the header/footer paragraph ids this
+    document's ``_HeaderFooter.add_paragraph`` returned: a ``block not
+    found`` on one of them gets the header/footer hint.
+    """
     headers = {
         "Content-Type": "application/json",
         "Authorization": f"Bearer {api_key}",
         "Accept": "application/json",
         "User-Agent": _user_agent(),
+        **_delegation_headers(),
     }
-    custom_attr = os.environ.get("ATHENA_DOCX_CUSTOM_ATTRIBUTIONS")
-    if custom_attr:
-        headers["X-Custom-Attributions"] = custom_attr
     try:
         resp = session.post(
             url,
@@ -621,7 +652,9 @@ 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 paragraph_targeting:
+                if _missing_block_id(err_obj.get("message")) in header_footer_block_ids:
+                    hint = _HEADER_FOOTER_PARAGRAPH_HINT
+                elif paragraph_targeting:
                     hint = _CELL_PARAGRAPH_HINT
                 elif table_query:
                     hint = _TABLE_CLIENT_ID_HINT
@@ -696,6 +729,63 @@ def _warn_skipped_commands(skipped: list[Any]) -> None:
         warnings.warn(message, DocxUnsupportedCommandWarning, stacklevel=2)
 
 
+def _http_get(
+    *,
+    session: requests.Session,
+    url: str,
+    api_key: str,
+    params: dict[str, str] | None = None,
+    timeout: float = DEFAULT_OP_TIMEOUT_SECONDS,
+) -> requests.Response:
+    """GET one of docx-studio's read-only routes; raise typed errors on non-2xx.
+
+    A 404 keeps the server's JSON body as the error payload, so a caller can
+    tell a page past the end (``error: "PageNotFound"``, ``pageCount``) from an
+    asset the caller cannot read.
+    """
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "User-Agent": _user_agent(),
+        **_delegation_headers(),
+    }
+    try:
+        resp = session.get(url, params=params, headers=headers, timeout=timeout)
+    except requests.Timeout as e:
+        raise SessionError(f"docx-studio timed out at {url}: {e}") from e
+    except requests.ConnectionError as e:
+        raise SessionError(f"Unable to reach docx-studio at {url}: {e}") from e
+    if 200 <= resp.status_code < 300:
+        return resp
+    err_body: str = resp.text
+    if resp.status_code in (401, 403):
+        raise AuthenticationError(
+            f"docx-studio rejected the request (HTTP {resp.status_code}): {err_body}",
+        )
+    if resp.status_code == 404:
+        try:
+            parsed: object = resp.json()
+        except ValueError:
+            parsed = None
+        payload: dict[str, Any] = {"status": 404, "body": err_body}
+        if isinstance(parsed, dict):
+            payload.update(parsed)
+        raise NotFoundError(f"docx-studio returned HTTP 404: {err_body}", payload=payload)
+    if resp.status_code in (502, 503, 504):
+        raise DocxStudioTemporarilyUnavailable(
+            f"docx-studio returned HTTP {resp.status_code}: {err_body}",
+            http_status=resp.status_code,
+            retry_after_seconds=_parse_retry_after(resp.headers.get("Retry-After")),
+        )
+    raise DocxError(f"docx-studio returned HTTP {resp.status_code}: {err_body}")
+
+
+class RenderedPagePng(TypedDict):
+    """One page from ``GET /docs/:id/pages/:n.png``."""
+
+    png: bytes
+    page_count: int
+
+
 # ---------------------------------------------------------------------------
 # HttpClient — the bare HTTP transport. Stateless wrt batching.
 # ---------------------------------------------------------------------------
@@ -720,6 +810,8 @@ class HttpClient:
         self._base_url: str = base_url.rstrip("/")
         self._api_key: str = api_key
         self._session: requests.Session = session or _build_retry_session()
+        # Header/footer paragraph ids, for the ``block not found`` hint.
+        self.header_footer_block_ids: set[str] = set()
 
     def close(self) -> None:
         """Release the pooled HTTP connections held by ``requests.Session``.
@@ -801,6 +893,7 @@ class HttpClient:
             api_key=self._api_key,
             body=body,
             timeout=timeout_for_commands(commands=commands),
+            header_footer_block_ids=self.header_footer_block_ids,
         )
         applied = resp.get("applied")
         # Commands the engine doesn't implement yet are reported in
@@ -852,6 +945,38 @@ class HttpClient:
                 skipped_by_index[idx] = entry
         return results, skipped_by_index
 
+    def _doc_url(self, asset_id: str, path: str) -> str:
+        return f"{self._base_url}/docs/{urllib.parse.quote(asset_id, safe='')}/{path}"
+
+    def get_layout(self, asset_id: str) -> dict[str, Any]:
+        """``GET /docs/:id/layout.json`` — the page count and page sizes as
+        DOCX Studio's layout engine paginates the document (VIEW gate)."""
+        resp = _http_get(
+            session=self._session,
+            url=self._doc_url(asset_id, "layout.json"),
+            api_key=self._api_key,
+        )
+        try:
+            data: object = resp.json()
+        except ValueError as e:
+            raise DocxError(f"docx-studio returned a non-JSON layout: {resp.text[:200]!r}") from e
+        if not isinstance(data, dict):
+            raise DocxError(f"docx-studio returned an unexpected layout: {data!r}")
+        return data
+
+    def render_page_png(self, asset_id: str, page_number: int, *, scale: float) -> RenderedPagePng:
+        """``GET /docs/:id/pages/:n.png?scale=`` — one page (1-indexed) as PNG,
+        from the same layout engine the editor paginates with (VIEW gate)."""
+        resp = _http_get(
+            session=self._session,
+            url=self._doc_url(asset_id, f"pages/{page_number}.png"),
+            api_key=self._api_key,
+            params={"scale": f"{scale:g}"},
+        )
+        page_count_header = resp.headers.get("X-Page-Count", "")
+        page_count = int(page_count_header) if page_count_header.isdigit() else 0
+        return RenderedPagePng(png=resp.content, page_count=page_count)
+
 
 # ---------------------------------------------------------------------------
 # Path proxy — translates dotted paths + camelCase param dicts into typed
@@ -1045,6 +1170,7 @@ _FIELD_RENAMES: dict[str, dict[str, str]] = {
     # path-proxy snake-case transform leaves `in` as a Python keyword
     # collision; rename to `in_` here so the dataclass accepts it.
     "find_replace": {"in": "in_"},
+    "blocks.list": {"in": "in_"},
     "find_text": {"in": "in_"},
     "iter_runs": {"in": "in_"},
     "numbering.list": {"in": "in_"},

{athena_python_docx-0.23.0 → athena_python_docx-0.25.0}/docx/_postproc.py

@@ -2055,7 +2055,7 @@ def _border_spec_to_ooxml_attrs(spec: dict[str, Any]) -> dict[str, str]:
             out["sz"] = str(int(round(float(size_pt) * 8)))
         except (TypeError, ValueError):
             pass
-    space = spec.get("space_pt")
+    space = spec.get("space", spec.get("space_pt"))
     if space is not None:
         try:
             out["space"] = str(int(round(float(space))))

athena_python_docx-0.25.0/docx/_run_order.py

@@ -0,0 +1,217 @@
+"""Run order of a paragraph, as ``Paragraph.add_run`` created its runs.
+
+A picture takes no text offset, so two runs can end at the same offset:
+``r1 = p.add_run("A"); r2 = p.add_run(); r2.add_picture(img)`` puts ``r2`` and
+its picture at offset 1, where ``r1`` ends. The offset alone cannot tell the
+server whether content for ``r1`` goes before or after that picture. The SDK
+knows: ``add_run`` appends each run to the end of its paragraph.
+
+This module keeps a record of each such run (its range and the pictures that
+its ``add_picture`` added), in creation order, and gives:
+
+- the run identity of a run-end insert (:func:`run_ref`): the first picture
+  that a later run holds at the same offset (for a read segment that ends
+  inside its run, also the run's own picture there). The server puts the
+  content in front of it; without it, after the pictures at the offset.
+- current ranges: when a run grows or shrinks, its pictures and the runs after
+  it move (:func:`note_length_change`), and so do the live run proxies. A
+  replace cuts every record that it touches.
+
+A record lives as long as its paragraph proxy, not as long as its run proxy,
+so ``p.add_run().add_picture(img)`` keeps the picture's place. The records of
+every paragraph proxy of one block (``doc.paragraphs`` makes new ones) are one
+order. A read run (``paragraph.runs``) stands for the recorded run that holds
+its last character; a read run over text that no recorded run holds counts as
+a run before all of them. The order lives in the SDK process only; the
+document stores none of it.
+"""
+
+from __future__ import annotations
+
+import itertools
+import weakref
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from docx.text.run import Run
+
+_SEQ = itertools.count()
+
+
+@dataclass(eq=False)
+class RunRecord:
+    """One run that ``add_run`` created."""
+
+    seq: int
+    range: tuple[int, int]
+    run: "weakref.ref[Run]"
+    # ``(picture id, offset)`` of each picture that the run's ``add_picture`` added.
+    pictures: list[tuple[str, int]] = field(default_factory=list)
+
+
+# Paragraph proxy -> the records of the runs its ``add_run`` created. A record
+# holds no reference to the paragraph or session, so an entry goes with its
+# paragraph proxy. Keyed by the proxy, not by its id: the first flush moves a
+# new paragraph from its client id to the server id, and the runs created
+# before that keep the client id.
+_ORDERS: "weakref.WeakKeyDictionary[Any, list[RunRecord]]" = weakref.WeakKeyDictionary()
+
+
+def _records_of(run: "Run") -> list[RunRecord]:
+    paragraph = getattr(run, "_paragraph", None)
+    ids = {run._block_id}
+    if paragraph is not None:
+        ids.add(paragraph._node_id)
+    records: list[RunRecord] = []
+    for owner, owner_records in list(_ORDERS.items()):
+        if owner is paragraph or (owner._session is run._session and owner._node_id in ids):
+            records.extend(owner_records)
+    records.sort(key=lambda record: record.seq)
+    return records
+
+
+def register_run(run: "Run") -> None:
+    """Record ``run`` as the last run of its paragraph (``Paragraph.add_run``)."""
+    record = RunRecord(seq=next(_SEQ), range=run._range, run=weakref.ref(run))
+    _ORDERS.setdefault(run._paragraph, []).append(record)
+    run._run_record = record
+
+
+def forget_paragraph(paragraph: Any) -> None:
+    """Drop the order of a paragraph whose runs are gone (``Paragraph.text = ...``)."""
+    for owner in list(_ORDERS.keys()):
+        if owner is paragraph or (owner._session is paragraph._session and owner._node_id == paragraph._node_id):
+            _ORDERS.pop(owner, None)
+
+
+def _place(
+    run: "Run", span: tuple[int, int], records: list[RunRecord] | None = None
+) -> tuple[RunRecord | None, list[RunRecord]]:
+    """The record of ``run`` (over ``span``), if any, and the records after it."""
+    if records is None:
+        records = _records_of(run)
+    # The run itself, or the text that its ``add_text`` returned.
+    own = getattr(run, "_run_record", None) or getattr(run, "_owner_record", None)
+    for index, record in enumerate(records):
+        if record is own:
+            return record, records[index + 1 :]
+    # ``paragraph.runs`` makes a new proxy of a kept run: over the same range,
+    # or over a part of it (a read splits a run at a tab, a break or a change
+    # of format). The proxy stands for the run that holds its last character.
+    if span[0] != span[1]:
+        last = span[1] - 1
+        for index, record in enumerate(records):
+            if record.range[0] <= last < record.range[1]:
+                return record, records[index + 1 :]
+    return None, records
+
+
+def _set_range(record: RunRecord, value: tuple[int, int]) -> None:
+    record.range = value
+    proxy = record.run()
+    if proxy is not None:
+        proxy._range = value
+
+
+def note_length_change(
+    run: "Run",
+    at: int,
+    delta: int,
+    *,
+    replaced: tuple[int, int] | None = None,
+    before: str | None = None,
+) -> None:
+    """``run`` (already over its new range) changed its text by ``delta`` units.
+
+    Without ``replaced``: an insert of ``delta`` units at ``at`` (the end of
+    ``run``), in front of the picture ``before`` when the command named one
+    (else after the pictures at ``at``). With ``replaced``: ``Run.text``
+    replaced the old range ``replaced``; the server keeps the pictures at its
+    start and end and removes the ones inside.
+
+    The text belongs to the record of ``run`` (see :func:`_place`). Every
+    record that the replaced range touches is cut; the records and pictures
+    after the change move.
+    """
+    if delta == 0 and replaced is None:
+        return
+    records = _records_of(run)
+    if replaced is None:
+        start = end = at
+        inserted = delta
+        old_span = (run._range[0], run._range[1] - delta)
+    else:
+        start, end = replaced
+        inserted = (end - start) + delta
+        old_span = replaced
+    owner = _place(run, old_span, records)[0]
+    owner_index = records.index(owner) if owner is not None else -1
+    removed = end - start
+
+    def cut(x: int) -> int:
+        return x if x <= start else start if x < end else x - removed
+
+    # The pictures at ``at`` that an insert goes in front of: ``before`` and
+    # the ones after it, in document order (records in order, then the
+    # pictures of each record in order).
+    moved_at: set[str] = set()
+    if replaced is None and before is not None:
+        order = [pid for record in records for pid, off in record.pictures if off == at]
+        if before in order:
+            moved_at = set(order[order.index(before) :])
+
+    for index, record in enumerate(records):
+        rec_start, rec_end = cut(record.range[0]), cut(record.range[1])
+        if record is owner:
+            rec_end += inserted
+        elif index > owner_index and rec_start >= start:
+            rec_start, rec_end = rec_start + inserted, rec_end + inserted
+        _set_range(record, (rec_start, rec_end))
+        pictures: list[tuple[str, int]] = []
+        for pid, off in record.pictures:
+            if replaced is None:
+                pictures.append((pid, off + delta if off > at or pid in moved_at else off))
+            elif off <= start:
+                pictures.append((pid, off))
+            elif off >= end:
+                pictures.append((pid, off + delta))
+        # The moves keep document order; a stable sort by offset keeps it so.
+        pictures.sort(key=lambda item: item[1])
+        record.pictures = pictures
+
+
+def note_picture(run: "Run", picture_id: str, offset: int, *, before: str | None = None) -> None:
+    """``run.add_picture`` put the picture ``picture_id`` at ``offset``, in front of ``before``.
+
+    A record keeps its pictures in document order: the new one goes in front
+    of ``before``, else after the pictures at ``offset`` and before the ones
+    after it (the server puts a picture after the pictures at its offset).
+    """
+    record = _place(run, run._range)[0]
+    if record is None:
+        return
+    ids = [pid for pid, _ in record.pictures]
+    if before in ids:
+        index = ids.index(before)
+    else:
+        index = next((i for i, (_, off) in enumerate(record.pictures) if off > offset), len(ids))
+    record.pictures.insert(index, (picture_id, offset))
+
+
+def run_ref(run: "Run") -> dict[str, str] | None:
+    """``{"beforeImageId": id}``: the picture that an insert at the end of ``run`` goes in front of.
+
+    The first picture of a later run where ``run`` ends. A read segment that
+    ends inside its run (a picture of the run between two of its texts) also
+    puts the insert in front of the run's own picture there, right after the
+    segment's text.
+    """
+    end = run._range[1]
+    record, later = _place(run, run._range)
+    candidates = ([record] if record is not None and end < record.range[1] else []) + later
+    for candidate in candidates:
+        for picture_id, offset in candidate.pictures:
+            if offset == end:
+                return {"beforeImageId": picture_id}
+    return None

{athena_python_docx-0.23.0 → athena_python_docx-0.25.0}/docx/_timeouts.py

@@ -22,6 +22,8 @@ _LONG_RUNNING_COMMAND_TYPES: frozenset[str] = frozenset(
         # ``Document.clear()`` replaces the whole body story in one write;
         # on a large document that single command can outlast the 60s budget.
         "ClearBody",
+        # ``Document.to_pdf()`` lays out and paints every page of the document.
+        "ExportPDF",
     }
 )
 

{athena_python_docx-0.23.0 → athena_python_docx-0.25.0}/docx/client.py

@@ -178,6 +178,22 @@ class Session:
             )
         return self._doc_handle
 
+    @property
+    def http_client(self) -> Any:
+        """The opened :class:`HttpClient`, for docx-studio's read-only routes
+        outside the command bus (page renders, layout)."""
+        self._assert_current_execution()
+        if not self._opened:
+            raise SessionError(
+                "Session not yet opened; call await session.open() first "
+                "or use the sync facade via Document().",
+            )
+        if self._closed:
+            raise DocumentClosedError(
+                f"Session for asset {self._asset_id} is closed.",
+            )
+        return self._client
+
     async def send_command(self, cmd: Any) -> Any:
         """Route a pre-built :class:`docx.commands.Command` through the
         buffer.