athena-python-docx 0.29.0__tar.gz → 0.31.0__tar.gz

{athena_python_docx-0.29.0 → athena_python_docx-0.31.0}/AGENTS.md

@@ -204,14 +204,21 @@ not file-backed. Each is documented in the relevant docstring.
   are sent with `changeMode: "tracked"`, and docx-studio records their text
   edits as Word revisions (`w:ins` / `w:del`): run and paragraph text,
   `find_replace` in the body, new paragraphs and headings (an inserted
-  paragraph mark), tabs and line breaks, run formatting (`w:rPrChange`) and
+  paragraph mark), whole paragraphs deleted (`paragraph.delete()`, 0.30.0+:
+  its content, fields included, and its paragraph mark), tabs and line breaks,
+  run formatting (`w:rPrChange`) and
   `paragraph_format` properties (`w:pPrChange`). The replaced text stays, deleted,
   and the new text follows it, so the SDK keeps its paragraph lengths and
   run ranges that way (`docx/_tracked.py`): a tracked `run.text = value`
   leaves the run over `value`, after its deleted text, and the paragraph
-  grows by `len(value)`. Every batch says so to docx-studio
-  (`client.capabilities: ["trackedAuthoring"]`); a docx-studio refuses a
-  tracked edit from an SDK that does not. A batch holding an edit it cannot
+  grows by `len(value)`. `find_replace` and (0.30.0+) `paragraph.text = value`
+  mark only the words that change, the words the old and new text share at
+  their start and end left as they are, so after a tracked `paragraph.text`
+  the SDK reads the paragraph's length back. Every batch says so to docx-studio
+  (`client.capabilities: ["trackedAuthoring", "trackedMinimalParagraphText"]`);
+  a docx-studio refuses a tracked edit from an SDK that does not declare
+  `trackedAuthoring`, and replaces a paragraph's whole text for one that
+  does not declare `trackedMinimalParagraphText`. A batch holding an edit it cannot
   record yet (paragraph styles, tables, pictures, lists, sections, notes,
   page breaks, header/footer/comment text) is refused (HTTP 422,
   `TrackedChangesUnsupported`) and applies nothing; reads, exports,
@@ -233,9 +240,11 @@ not file-backed. Each is documented in the relevant docstring.
 
 - **`Document.user_name: str | None` / `Document.user_email: str |
   None`** — the name sent with each batch, which DOCX Studio uses as the
-  author of a comment that names none. It is not a tracked change's author:
-  DOCX Studio stamps those with the signed-in user agora's access check
-  names, so a script cannot choose who a redline's changes are by.
+  author of a comment that names none (unset, such a comment is by the
+  signed-in user, as "Jane Doe (Athena)"). It is not a tracked change's
+  author: DOCX Studio stamps those with the signed-in user agora's access
+  check names, as an agent writes for them ("Jane Doe (Athena)"), so a
+  script cannot choose who a redline's changes are by.
   Separate from `Document.core_properties.last_modified_by`, the
   `docProps/core.xml` metadata the SDK reads and writes as python-docx
   does.
@@ -451,6 +460,26 @@ Issue numbers reference `python-openxml/python-docx`.
   numbering reads. python-docx issue #471 (13 👍) demands access to
   list metadata. Routes through `NumberingGet`.
 
