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

athena_python_docx-0.21.8/CLAUDE.md → athena_python_docx-0.23.0/AGENTS.md

@@ -367,8 +367,8 @@ Issue numbers reference `python-openxml/python-docx`.
   list metadata. Routes through `NumberingGet`.
 
 - **`Document.to_pdf(*, quality=None, destination=None,
-  include_revisions=False) -> bytes`** — render to PDF via the
-  Daytona-hosted LibreOffice. python-docx issue #113 was closed as
+  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).
 
@@ -447,6 +447,53 @@ Issue numbers reference `python-openxml/python-docx`.
   only when you already have a DOCX editor anchor id. For normal writing,
   cite the ``Paragraph`` proxy you just created or found.
 
+- **Table-cell citations** (0.22.0+): **`_Cell.add_citation(source, *,
+  anchor=None, citation_string=None, excerpt=None, display_value=None)
+  -> str`** + **`_Cell.clear_citations()`**, and ``Paragraph.add_citation``
+  / ``Paragraph.clear_citations`` on cell paragraphs (before 0.22.0 they
+  raised ``ValueError`` "top-level DOCX paragraphs only"). The SDK models a
+  cell as one paragraph addressed by the synthetic cell id
+  (``tc:table:row:col``; ``cell.paragraphs[0]`` stands for the whole cell),
+  so a cell citation sends that id. The docx-studio applier resolves it to
+  the cell's paragraph ids: one paragraph with text → ``pm_node``, several
+  → ``pm_node_range`` from the first to the last; a cell paragraph with no
+  paraId (or a repeated one) gets a new one. A horizontally merged cell
+  resolves to its master cell from any grid position it covers. A
+  paragraph that ``cell.add_paragraph(text)`` returned already carries its
+  own paraId and is cited alone. To cite one paragraph of a cell (or a
+  paragraph in a nested table), pass the ``data-id`` a Word read shows for
+  it: ``doc.add_citation(..., destination_anchor=PmNodeAnchor(node_id=...))``.
+  ``_Cell.clear_citations()`` removes every citation inside the cell.
+  Write the cell text first, then cite it:
+
+  ```python
+  table = doc.add_table(rows=2, cols=2)
+  table.cell(1, 0).text = "Revenue"
+  table.cell(1, 1).text = "$12.4M"
+  table.cell(1, 1).add_citation(
+      "/dashboard/spaces/?asset_ids=asset_sheet&type=spreadsheet"
+      "&anchor=sheet_range&sheet_id=0&range=C4",
+      excerpt="$12.4M",
+  )
+  ```
+
+  Needs a docx-studio API that resolves cell ids (the same release train);
+  an older API stores the record under the cell id, where nothing renders
+  it and the next edit retires it.
+
+- **Image region citations**: cite a region of an image asset with
+  ``AssetReference(id=<image>)`` + ``PixelRangeAnchor(x=, y=, width=,
+  height=)`` in source image pixels, or with a
+  ``/dashboard/spaces/?asset_ids=<image>&type=image&anchor=pixel_range&x=…&y=…&width=…&height=…``
+  citation string. DOCX Studio stores ``type=image`` and keeps ``excerpt``
+  out of the URL (the record keeps it as the span of the cited paragraph to
+  highlight). Since 0.23.0, ``add_citation`` raises ``ValueError`` for the
+  image citations that chat and Sheets reject (agora
+  ``validate_image_citation_url``): an image URL with ``excerpt`` or
+  ``#:~:text=`` and no anchor, a non-region anchor, a region anchor without
+  x, y, width and height, and an ``AssetMeta(asset_type="image")`` source
+  with a non-region anchor or with an excerpt and no anchor.
+
 - **`Document.export_docx(path=None, *, include_revisions=False)
   -> bytes`** (0.11.4+) — export the document's current state as
   ``.docx`` bytes, optionally writing to ``path``. Closes the gap
@@ -769,7 +816,7 @@ This is a **thin HTTP client** that mimics the sync python-docx API.
   drain pending ops before running; the 100 ms idle timer fires on
   inactivity so collab updates stream live; `Document.save()` and
   the context-manager exit drain explicitly; `docx.flush_all()` is
