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

{athena_python_docx-0.24.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.24.0 → athena_python_docx-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.24.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.24.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.24.0"
+__version__ = "0.25.0"
 
 from docx.api import Document
 from docx._buffer import discard_all, flush_all

{athena_python_docx-0.24.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.24.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.24.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.24.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.24.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.

{athena_python_docx-0.24.0 → athena_python_docx-0.25.0}/docx/commands.py

@@ -88,6 +88,8 @@ class CreateParagraph(Command):
     # serialises as ``in`` on the wire (see top-of-module helper).
     in_: dict[str, Any] | None = None
     client_node_id: str | None = None
+    # The paragraph opens with a page break (``Document.add_page_break``).
+    page_break: bool | None = None
 
 
 @dataclass
@@ -543,6 +545,9 @@ class BlocksList(Command):
     # ``Paragraph.text``/``.runs``/``.style`` from one list instead of a
     # ``get_node_by_id`` per paragraph. Serialized to ``includeRuns`` on the wire.
     include_runs: bool | None = None
+    # A header/footer story (``headerFooterSlot``) for ``header.paragraphs``;
+    # ``in`` on the wire. See CreateParagraph.in_.
+    in_: dict[str, Any] | None = None
 
 
 @dataclass
@@ -573,7 +578,10 @@ class ImagesList(Command):
 
 @dataclass
 class Info(Command):
-    pass
+    # ``True`` also returns the document's style table (``styleTable``: the
+    # id, styles.xml name, type and default flag of every style); an older
+    # docx-studio ignores the field and sends no table.
+    include_styles: bool | None = None
 
 
 @dataclass
@@ -1004,6 +1012,11 @@ class CreateField(Command):
     target: dict[str, Any] | None = None
     cached_result: str | None = None
     client_entity_id: str | None = None
+    # False for an empty run: the field takes the paragraph style's defaults,
+    # not the formatting of the text before it.
+    inherit_marks: bool | None = None
+    # The formatting set on that empty run before it has text (``FormatApply.inline``).
+    inline: dict[str, Any] | None = None
 
 
 @dataclass
@@ -1616,10 +1629,12 @@ class IterRuns(Command):
 
 @dataclass
 class ExportPDF(Command):
-    """Render the document to a PDF byte stream, optionally storing it
-    under ``destination`` (an asset id, S3 URL, or path).
+    """Render the document to a PDF with DOCX Studio's layout engine.
 
-    Returns ``{bytes_base64, asset_id?, page_count}``.
+    Returns ``{bytesBase64, mediaType, pageCount, fidelityNotes}``. The
+    server refuses ``destination`` (``Document.to_pdf`` writes local files
+    itself and never sends it); ``quality`` is ``"draft"`` | ``"standard"`` |
+    ``"high"``.
     """
 
     quality: str | None = None  # "draft" | "standard" | "high"
@@ -1772,6 +1787,9 @@ _RESPONSE_BEARING_TYPES: frozenset[str] = frozenset(
         "HeaderFootersPartsCreate",
         # HeaderFootersPartsList is a read-side query.
         "HeaderFootersPartsList",
+        # HeaderFootersPartsDelete returns {changed}: whether a part was
+        # deleted. Buffered, the caller only ever saw ``{}``.
+        "HeaderFootersPartsDelete",
         # Athena-extension response-bearing creates — each returns an
         # entity id the caller wraps in a proxy.
         "CreateHyperlink",