+- **`Paragraph.delete()`** (0.30.0+) — delete the paragraph, its
+  paragraph mark included. python-docx has no paragraph delete (issue #33);
+  code written for it removes the element
+  (`p._element.getparent().remove(p._element)`), which this SDK cannot reach.
+  Routes through `DeleteParagraph`, sent in a request of its own after the
+  buffered edits (response-bearing, so a refusal raises at the call). With
+  tracking off docx-studio removes the paragraph, with the page and column
+  breaks the import keeps beside it; with `track_revisions` on it records
+  Word's tracked deletion of a whole paragraph: its content in `w:del`
+  (cross-reference and other fields with their codes and results, links,
+  note references) and its paragraph mark deleted, one revision. Accept All
+  removes it and the numbered paragraphs after it number on; Reject All
+  restores it. `paragraph.text = ""` leaves an empty, still numbered,
+  paragraph instead. docx-studio refuses (`DocxError`, nothing applied) the
+  document's last paragraph, one that ends a section, the only paragraph of
+  a table cell or content control, one holding part of a field that spans
+  paragraphs, one in a header, footer, comment or text box, and, tracked,
+  one in a table cell or holding a page break, a content control, a shape or
+  an equation (`DOCX_STUDIO_LIMITATIONS.md` § 32).
+
 - **`Paragraph.restart_numbering(start=1)`** (0.26.0+) — restart the
   paragraph's numbered list at `start`, as Word's "Restart at 1" does
   ("Set Numbering Value" for another start). All `"List Number"`
@@ -648,8 +677,11 @@ Issue numbers reference `python-openxml/python-docx`.
   leaves out the author, last-modified-by, revision, company, manager,
   template, editing-time and hyperlink-base properties, rsids, document
   variables, custom properties, Custom XML (a content control bound to it
-  keeps its content, not its binding), the attached template and the
-  thumbnail; ``clear_title=True`` drops the title too. The live document is
+  keeps its content, not its binding), the attached template, the attached
+  XML schema and the thumbnail; ``clear_title=True`` drops the title too.
+  Bookmarks, the creation date and the sensitivity label stay (the route's
+  ``removeSensitivityLabel=1`` drops the label; the SDK does not send it).
+  The live document is
   not changed. The SDK refuses (``DocxUnsupportedCommandError``) an answer
   without ``X-Docx-Clean-Copy: 1``, the plain export an older docx-studio
   sends, and raises ``DocxError`` with docx-studio's reason when a header,
@@ -954,13 +986,32 @@ architecture or a DOCX Studio constraint:
   `Table.autofit` reads `False` (python-docx leaves autofit on); its columns
   share 9,360 twips, where python-docx shares the section's text width; and
   in the fixed layout a column width the script sets sizes the column's
-  cells too, where python-docx sets the `w:gridCol` alone. It also draws
-  borders and a zebra fill, which no python-docx read sees. Recorded as
-  `live_deviations` for the script cases' `tables.autofit`, `tables.widths`
-  and `tables.cell_format` in `tests/parity/intentional_deviations.json`;
+  cells too, where python-docx sets the `w:gridCol` alone. Its cell
+  paragraphs carry their own spacing (`w:spacing w:after="0" w:line="240"
+  w:lineRule="auto"`: no space after, single lines), so a cell paragraph's
+  `paragraph_format.space_after` reads `0` and `line_spacing` `1.0`, where
+  python-docx's `add_table` writes none. It also draws borders and a zebra
+  fill, which no python-docx read sees. Recorded as `live_deviations` for
+  the script cases' `tables.autofit`, `tables.widths`, `tables.cell_format`
+  and `tables.cell_paragraph_format` in `tests/parity/intentional_deviations.json`;
   an imported table's gaps stay gaps, and so do the two cases whose
   `cell_format` also differs for another cause (`except`).
 
+- **A held `Table` raises `StaleTableError` once its table is gone.** The SDK
+  holds the anchored ids docx-studio gives it (`t:N/R:C/K…@FIRST.LAST`: the
+  table's place, then the paraIds of its first and last paragraphs), and
+  docx-studio finds the table by those paragraphs, so a table an edit moved (a
+  row added above a table nested in a cell, a table added before it, a merge
+  moving a nested table into the merged cell) is still the one read and
+  written, as python-docx's proxies follow the elements they hold. When no
+  table holds them (the table was deleted, or the cell holding it had its
+  text replaced, which removes the tables it held), docx-studio refuses the
+  batch and the SDK raises `StaleTableError`: "the table this proxy named is
+  gone; re-read `document.tables`". python-docx writes the detached element
+  and changes nothing; raising tells the script instead of losing its write
+  (coordinator, 2026-10-14). A held `_Cell` or `_Row` is still found by its
+  place in its table.
+
 - **`_Cell.merge` raises `InvalidSpanError` for every span that would cut
   through a merged cell.** It merges what python-docx merges and refuses
   what python-docx refuses (an L- or T-shaped pair of corners), but where
@@ -990,8 +1041,9 @@ architecture or a DOCX Studio constraint:
   `""`.** `Document.add_comment` / `Comments.add_comment` send `author`
   and `initials` and docx-studio stores them as `w:author` /
   `w:initials`, as python-docx does; with none (python-docx's default
-  `""`) the author is `Document.user_name`, else `"Athena"`, and no
-  initials are stored (`initials` then reads `None`). The SDK raises
+  `""`) the author is `Document.user_name`, else the signed-in user agora's
+  access check names as an agent writes for them, "Jane Doe (Athena)" (the
+  author of the batch's tracked changes), else `"Athena"`, and no initials are stored (`initials` then reads `None`). The SDK raises
   `ValueError` for what lxml refuses in an attribute, as python-docx
   does, and also past docx-studio's caps (255 UTF-16 code units for an
   author, 32 for initials); docx-studio turns tabs, line breaks and other