-  the Daytona-prelude hook that flushes every live buffer in the
+  the executor-postamble hook that flushes every live buffer in the
   process.
 - Execution scope: executor sandboxes may keep Python globals
   between tool calls so imports, constants, and helper functions can be

athena_python_docx-0.23.0/CLAUDE.md

@@ -0,0 +1,5 @@
+@AGENTS.md
+
+<!-- AGENTS.md next to this file is the single source of truth for agent
+     instructions. Claude Code does not read AGENTS.md natively, so this file
+     imports it. Add Claude-Code-only rules below this line. -->

{athena_python_docx-0.21.8 → athena_python_docx-0.23.0}/DOCX_EXEC_LAB.md

@@ -6,7 +6,7 @@ shortens the debug loop by running local SDK code directly against a
 chosen DOCX Studio API, capturing stdout/stderr/errors/timings, and
 optionally exporting the result to `.docx` for assertions.
 
-Use this before waiting on a full Agent -> Daytona -> preview cycle when
+Use this before waiting on a full Agent -> executor sandbox -> preview cycle when
 debugging SDK behavior such as large-document replacement, table fills,
 unsupported OOXML internals, or export fidelity.
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.21.8
+Version: 0.23.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>
@@ -76,7 +76,7 @@ an Olympus Word document embed preview pane. See `DOCX_EXEC_LAB.md`.
 
 ## Environment variables
 
-Required when connecting to DOCX Studio (set by Athena backend when executing in Daytona):
+Required when connecting to DOCX Studio (set by the Athena backend in the `execute_word_document_code` executor sandbox):
 
 - `ATHENA_DOCX_BASE_URL` — DOCX Studio API base URL
 - `ATHENA_DOCX_API_KEY` — Athena API key or service-issued DOCX Studio token

{athena_python_docx-0.21.8 → athena_python_docx-0.23.0}/README.md

@@ -51,7 +51,7 @@ an Olympus Word document embed preview pane. See `DOCX_EXEC_LAB.md`.
 
 ## Environment variables
 
-Required when connecting to DOCX Studio (set by Athena backend when executing in Daytona):
+Required when connecting to DOCX Studio (set by the Athena backend in the `execute_word_document_code` executor sandbox):
 
 - `ATHENA_DOCX_BASE_URL` — DOCX Studio API base URL
 - `ATHENA_DOCX_API_KEY` — Athena API key or service-issued DOCX Studio token

{athena_python_docx-0.21.8 → athena_python_docx-0.23.0}/docx/__init__.py

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

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

@@ -20,7 +20,7 @@ guard the pending list with an RLock and treat the timer flush as a
 best-effort coalesce — if the loop thread races us we just flush twice
 (or zero times; the next loop-thread call drains it).
 
-`flush_all` is a process-wide hook used by the Daytona sandbox prelude to
+`flush_all` is a process-wide hook used by Athena's sandbox executor to
 make sure pending writes hit Keryx before the sandbox is suspended. It walks
 a weak-ref registry so dead Workbook instances don't keep their buffers
 alive.
