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

{athena_python_docx-0.29.0 → athena_python_docx-0.30.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,
@@ -990,8 +1022,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.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.29.0
+Version: 0.30.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.30.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.30.0"
 
 from docx.api import Document
 from docx._buffer import discard_all, flush_all

{athena_python_docx-0.29.0 → athena_python_docx-0.30.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"]},
       "commands": [
         {"type": "CreateParagraph", "text": "Hi", "at": {"kind": "documentEnd"}},
         ...
@@ -42,7 +43,7 @@ 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._tracked import TRACKED_AUTHORING_CAPABILITY, TRACKED_MINIMAL_PARAGRAPH_TEXT_CAPABILITY
 from docx._timeouts import (
     DEFAULT_OP_TIMEOUT_SECONDS,
     LONG_RUNNING_COMMAND_TIMEOUT_SECONDS,
@@ -89,6 +90,7 @@ from docx.commands import (
     CreateTOC,
     CreateWatermark,
     DeleteBookmark,
+    DeleteParagraph,
     DeleteWatermark,
     EndnotesDelete,
     EndnotesGet,
@@ -1194,8 +1196,13 @@ 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``).
+                "capabilities": [
+                    TRACKED_AUTHORING_CAPABILITY,
+                    TRACKED_MINIMAL_PARAGRAPH_TEXT_CAPABILITY,
+                ],
             },
             "commands": [
                 _with_real_ids(c.to_dict(), ids) if ids else c.to_dict() for c in commands
@@ -1475,6 +1482,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,

{athena_python_docx-0.29.0 → athena_python_docx-0.30.0}/docx/_postproc.py

@@ -520,6 +520,15 @@ class PostExportOps:
             or bool(self._row_cant_split_ops)
         )
 
+    def forget_captured_refs(self) -> None:
+        """Drop the captured REF paragraphs (``Paragraph.delete``).
+
+        They are addressed by their index among the body's paragraphs, which
+        a deleted paragraph shifts, so a capture could restore over the
+        paragraph after the one it was taken from.
+        """
+        self._captured_refs.clear()
+
     def discard_body_ops(self) -> None:
         """Drop every rewrite that addresses body content by position.
 
@@ -1402,6 +1411,17 @@ def _count_ref_fields(p: ET.Element) -> int:
     return count
 
 
+_REVISION_TAGS = frozenset(
+    f"{W_NS}{name}" for name in ("ins", "del", "moveFrom", "moveTo", "delInstrText")
+)
+
+
+def _holds_revisions(p: ET.Element) -> bool:
+    """True when the paragraph holds tracked-change markup: an insertion,
+    a deletion or a move, of its runs or of its paragraph mark."""
+    return any(el.tag in _REVISION_TAGS for el in p.iter())
+
+
 def _iter_captured_ref_paragraphs(
     body: ET.Element,
 ) -> "Iterable[CapturedRefParagraph]":
@@ -1503,6 +1523,11 @@ def _restore_stripped_refs(
         if _count_ref_fields(exported) >= entry.ref_count:
             # DOCX Studio kept the REFs; nothing to do.
             continue
+        if _holds_revisions(exported):
+            # A tracked change (a deleted paragraph's REF is a
+            # ``w:delInstrText`` in a ``w:del``) is an edit, not a strip:
+            # restoring the source would drop it from the export.
+            continue
         if _paragraph_fingerprint(exported) != entry.fingerprint:
             # The paragraph diverged on round-trip — user edited it or
             # DOCX Studio materially changed its text. Skip rather than

{athena_python_docx-0.29.0 → athena_python_docx-0.30.0}/docx/_tracked.py

@@ -11,6 +11,13 @@ text in place.
 The SDK declares that it keeps its offsets this way
 (:data:`TRACKED_AUTHORING_CAPABILITY` in ``client.capabilities``); a
 docx-studio records a python-sdk's tracked edits only from an SDK that does.
+
+A tracked ``paragraph.text = value`` is the exception: docx-studio marks only
+the words that change (the words the old and new text share at their start
+and end stay as they are), so the paragraph's new length is known only to the
+server. The SDK forgets the length and reads it back before the next edit
+that needs it, and says so (:data:`TRACKED_MINIMAL_PARAGRAPH_TEXT_CAPABILITY`);
+a docx-studio replaces the whole text for an SDK that does not.
 """
 
 from __future__ import annotations
@@ -20,6 +27,10 @@ from typing import Any
 #: What the SDK tells docx-studio in ``client.capabilities`` on every batch.
 TRACKED_AUTHORING_CAPABILITY = "trackedAuthoring"
 
+#: Also sent: the SDK reads a paragraph's length back after a tracked
+#: ``paragraph.text = value``, so docx-studio may mark only what changes.
+TRACKED_MINIMAL_PARAGRAPH_TEXT_CAPABILITY = "trackedMinimalParagraphText"
+
 
 def tracking(session: Any) -> bool:
     """True when ``session``'s writes go out with ``changeMode: "tracked"``

{athena_python_docx-0.29.0 → athena_python_docx-0.30.0}/docx/commands.py

@@ -781,8 +781,8 @@ class CommentsCreate(Command):
     target: dict[str, Any] | None = None
     parent_id: str | None = None
     # Word's ``w:author`` / ``w:initials`` (display text). Left unset, the
-    # comment's author is the batch's ``user.name``, else "Athena", and it
-    # has no initials.
+    # comment's author is the batch's ``user.name``, else the user agora's
+    # access check names, else "Athena", and it has no initials.
     author: str | None = None
     initials: str | None = None
     # Optional client-assigned entity id for transparent-batched
@@ -1770,6 +1770,19 @@ class ClearBody(Command):
     """
 
 
+@dataclass
+class DeleteParagraph(Command):
+    """Delete a whole body paragraph (:meth:`Paragraph.delete`).
+
+    Athena extension: python-docx has no paragraph delete. Direct, DOCX Studio
+    removes the paragraph; with ``track_revisions`` it keeps it as Word's
+    tracked deletion of its content and its paragraph mark, fields included,
+    which Accept All removes and Reject All restores. Returns ``{changed}``.
+    """
+
+    block_id: str = ""
+
+
 @dataclass
 class FindText(Command):
     """Search document text and return bounded match context.
@@ -2003,6 +2016,9 @@ _RESPONSE_BEARING_TYPES: frozenset[str] = frozenset(
         # ClearBody replaces the whole body; Document.clear awaits it so a
         # rejected clear raises instead of leaving stale content behind.
         "ClearBody",
+        # DeleteParagraph returns {changed}; Paragraph.delete awaits it so a
+        # refused delete raises at the call.
+        "DeleteParagraph",
         # TablesMergeCells returns the merged cell, which ``_Cell.merge``
         # returns; an invalid span raises InvalidSpanError at the call, as in
         # python-docx.
@@ -2104,6 +2120,7 @@ for _cls, _issue, _desc in [
     (SetSectionColumns, "python-docx#167", "Section multi-column layout"),
     (FindReplace, "python-docx#30", "Formatting-preserving find/replace"),
     (ClearBody, None, "Document.clear — bulk body reset"),
+    (DeleteParagraph, "python-docx#33", "Paragraph.delete — whole paragraph delete"),
     (FindText, "python-docx#980", "Fast document text search"),
     (IterRuns, "python-docx#980", "Run stream for run-isolation"),
     (ExportPDF, "python-docx#113", "PDF export"),
@@ -2247,6 +2264,7 @@ __all__ = [
     "SetSectionColumns",
     "FindReplace",
     "ClearBody",
+    "DeleteParagraph",
     "FindText",
     "IterRuns",
     "ExportPDF",

{athena_python_docx-0.29.0 → athena_python_docx-0.30.0}/docx/comments.py

@@ -216,7 +216,8 @@ def _comment_display_fields(
     so does docx-studio, as display text only: Keryx attributes the write
     itself to the signed-in user (and agent). An empty author, python-docx's
     default, is not sent, so the comment keeps the session's name
-    (``Document.user_name``, else "Athena"); empty or ``None`` initials are
+    (``Document.user_name``, else the signed-in user, else "Athena"); empty
+    or ``None`` initials are
     not sent either. docx-studio turns tabs, line breaks and other control
     characters into spaces.
     """
@@ -492,7 +493,8 @@ class Comments:
         ``w:initials``. They are display text; the edit itself is
         attributed to the signed-in user. Without an ``author`` the
         comment's author is the session's name (``Document.user_name``,
-        else "Athena"). Use :meth:`Document.add_comment` to thread a
+        else the signed-in user, else "Athena"). Use
+        :meth:`Document.add_comment` to thread a
         run-anchored target — this method creates an unanchored comment.
         """
         # python-docx 1.x routes ``text`` / ``author`` / ``initials``

{athena_python_docx-0.29.0 → athena_python_docx-0.30.0}/docx/document.py

@@ -853,7 +853,8 @@ class Document:
         ``initials`` as Word's ``w:author`` / ``w:initials`` (display
         text; the edit itself is attributed to the signed-in user). Without
         an ``author`` its author is the session's name
-        (:attr:`user_name`, else "Athena"). The runs must be co-located in
+        (:attr:`user_name`, else the signed-in user, else "Athena"). The
+        runs must be co-located in
         a single block (Word can't anchor a comment to disjoint blocks); if
         they span multiple blocks the comment is created unanchored.
         """

{athena_python_docx-0.29.0 → athena_python_docx-0.30.0}/docx/text/paragraph.py

@@ -11,6 +11,10 @@ from docx._batching import run_sync
 from docx._run_order import forget_paragraph, register_run
 from docx._tracked import tracking
 
+#: The session attribute ``Paragraph.delete`` bumps, after which every
+#: paragraph handle of the session reads its list number again.
+_NUMBERING_GENERATION_ATTR = "_docx_numbering_generation"
+
 if TYPE_CHECKING:
     from docx._references import AssetReference
     from docx.bookmarks import Bookmark
@@ -675,8 +679,10 @@ class Paragraph:
         )
         # We just replaced the entire paragraph contents with ``value``;
         # the new text-address length is simply ``len(value)``. With tracking
-        # on the old text stays, deleted, before ``value`` (``docx._tracked``).
-        self._text_len = current_len + len(value) if tracked else len(value)
+        # on docx-studio keeps the words the old and new text share and marks
+        # only the rest, so only the server knows the length: read it back
+        # before the next edit that needs it (``docx._tracked``).
+        self._text_len = None if tracked else len(value)
         # The runs of the paragraph are gone, as in python-docx.
         forget_paragraph(self)
         # Content changed — drop the prefetched snapshot so a follow-up
@@ -2141,8 +2147,77 @@ class Paragraph:
         )
         self._list_info_cache = None
 