{athena_python_docx-0.29.0 → athena_python_docx-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.29.0
+Version: 0.31.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.29.0 → athena_python_docx-0.31.0}/docx/__init__.py

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

{athena_python_docx-0.29.0 → athena_python_docx-0.31.0}/docx/_buffer.py

@@ -102,6 +102,54 @@ def _apply_proxy_id_rewrites(
                     pass
 
 
+_WRITES_UNAPPLIED = "_docx_writes_unapplied"
+
+
+def writes_unapplied(exc: BaseException) -> bool:
+    """True for the failure of a batch whose buffered writes docx-studio did
+    not apply (or may not have): a flush of them, a read they rode with, or
+    the idle timer's flush. A read that flushed them raises it rather than
+    fall back as it would for a failure of its own, so the script hears of
+    the write as python-docx would have failed at the write itself."""
+    return getattr(exc, _WRITES_UNAPPLIED, False) is True
+
+
+def _unapplied_writes(exc: BaseException) -> BaseException:
+    """``exc``, marked as the failure of buffered writes (:func:`writes_unapplied`)."""
+    if not writes_unapplied(exc):
+        setattr(exc, _WRITES_UNAPPLIED, True)
+        exc.add_note("the buffered writes this call sent to docx-studio were not applied")
+    return exc
+
+
+_REPORTED_ARGS = "_docx_reported_args"
+
+
+def keep_reported_message(exc: BaseException) -> None:
+    """Keep ``exc``'s message as it was raised, before a flush's account of
+    what of it docx-studio applied is put ahead of it (``_flush_outcome``), so
+    that a read whose buffered writes were sent again on their own can raise
+    its failure as its own (:func:`_as_the_read_s_own_failure`)."""
+    if not hasattr(exc, _REPORTED_ARGS):
+        setattr(exc, _REPORTED_ARGS, exc.args)
+
+
+def _as_the_read_s_own_failure(exc: BaseException, read: Command) -> None:
+    """``exc``, the failure of the read ``read`` whose buffered writes were
+    sent again on their own and applied, saying only that the read failed:
+    its message as docx-studio gave it, without the flush's account that the
+    writes did not land, ``read`` the one command that did not land
+    (``unapplied_commands``, ``failed_command``), and nothing applied before
+    it (``partial_applied``). A caller re-applying what the error names then
+    repeats no write."""
+    reported: object = getattr(exc, _REPORTED_ARGS, None)
+    if isinstance(reported, tuple):
+        exc.args = reported
+    exc.unapplied_commands = [read]  # type: ignore[attr-defined]
+    exc.failed_command = read  # type: ignore[attr-defined]
+    exc.partial_applied = []  # type: ignore[attr-defined]
+
+
 def _repeatable_read_key(cmd: Command) -> str | None:
     """The key a repeat of ``cmd`` answers from (:meth:`CommandBuffer.call`):
     a ``GetNodeById``'s wire form; ``None`` for any other command."""
@@ -677,9 +725,11 @@ class CommandBuffer:
             # See ``_apply_proxy_id_rewrites`` for the full rationale.
             _apply_proxy_id_rewrites(_extract_partial_results(exc), proxy_id_refs)
             _ptc_emit_end_batch(pending, is_error=True)
+            _unapplied_writes(exc)
             raise
-        except Exception:
+        except Exception as exc:
             _ptc_emit_end_batch(pending, is_error=True)
+            _unapplied_writes(exc)
             raise
         finally:
             _forget_reads_of_others(self)
@@ -751,10 +801,17 @@ class CommandBuffer:
             # the trailing ``cmd`` would otherwise abandon every
             # buffered Create's rewrite at once.
             _apply_proxy_id_rewrites(_extract_partial_results(exc), proxy_id_refs)
-            _ptc_emit_end_batch(all_cmds, is_error=True)
+            _ptc_emit_end_batch([cmd], is_error=True)
+            if pending:
+                self._settle_writes_of_failed_read(
+                    exc, pending, change_mode=change_mode, user=user, proxy_id_refs=proxy_id_refs
+                )
             raise
-        except Exception:
+        except Exception as exc:
             _ptc_emit_end_batch(all_cmds, is_error=True)
+            if pending:
+                # Whether the request landed is not known (a timeout, a dropped connection).
+                _unapplied_writes(exc)
             raise
         finally:
             # A batch of one node read changes nothing another buffer read.
@@ -788,6 +845,51 @@ class CommandBuffer:
         trailing = results[-1]
         return trailing if trailing is not None else {}
 
+    def _settle_writes_of_failed_read(
+        self,
+        exc: DocxError,
+        pending: list[Command],
+        *,
+        change_mode: str | None,
+        user: dict[str, str] | None,
+        proxy_id_refs: "dict[str, list[tuple[object, str]]]",
+    ) -> None:
+        """The buffered writes ``pending`` that rode with a read whose batch
+        failed (``exc``). docx-studio applies a batch all or nothing, so when
+        it reported the read itself failing, it applied none of the writes:
+        they are sent again on their own, and the read's failure stays its own
+        to report, as a read's fallback expects: once they landed, it names the
+        read alone as what did not land (:func:`_as_the_read_s_own_failure`).
+        Any other failure (one of the writes, or one not reported) marks
+        ``exc`` as one of unapplied writes (:func:`writes_unapplied`), and a
+        failure of the writes sent again is raised as one."""
+        unapplied = getattr(exc, "unapplied_commands", None)
+        failed = getattr(exc, "failed_command", None)
+        if not (isinstance(unapplied, list) and unapplied and failed is unapplied[-1]):
+            _ptc_emit_end_batch(pending, is_error=True)
+            _unapplied_writes(exc)
+            return
+        writes = unapplied[:-1]
+        if not writes:
+            # An older docx-studio kept the writes ahead of the read.
+            _ptc_emit_end_batch(pending, is_error=False)
+            return
+        try:
+            results, _skipped = self._client.execute_batch(
+                self._asset_id, writes, change_mode=change_mode, user=user
+            )
+        except Exception as again:
+            # The writes sent again go in requests of at most
+            # ``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)
+            _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)
+        _as_the_read_s_own_failure(exc, failed)
+
     def _reset_timer_locked(self) -> None:
         # Caller must hold self._lock.
         self._cancel_timer_locked()