@@ -199,7 +199,7 @@ def _unregister(buffer: "CommandBuffer") -> None:
 def flush_all(*, strict: bool = False) -> None:
     """Flush every live CommandBuffer in this process.
 
-    Used by the Daytona sandbox prelude after user code returns, so
+    Used by Athena's sandbox executor after user code returns, so
     buffered mutations make it to Keryx before the sandbox is suspended.
     Safe to call when no Buffers exist (no-op).
 

{athena_python_docx-0.21.8 → athena_python_docx-0.23.0}/docx/_citations.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import uuid
+from collections.abc import Mapping
 from typing import Any
 from urllib.parse import parse_qs, urlparse
 
@@ -34,6 +35,87 @@ def source_ref_to_dict(source: AssetReference) -> dict[str, Any]:
     return source.to_dict()
 
 
+_IMAGE_REGION_ANCHOR_TYPES: tuple[str, ...] = ("pixel_range", "rect")
+_IMAGE_REGION_FIELDS: tuple[str, ...] = ("x", "y", "width", "height")
+
+
+def _is_number(value: object) -> bool:
+    """True for what agora's anchor parser reads as a number (``float(...)``)."""
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, (int, float)):
+        return True
+    if isinstance(value, str):
+        try:
+            float(value)
+        except ValueError:
+            return False
+        return True
+    return False
+
+
+def check_image_citation(
+    *,
+    anchor_type: str | None,
+    has_excerpt: bool,
+    region: Mapping[str, object] | None = None,
+) -> None:
+    """Reject an image citation that chat and Sheets reject.
+
+    The same rules as agora's ``validate_citation_url`` for an image: an
+    image is cited by a region (``anchor=pixel_range`` with numeric x, y,
+    width and height in source image pixels), never by a page, a text anchor
+    or an excerpt. ``region`` holds the x, y, width and height values of a
+    region anchor (``None`` for a missing one).
+    """
+    if anchor_type and anchor_type not in _IMAGE_REGION_ANCHOR_TYPES:
+        raise ValueError(
+            f"An image citation cannot use anchor={anchor_type}. Cite a region "
+            "of the image: anchor=pixel_range with x, y, width and height in "
+            "source image pixels (PixelRangeAnchor)."
+        )
+    if not anchor_type and has_excerpt:
+        raise ValueError(
+            "An image citation cannot use an excerpt or a #:~:text= fragment: "
+            "an image has no text to find. Cite a region of the image: "
+            "anchor=pixel_range with x, y, width and height in source image "
+            "pixels (PixelRangeAnchor), and put the label in display_value."
+        )
+    if not anchor_type or region is None:
+        return
+    missing = [field for field in _IMAGE_REGION_FIELDS if region.get(field) is None]
+    if missing:
+        raise ValueError(
+            f"An image citation with anchor={anchor_type} needs x, y, width "
+            f"and height. Missing: {', '.join(missing)}."
+        )
+    not_numbers = [field for field in _IMAGE_REGION_FIELDS if not _is_number(region[field])]
+    if not_numbers:
+        raise ValueError(
+            f"An image citation with anchor={anchor_type} needs numbers for "
+            f"x, y, width and height. Not a number: {', '.join(not_numbers)}."
+        )
+
+
+def _check_image_citation_url(query: str, fragment: str) -> None:
+    # Blank values are dropped, as agora's validator parses the query.
+    params = parse_qs(query)
+
+    def first(key: str) -> str | None:
+        values = params.get(key)
+        return values[0] if values else None
+
+    asset_type = (first("asset_type") or first("type") or "").lower()
+    if asset_type != "image":
+        return
+    anchor_type = (first("anchor") or "").lower() or None
+    check_image_citation(
+        anchor_type=anchor_type,
+        has_excerpt=first("excerpt") is not None or fragment.startswith(":~:text="),
+        region={field: first(field) for field in _IMAGE_REGION_FIELDS},
+    )
+
+
 def normalize_citation_string(citation_string: str) -> str:
     value = citation_string.strip()
     if not value:
@@ -49,6 +131,7 @@ def normalize_citation_string(citation_string: str) -> str:
             asset_ids = parse_qs(parsed.query).get("asset_ids")
             if not asset_ids or not asset_ids[0]:
                 raise ValueError("Athena Spaces citation URLs must include asset_ids")
+            _check_image_citation_url(parsed.query, parsed.fragment)
         return value
 
     if not parsed.scheme and value.startswith("/"):
@@ -61,6 +144,7 @@ def normalize_citation_string(citation_string: str) -> str:
         if relative.path.rstrip("/") == "/dashboard/spaces":
             asset_ids = parse_qs(relative.query).get("asset_ids")
             if asset_ids and asset_ids[0]:
+                _check_image_citation_url(relative.query, relative.fragment)
                 return value
             raise ValueError("Athena Spaces citation URLs must include asset_ids")
 
@@ -106,6 +190,35 @@ def destination_anchor_to_dict(destination_anchor: object) -> dict[str, Any]:
     )
 
 