+    @athena_extension(
+        issue=33,
+        since="0.30.0",
+        description="Paragraph.delete — delete the whole paragraph, as a tracked deletion with track_revisions.",
+    )
+    def delete(self) -> None:
+        """Delete this paragraph from the document, 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. ``paragraph.delete()`` does that here::
+
+            for p in doc.paragraphs:
+                if p.text.startswith("Forfeiture of Rights"):
+                    p.delete()
+
+        With tracking off the paragraph goes. With ``track_revisions`` on it
+        is Word's tracked deletion of a whole paragraph: all its content, its
+        cross-reference and other fields, links and note references included,
+        and its paragraph mark, one change by the signed-in user. Accept All
+        removes the paragraph and the numbered paragraphs after it number on;
+        Reject All gives it back as it was. Setting ``p.text = ""`` instead
+        leaves an empty (still numbered) paragraph behind.
+
+        The delete goes in a request of its own, after the edits buffered
+        before it, so a refused one takes none of them down.
+
+        Raises:
+            DocxError: docx-studio refused the delete, and changed nothing:
+                ``ParagraphDeleteRefused`` for the document's last paragraph
+                (Word never deletes its mark), one that ends a section, the
+                only paragraph of a table cell or content control, one holding
+                part of a field that spans paragraphs, and one in a header,
+                footer, comment or text box; with tracking on,
+                ``TrackedChangesUnsupported`` for one in a table cell or holding
+                a page break, a content control, a shape or an equation.
+        """
+        from docx.commands import DeleteParagraph
+
+        self._adopt_cell_paragraph()
+        run_sync(self._session.save())
+        run_sync(self._session.send_command(DeleteParagraph(block_id=self._node_id)))
+        # The template's REF paragraphs are restored on export by their body
+        # index (``docx._postproc``), which this delete may have shifted.
+        post_export_ops: object = getattr(self._session, "_post_export_ops", None)
+        forget = getattr(post_export_ops, "forget_captured_refs", None)
+        if callable(forget):
+            forget()
+        # Every handle's list number is read again: the items after this one renumber.
+        generation: object = getattr(self._session, _NUMBERING_GENERATION_ATTR, 0)
+        next_generation = (generation if isinstance(generation, int) else 0) + 1
+        try:
+            setattr(self._session, _NUMBERING_GENERATION_ATTR, next_generation)
+        except AttributeError:  # a session that takes no new attribute
+            pass
+        self._text_len = None
+        forget_paragraph(self)
+        self._invalidate_node_info()
+        self._list_info_cache = None
+
     def _list_info(self) -> dict | None:
-        """Cache-then-fetch the numbering record for this paragraph."""
+        """Cache-then-fetch the numbering record for this paragraph.
+
+        The cache holds until a paragraph of the session is deleted
+        (:meth:`delete` bumps the session's numbering generation): the list
+        items after it number again, so every handle reads its number anew.
+        """
+        generation: object = getattr(self._session, _NUMBERING_GENERATION_ATTR, 0)
+        if getattr(self, "_list_info_generation", 0) != generation:
+            self._list_info_cache = None
+            self._list_info_generation = generation
         cache = getattr(self, "_list_info_cache", None)
         if cache is not None:
             return cache or None

{athena_python_docx-0.29.0 → athena_python_docx-0.30.0}/pyproject.toml

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

{athena_python_docx-0.29.0 → athena_python_docx-0.30.0}/tests/live/baseline.json

@@ -173,6 +173,7 @@
   "fixture-bookmarks-internal-links",
   "fixture-breaks-inline",
   "fixture-breaks-tabs",
+  "fixture-character-style-toggles",
   "fixture-chart-column",
   "fixture-cjk-grid-theme-colors",
   "fixture-comments-links",
@@ -253,10 +254,5 @@
   "rw16_header_footer_tables",
   "rw17_header_letterhead_filled"
  ],
- "gaps": [
-  "fixture-headers-tabs-wrapped::reads::sections.header.paragraphs",
-  "fixture-tables-content-controls::reads::tables.cell_format",
-  "fixture-tables-content-controls::reads::tables.cells",
-  "fixture-tables-content-controls::reads::tables.rows"
- ]
+ "gaps": []
 }

{athena_python_docx-0.29.0 → athena_python_docx-0.30.0}/tests/test_athena_extensions_registry.py

@@ -113,6 +113,7 @@ _EXPECTED_LOCATIONS: set[str] = {
     "docx.text.paragraph.Paragraph.list_format",
     "docx.text.paragraph.Paragraph.list_number",
     "docx.text.paragraph.Paragraph.restart_numbering",
+    "docx.text.paragraph.Paragraph.delete",
     # Run methods.
     "docx.text.run.Run.add_field",
     "docx.text.run.Run.add_footnote",

{athena_python_docx-0.29.0 → athena_python_docx-0.30.0}/tests/test_http_transport.py

@@ -89,7 +89,7 @@ def test_path_proxy_walks_dotted_path() -> None:
     assert body["client"] == {
         "type": "python-sdk",
         "version": SDK_VERSION,
-        "capabilities": ["trackedAuthoring"],
+        "capabilities": ["trackedAuthoring", "trackedMinimalParagraphText"],
     }
     assert body["return"] == {"snapshot": False}
     assert body["commands"] == [