@@ -852,6 +954,8 @@ class CommandBuffer:
                 "raised by a background docx-sdk auto-flush that failed earlier; "
                 "the commands in that batch were NOT applied",
             )
+            # Marked as unapplied writes by the flush (``_flush_in_order``):
+            # the read it surfaces in next raises it rather than fall back.
             with self._lock:
                 self._deferred_flush_error = e
             sys.stderr.write(

{athena_python_docx-0.29.0 → athena_python_docx-0.31.0}/docx/_capabilities.py

@@ -14,6 +14,14 @@ from typing import Any
 
 from docx._batching import run_sync
 
+# What this SDK declares in ``client.capabilities``: it holds the anchored table
+# ids (``t:N/R:C/K…@FIRST.LAST``) a docx-studio gives a client declaring it, and
+# sends them back as given. docx-studio then finds each held table by its
+# paragraphs, wherever an edit moved it, and refuses the command with
+# ``StaleTable`` when no one table holds them (``docx.errors.StaleTableError``).
+# An older docx-studio gives none, so the SDK needs no check.
+TABLE_ANCHORS_CLIENT_CAPABILITY = "tableAnchors"
+
 # Session -> the capabilities its server reported, read once.
 _capabilities: "weakref.WeakKeyDictionary[Any, dict[str, Any]]" = weakref.WeakKeyDictionary()
 

{athena_python_docx-0.29.0 → athena_python_docx-0.31.0}/docx/_http_doc.py

@@ -4,7 +4,8 @@ Wire format (matches ``apps/api/src/commands/types.ts``):
 
     POST /docs/:id/commands
     {
-      "client": {"type": "python-sdk", "version": "<x.y.z>", "capabilities": ["trackedAuthoring"]},
+      "client": {"type": "python-sdk", "version": "<x.y.z>",
+                 "capabilities": ["trackedAuthoring", "trackedMinimalParagraphText", "tableAnchors"]},
       "commands": [
         {"type": "CreateParagraph", "text": "Hi", "at": {"kind": "documentEnd"}},
         ...
@@ -41,8 +42,9 @@ from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
 from docx._batching import call_abandoned, note_progress
-from docx._buffer import CommandBuffer
-from docx._tracked import TRACKED_AUTHORING_CAPABILITY
+from docx._buffer import CommandBuffer, keep_reported_message
+from docx._tracked import TRACKED_AUTHORING_CAPABILITY, TRACKED_MINIMAL_PARAGRAPH_TEXT_CAPABILITY
+from docx._capabilities import TABLE_ANCHORS_CLIENT_CAPABILITY
 from docx._timeouts import (
     DEFAULT_OP_TIMEOUT_SECONDS,
     LONG_RUNNING_COMMAND_TIMEOUT_SECONDS,
@@ -89,6 +91,7 @@ from docx.commands import (
     CreateTOC,
     CreateWatermark,
     DeleteBookmark,
+    DeleteParagraph,
     DeleteWatermark,
     EndnotesDelete,
     EndnotesGet,
@@ -192,6 +195,7 @@ from docx.errors import (
     NotFoundError,
     NotNumberedListItemError,
     SessionError,
+    StaleTableError,
     _missing_block_id,
 )
 from docx.exceptions import InvalidSpanError
@@ -282,6 +286,7 @@ def _flush_outcome(
             f" applied{not_sent}.{offered} Re-read the document to see whether that"
             " request landed before re-applying anything."
         )
+        keep_reported_message(exc)
         exc.args = (f"{prefix}\n\n{exc.args[0] if exc.args else ''}", *exc.args[1:])
         return exc
     applied = min(start + landed, total)
@@ -331,6 +336,7 @@ def _flush_outcome(
         f" nothing{not_sent}. `exc.unapplied_commands` holds the {len(unapplied)}"
         f" that did not land{which}. {redo}"
     )
+    keep_reported_message(exc)
     exc.args = (f"{prefix}\n\n{exc.args[0] if exc.args else ''}", *exc.args[1:])
     return exc
 
@@ -836,6 +842,13 @@ def _http_post_json(
                     err_obj,
                     partial_applied,
                 )
+            # A held ``Table`` whose table is gone (``docx.table`` anchored ids).
+            if err_obj.get("error") == "StaleTable":
+                raise _reported(
+                    StaleTableError(str(err_obj.get("message") or base_msg)),
+                    err_obj,
+                    partial_applied,
+                )
             # ``Paragraph.restart_numbering`` on a paragraph that takes no number.
             if err_obj.get("error") == "NotNumberedListItem":
                 raise _reported(
@@ -1194,8 +1207,14 @@ class HttpClient:
             "client": {
                 "type": "python-sdk",
                 "version": _sdk_version(),
-                # Keeps its offsets as a tracked edit moves them (``docx._tracked``).
-                "capabilities": [TRACKED_AUTHORING_CAPABILITY],
+                # Keeps its offsets as a tracked edit moves them, and reads a
+                # paragraph's length back after a tracked ``paragraph.text``
+                # (``docx._tracked``); holds anchored table ids (``docx.table``).
+                "capabilities": [
+                    TRACKED_AUTHORING_CAPABILITY,
+                    TRACKED_MINIMAL_PARAGRAPH_TEXT_CAPABILITY,
+                    TABLE_ANCHORS_CLIENT_CAPABILITY,
+                ],
             },
             "commands": [
                 _with_real_ids(c.to_dict(), ids) if ids else c.to_dict() for c in commands
@@ -1475,6 +1494,7 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "sections.set_columns": SetSectionColumns,
     "find_replace": FindReplace,
     "clear_body": ClearBody,
+    "delete_paragraph": DeleteParagraph,
     "find_text": FindText,
     "iter_runs": IterRuns,
     "export_pdf": ExportPDF,