+def _check_typed_image_citation(
+    *,
+    source_ref: dict[str, Any],
+    source_anchor: dict[str, Any] | None,
+    excerpt: str | None,
+) -> None:
+    """Apply the image citation rules to an ``AssetReference`` source.
+
+    A ``PixelRangeAnchor`` / ``RectAnchor`` source is an image region:
+    DOCX Studio names it ``type=image`` and keeps the excerpt out of its URL
+    (the record keeps it as the span of the cited paragraph to highlight).
+    A source that ``AssetMeta(asset_type="image")`` names an image must use
+    one of those anchors.
+    """
+    anchor = source_anchor or source_ref.get("anchor")
+    anchor_type = anchor.get("type") if isinstance(anchor, dict) else None
+    meta = source_ref.get("meta")
+    asset_type = meta.get("assetType") if isinstance(meta, dict) else None
+    is_region = anchor_type in _IMAGE_REGION_ANCHOR_TYPES
+    if not is_region and str(asset_type or "").lower() != "image":
+        return
+    meta_excerpt = meta.get("excerpt") if isinstance(meta, dict) else None
+    check_image_citation(
+        anchor_type=anchor_type,
+        has_excerpt=excerpt is not None or meta_excerpt is not None,
+        region=anchor if is_region and isinstance(anchor, dict) else None,
+    )
+
+
 def build_add_citation_command(
     *,
     destination_anchor: object,
@@ -142,11 +255,19 @@ def build_add_citation_command(
     if source_ref is None and anchor is not None:
         raise ValueError("anchor requires an AssetReference source; encode the anchor in citation_string instead")
 
+    source_anchor = anchor_to_dict(anchor)
+    if source_ref is not None:
+        _check_typed_image_citation(
+            source_ref=source_ref,
+            source_anchor=source_anchor,
+            excerpt=excerpt,
+        )
+
     citation_id = new_citation_id()
     return citation_id, AddCitation(
         destination_anchor=destination_anchor_to_dict(destination_anchor),
         source_ref=source_ref,
-        source_anchor=anchor_to_dict(anchor),
+        source_anchor=source_anchor,
         citation_string=normalized_citation_string,
         citation_id=citation_id,
         excerpt=excerpt,

{athena_python_docx-0.21.8 → athena_python_docx-0.23.0}/docx/_http.py

@@ -5,7 +5,7 @@ bootstrap and upload calls on urllib so ``Document.create()`` can provision
 Word document assets without pulling in extra runtime dependencies.
 
 We use ``urllib`` from stdlib to avoid pulling ``httpx`` / ``requests``
-into the runtime — this code runs in Daytona sandboxes where every MB
+into the runtime — this code runs in sandboxes where every MB
 matters, and the existing SDK already keeps its dep tree tight.
 """
 

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

@@ -46,6 +46,7 @@ from docx.commands import (
     BookmarksList,
     ChartsGet,
     ChartsList,
+    ClearBody,
     ClearParagraphAlignment,
     ClearParagraphIndentation,
     ClearParagraphSpacing,
@@ -1002,6 +1003,7 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "sdt.delete": ContentControlsDelete,
     "sections.set_columns": SetSectionColumns,
     "find_replace": FindReplace,
+    "clear_body": ClearBody,
     "find_text": FindText,
     "iter_runs": IterRuns,
     "export_pdf": ExportPDF,

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

@@ -497,6 +497,27 @@ class PostExportOps:
             or bool(self._row_cant_split_ops)
         )
 
+    def discard_body_ops(self) -> None:
+        """Drop every rewrite that addresses body content by position.
+
+        Cell/table formatting, row heights, captured REF paragraphs and
+        header/footer relocations are all keyed by body-relative indices
+        (``table_doc_index``, ``source_paragraph_index``, body node ids).
+        Once the body story has been replaced they point at nodes that no
+        longer exist — and would silently re-target whatever the caller
+        creates next at the same index. Document-wide rewrites
+        (``font_override``) do not address the body and are kept.
+        """
+        self._cell_format_ops.clear()
+        self._cell_run_format_ops.clear()
+        self._cell_hyperlink_ops.clear()
+        self._cell_shading_ops.clear()
+        self._table_borders_ops.clear()
+        self._captured_refs.clear()
+        self._row_height_ops.clear()
+        self._row_cant_split_ops.clear()
+        self._header_footer_relocations.clear()
+
     def add_row_cant_split(
         self,
         *,

{athena_python_docx-0.21.8 → athena_python_docx-0.23.0}/docx/_ptc.py

@@ -23,6 +23,11 @@ Emits are **synchronous, best-effort** HTTP POSTs:
 - Snapshot the URL at ``emit_begin`` time and carry it to ``emit_end``
   so late end events can't be misattributed if a new sandbox run
   swapped in a different URL between begin and end.
+- Reuse one keep-alive connection per endpoint instead of a new TCP (and
+  TLS) connection per event. An idle connection the server has closed is
+  detected before sending and replaced; a send is never retried (the
+  registry does not deduplicate events). When a proxy applies to the URL
+  (``*_proxy`` env vars) each event goes through urllib as before.
 
 This module is *intentionally byte-identical* across the docx / pptx /
 xlsx SDKs — the three SDKs have no shared base. Duplicating ~100 LOC
@@ -31,10 +36,14 @@ of stdlib code is cheaper than spinning up a 4th release pipeline.
 
 from __future__ import annotations
 
+import http.client
 import json
 import os
+import select
+import threading
 import time
 import urllib.error
+import urllib.parse
 import urllib.request
 import uuid
 from typing import Any
@@ -46,6 +55,58 @@ _HTTP_TIMEOUT = 2.0
 # original run's endpoint even if ATHENA_PTC_URL changed since.
 _call_url: dict[str, str] = {}
 
+# (scheme, host:port) -> an idle keep-alive connection. Checked out while a
+# POST uses it, so no two threads ever share one.
+_idle: dict[tuple[str, str], http.client.HTTPConnection] = {}
+_idle_lock = threading.Lock()
+
+
+def _dropped(conn: http.client.HTTPConnection) -> bool:
+    """An idle connection the server has closed (or that has unexpected data
+    waiting) reads as ready: never send on it."""
+    sock = conn.sock
+    if sock is None:
+        return True
+    try:
+        return bool(select.select([sock], [], [], 0)[0])
+    except (OSError, ValueError):
+        return True
+
+
+def _post_keepalive(url: str, raw: bytes) -> None:
+    parts = urllib.parse.urlsplit(url)
+    if parts.scheme not in ("http", "https") or not parts.hostname:
+        raise ValueError(f"unsupported PTC URL: {url!r}")
+    target = (parts.path or "/") + (f"?{parts.query}" if parts.query else "")
+    key = (parts.scheme, parts.netloc)
+    with _idle_lock:
+        conn = _idle.pop(key, None)
+    if conn is not None and _dropped(conn):
+        conn.close()
+        conn = None
+    if conn is None:
+        factory = (
+            http.client.HTTPSConnection if parts.scheme == "https" else http.client.HTTPConnection
+        )
+        conn = factory(parts.netloc, timeout=_HTTP_TIMEOUT)
+    # Never retried: a failure after the request left may still have been
+    # processed, and the registry does not deduplicate events.
+    try:
+        conn.request("POST", target, body=raw, headers={"Content-Type": "application/json"})
+        response = conn.getresponse()
+        response.read()
+    except BaseException:
+        conn.close()
+        raise
+    if response.will_close:
+        conn.close()
+        return
+    with _idle_lock:
+        spare = _idle.pop(key, None)
+        _idle[key] = conn
+    if spare is not None:
+        spare.close()
+
 
 def _send(url: str, body: dict[str, Any]) -> None:
     """Synchronously POST one PTC event. Best-effort; never raises.
@@ -63,14 +124,19 @@ def _send(url: str, body: dict[str, Any]) -> None:
             key = "args" if body.get("phase") == "begin" else "result"
             body[key] = {"__truncated__": True}
             raw = json.dumps(body).encode("utf-8")
-        req = urllib.request.Request(
-            url,
-            data=raw,
-            method="POST",
-            headers={"Content-Type": "application/json"},
-        )
-        urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT).close()
-    except (urllib.error.URLError, OSError, ValueError):
+        parts = urllib.parse.urlsplit(url)
+        proxy = urllib.request.getproxies().get(parts.scheme)
+        if proxy and not urllib.request.proxy_bypass(parts.hostname or ""):
+            req = urllib.request.Request(
+                url,
+                data=raw,
+                method="POST",
+                headers={"Content-Type": "application/json"},
+            )
+            urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT).close()
+        else:
+            _post_keepalive(url, raw)
+    except (urllib.error.URLError, OSError, ValueError, http.client.HTTPException):
         pass  # never propagate — PTC is best-effort
 
 

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

@@ -19,6 +19,9 @@ _LONG_RUNNING_COMMAND_TYPES: frozenset[str] = frozenset(
         # ordinary 60s budget committing a table batch even when the Python code
         # uses the fast no-read cell path.
         "TableSetCell",
+        # ``Document.clear()`` replaces the whole body story in one write;
+        # on a large document that single command can outlast the 60s budget.
+        "ClearBody",
     }
 )
 

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

@@ -36,7 +36,7 @@ if TYPE_CHECKING:
 
 def _log_info(msg: str) -> None:
     """Minimal stderr logger; we avoid loguru to keep the SDK runtime
-    dependency tree small (this code runs inside Daytona sandboxes)."""
+    dependency tree small (this code runs inside sandboxes)."""
     import sys
 
     print(f"[docx-sdk] {msg}", file=sys.stderr)
@@ -84,6 +84,10 @@ class Session:
         from docx._postproc import PostExportOps
 
         self._post_export_ops: PostExportOps = PostExportOps()
+        # Bumped by ``Document.clear()``. ``Table`` proxies remember the
+        # generation they were created in, so a proxy from before a clear
+        # can never be re-anchored to a table created after it.
+        self._body_generation: int = 0
 
     @property
     def asset_id(self) -> str:

{athena_python_docx-0.21.8 → athena_python_docx-0.23.0}/docx/commands.py

@@ -136,6 +136,10 @@ class Insert(Command):
     # on the DOCX Studio call (renamed in transit so it doesn't collide with our
     # discriminator).
     value_type: str | None = None
+    # Text mode only. ``True`` continues the formatting of the run at the
+    # insertion point (``Run.add_text``); omitted means the inserted text is
+    # a fresh, unformatted run (``Paragraph.add_run``).
+    inherit_marks: bool | None = None
     placement: str | None = None
     content: dict[str, Any] | None = None
 
@@ -1543,6 +1547,18 @@ class FindReplace(Command):
     max_replacements: int | None = None
 
 
+@dataclass
+class ClearBody(Command):
+    """Replace the whole body story with a single empty paragraph.
+
+    Athena extension backing :meth:`Document.clear`. One server-side
+    write instead of a ``Replace`` per paragraph and per table-cell
+    paragraph; headers, footers and notes are untouched and the final
+    section's page setup survives. Returns ``{nodeId}`` of the new
+    empty paragraph.
+    """
+
+
 @dataclass
 class FindText(Command):
     """Search document text and return bounded match context.
@@ -1576,8 +1592,8 @@ class IterRuns(Command):
 
 # ---------------------------------------------------------------------------
 # PDF Export (Athena extension — python-docx issue #113 keeps getting
-# re-asked despite being closed wontfix. DOCX Studio renders via Daytona
-# (LibreOffice headless) to bytes the client can download or persist.)
+# re-asked despite being closed wontfix. DOCX Studio renders the document
+# to bytes the client can download or persist.)
 # ---------------------------------------------------------------------------
 
 
@@ -1759,6 +1775,9 @@ _RESPONSE_BEARING_TYPES: frozenset[str] = frozenset(
         "ExportDocx",
         # FindReplace returns a replacement count for the caller.
         "FindReplace",
+        # ClearBody replaces the whole body; Document.clear awaits it so a
+        # rejected clear raises instead of leaving stale content behind.
+        "ClearBody",
     }
 )
 
@@ -1852,6 +1871,7 @@ for _cls, _issue, _desc in [
     (ContentControlsDelete, "python-docx#155", "SDT delete"),
     (SetSectionColumns, "python-docx#167", "Section multi-column layout"),
     (FindReplace, "python-docx#30", "Formatting-preserving find/replace"),
+    (ClearBody, None, "Document.clear — bulk body reset"),
     (FindText, "python-docx#980", "Fast document text search"),
     (IterRuns, "python-docx#980", "Run stream for run-isolation"),
     (ExportPDF, "python-docx#113", "PDF export"),
@@ -1990,6 +2010,7 @@ __all__ = [
     "ContentControlsDelete",
     "SetSectionColumns",
     "FindReplace",
+    "ClearBody",
     "FindText",
     "IterRuns",
     "ExportPDF",