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

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

@@ -40,12 +40,14 @@ These standard python-docx members don't apply to a DOCX Studio-backed SDK:
 - `Document.part`, `Paragraph.part`, `Run.part` — package part access
 - `Document.settings` — Word app settings (not surfaced by DOCX Studio)
 - `InlineShape.chart` — charts are not currently surfaced by the SDK.
-- `Comment.add_paragraph` / `Comment.add_table` /
-  `Comment.iter_inner_content` / `Comment.paragraphs` /
-  `Comment.tables` — DOCX Studio models a comment as a single text body.
-  `Comment` is a `docx.blkcntnr.BlockItemContainer`, as `_Cell` and the
-  header/footer proxies are, but its paragraph/table-bearing surface raises
-  `CommentsNotImplementedError`. Use `Comment.text` instead.
+- `Comment.add_table` / `Comment.tables` — a DOCX Studio comment holds
+  paragraphs only. `Comment` is a `docx.blkcntnr.BlockItemContainer`, as
+  `_Cell` and the header/footer proxies are: `paragraphs`,
+  `add_paragraph`, `iter_inner_content` and `text` work as in python-docx
+  1.2.0 (the paragraphs list the comment's story, `blocks.list` with
+  `in: {storyType: "comment"}`, and `add_paragraph` sends
+  `CommentsParagraphAppend`), while `tables` is empty and `add_table`
+  raises `CommentsNotImplementedError`.
 - **`_Cell.add_table(rows, cols)`** — surface preserved for parity
   (signature matches python-docx, no `width` kwarg) but raises
   :class:`docx.errors.NestedTableNotSupportedError` (subclass of
@@ -188,22 +190,33 @@ not file-backed. Each is documented in the relevant docstring.
   on the other studios: `Workbook.workbook_id` (xlsx) and
   `Presentation.deck_id` (pptx).
 
-- **`Document.save(path_or_stream=None)`** — argument is optional and,
-  when supplied, raises
-  :class:`docx.errors.LocalSaveTargetNotSupportedError`. Stock
-  python-docx requires it and `TypeError`s on no-arg, but in an
-  asset-backed SDK there is no local file to write — writes are always
-  in-place against the Y.Doc. Forcing the upstream signature broke
-  every agent invocation that reflexively called `doc.save()` (a
-  near-universal Python pattern), so the no-arg form is supported.
-  When a path or stream IS supplied, the SDK cannot fulfill the
-  implied "write bytes to this target" contract, so the call raises
-  loudly rather than silently flushing — agents must use Olympus's
-  Export DOCX (which goes through the DOCX Studio session that already
-  has the bytes) instead of expecting a local file.
-
-- **`Document.track_revisions: bool`** — when `True`, all subsequent
-  mutations are recorded as tracked revisions instead of direct edits.
+- **`Document.save(path_or_stream=None)`** — the argument is optional.
+  Stock python-docx requires it and `TypeError`s on no-arg, but writes
+  are always in place against the Y.Doc, and forcing the upstream
+  signature broke every agent invocation that reflexively called
+  `doc.save()`, so the no-arg form flushes and writes no file. With a
+  path (`str` or `os.PathLike`) or a binary stream, `save` also writes
+  the document's `.docx` there, as python-docx does, through
+  `export_docx` (0.29.0+; earlier versions raised
+  `LocalSaveTargetNotSupportedError`, which stays importable).
+
+- **`Document.track_revisions: bool`** — when `True`, subsequent batches
+  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_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
+  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,
+  comments and `TrackChangesDecide` run either way
+  (`DOCX_STUDIO_LIMITATIONS.md` § 32).
   python-docx upstream has no top-level toggle (the closest is
   hand-edited `<w:trackChanges/>` on `Document.settings.element`).
   We expose this as a Document-level property because every DOCX Studio
@@ -219,10 +232,12 @@ not file-backed. Each is documented in the relevant docstring.
   because the upstream package has no track-changes API at all.
 
 - **`Document.user_name: str | None` / `Document.user_email: str |
-  None`** — author identity threaded through to DOCX Studio on session-
-  open for tracked-change attribution; DOCX Studio bakes them into the
-  change records. Separate from `Document.core_properties.last_modified_by`,
-  the `docProps/core.xml` metadata the SDK reads and writes as python-docx
+  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.
+  Separate from `Document.core_properties.last_modified_by`, the
+  `docProps/core.xml` metadata the SDK reads and writes as python-docx
   does.
 
 - **`Document.revisions: Revisions`** — collection of tracked changes
@@ -278,9 +293,10 @@ Issue numbers reference `python-openxml/python-docx`.
   `"FILENAME"`, `"NUMWORDS"`, `"REF"`, `"SEQ"`, `"TOC"`, and the
   generic `"FIELD"` escape hatch. python-docx has no field API
   whatsoever; issue #498 (page numbers) and #31 (23 comments) demand
-  this. `Fields` is sequence-like; `Fields.refresh_all(scope?)`
-  forces a recompute. Routes through `CreateField` / `FieldsRefresh`
-  / `FieldsList`.
+  this. `Fields` is sequence-like; `Fields.refresh_all(scope?)` updates
+  every unlocked REF and SEQ result as Word's F9 does (PAGE, PAGEREF
+  and TOC results depend on pages and stay). Routes through
+  `CreateField` / `FieldsRefresh` / `FieldsList`.
 
 - **`Document.bookmarks: Bookmarks`** + **`Paragraph.add_bookmark
   (name)`** + **`Document.add_bookmark(name, *, paragraph=None,
@@ -611,12 +627,10 @@ Issue numbers reference `python-openxml/python-docx`.
 
 - **`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
-  left by ``Document.save(path)`` raising
-  ``LocalSaveTargetNotSupportedError`` in this SDK: parity test
-  harnesses and CI workflows need a programmatic .docx export to
-  diff against ``python-docx`` output that doesn't require a
-  human-driven Olympus UI action. Routes through ``ExportDocx`` →
+  ``.docx`` bytes, optionally writing to ``path``; ``Document.save(path_or_stream)``
+  writes its file through it. Parity test harnesses and CI workflows
+  use it to diff against ``python-docx`` output without a human-driven
+  Olympus UI action. Routes through ``ExportDocx`` →
   apps/api's backend export path. apps/api
   writes the session state to a temp ``.docx``, reads bytes back,
   base64-encodes for the wire, and unlinks the temp in a
@@ -625,6 +639,26 @@ Issue numbers reference `python-openxml/python-docx`.
   the current backend export path has no ``includeRevisions`` support,
   so honoring the flag isn't possible yet.
 
+  ``export_docx(path=None, *, include_revisions=False, clean=False,
+  clear_title=False)`` (0.29.0+): called with ``clean=True`` it returns a
+  clean copy for sending outside the firm instead, from
+  ``GET /docs/:id/export.docx?clean=1`` (VIEW gate): docx-studio imports
+  the export into an in-memory room, accepts every tracked change and
+  deletes every comment through the command runner, exports that room and
+  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
+  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,
+  footer or note still holds a tracked change (the engine accepts the
+  body's only; ``DOCX_STUDIO_LIMITATIONS.md`` § 31). The in-process
+  post-export rewrites are applied to a clean copy as to a plain export,
+  and the copy is refused (``DocxError``) if they put revision, comment or
+  rsid markup back into ``word/document.xml``.
+
   Template seeding: ``Document.create()`` (no ``docx=``) already
   produces an exportable asset because ``POST /docs/empty`` seeds
   from the default Athena template, so ``export_docx`` works
@@ -915,6 +949,18 @@ architecture or a DOCX Studio constraint:
   but DOCX Studio's ProseMirror table node can't represent one; the SDK
   raises eagerly rather than failing opaquely on the wire.
 
+- **`Document.add_table` writes Athena's brand table.** Owner decision
+  (2026-10-12): keep the brand defaults. The table's layout is fixed, so
+  `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`;
+  an imported table's gaps stay gaps, and so do the two cases whose
+  `cell_format` also differs for another cause (`except`).
+
 - **`_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
@@ -953,6 +999,18 @@ architecture or a DOCX Studio constraint:
   Keryx attributes the edit to the signed-in user (and agent), and
   nothing reads a comment's author as identity.
 
+- **A comment's paragraphs are in Word's comment style, which the export
+  defines.** python-docx 1.2.0's `add_comment` and `Comment.add_paragraph`
+  write `w:pStyle CommentText` (Word's built-in "annotation text", Comment
+  Text in Word's UI) without defining the style in `styles.xml`, so
+  python-docx reads those paragraphs as Normal. docx-studio writes the same
+  `w:pStyle` and defines the style as Word does: `Comment.paragraphs[i].style`
+  reads `Comment Text` (a built-in the document lacks reads back as that
+  built-in, as above), and the export adds Word's definition of the style and
+  of its linked `Comment Text Char` to `styles.xml`, so python-docx reads the
+  exported paragraph as `annotation text`. Owner decision, 2026-10-12.
+  Recorded in `tests/parity/intentional_deviations.json` (`live_deviations`).
+
 - **`ParagraphFormat.line_spacing_rule = None` warns-and-preserves on a
   clear** rather than raising (upstream accepts `None` to clear, but DOCX
   Studio's merging mutation ops have no single-attribute clear). It emits a
@@ -970,7 +1028,17 @@ architecture or a DOCX Studio constraint:
   given. `Run.add_tab()` and `Run.add_break()` take the run's formatting, as
   upstream appends them to the run's `w:r`; `Run.add_break(WD_BREAK.COLUMN)`
   sends a column break (`breakType: "column"`), which docx-studio writes after
-  the paragraph's content. `DOCX_STUDIO_LIMITATIONS.md` §26.
+  the paragraph's content. `DOCX_STUDIO_LIMITATIONS.md` §26. `Run.text` and
+  `Paragraph.text` leave a ruby's base text out (`w:ruby`, a phonetic guide
+  over its base text), as upstream reads only a run's own text elements, while
+  the base text keeps its room in the text-address space (`ruby` spans on the
+  read's run; `tests/test_ruby_reads_python_docx_parity.py`). That holds while
+  the paragraph's runs are as its records hold them, in the body, a table cell,
+  a header, a footer or a comment; a paragraph with a link or a tracked change
+  reads its runs from their marks, the base text included. A write to the run
+  (its text, an append, its formatting) makes the base text ordinary text,
+  which then reads as text: docx-studio keeps no guide through an edit, where
+  upstream keeps the `w:ruby` through all but a text write.
 
 - **`CoreProperties.modified` is the time of the last save.** The asset is a
   live Word document, and docx-studio stamps `dcterms:modified` when it saves
@@ -1104,6 +1172,15 @@ This is a **thin HTTP client** that mimics the sync python-docx API.
   the context-manager exit drain explicitly; `docx.flush_all()` is
   the executor-postamble hook that flushes every live buffer in the
   process.
+- A flush of more than 500 commands (`MAX_BATCH_COMMANDS`,
+  docx-studio's request cap) goes out as consecutive requests, and
+  docx-studio applies each all or nothing: when one fails, the requests
+  before it are saved and it and every later one are not. The
+  `DocxError` (0.29.0+) says how many of the flush's commands were
+  applied and names the failed one by its flush index; it carries
+  `unapplied_commands` and `failed_command`, and `partial_applied`
+  holds the saved requests' results. A retry re-applies the unapplied
+  edits, never the whole flush.
 - Execution scope: executor sandboxes may keep Python globals
   between tool calls so imports, constants, and helper functions can be
   reused. Live SDK objects are different. The executor calls

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

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

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

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

@@ -43,7 +43,13 @@ from docx._execution import (
     is_stale_execution,
 )
 from docx._timeouts import timeout_for_commands
-from docx.commands import Command, GetNodeById, is_response_bearing, must_flush_immediately
+from docx.commands import (
+    Command,
+    GetNodeById,
+    is_query,
+    is_response_bearing,
+    must_flush_immediately,
+)
 from docx.errors import DocxError, DocxUnsupportedCommandError, FlushAllError
 
 
@@ -402,6 +408,11 @@ class CommandBuffer:
         # The last command's ``GetNodeById`` key, result and time, while
         # nothing has been sent or buffered after it (see :meth:`call`).
         self._last_read: tuple[str, Any, float] | None = None
+        # Counts each command that may change the document (anything but a
+        # query) this buffer has taken, buffered or sent, and each
+        # forget_reads(): a read kept from an earlier count (a ``Table``'s
+        # ``tables.get``) may no longer show the document. See ``writes``.
+        self._writes: int = 0
         _register(self)
 
     def register_proxy_id_ref(self, client_id: str, proxy: object, attr: str = "_node_id") -> None:
@@ -460,10 +471,15 @@ class CommandBuffer:
         if current == mode:
             return
         # Drain any queued commands with the *previous* mode before
-        # adopting the new one.
-        self.flush()
-        with self._lock:
-            self._change_mode = mode
+        # adopting the new one. The new mode is adopted even when that
+        # flush raises (docx-studio refuses a tracked batch that edits):
+        # ``Document`` has already recorded the new flag, so keeping the
+        # old mode here would refuse every later direct edit.
+        try:
+            self.flush()
+        finally:
+            with self._lock:
+                self._change_mode = mode
 
     def set_user(self, name: str | None, email: str | None = None) -> None:
         """Set the batch-level user identity.
@@ -485,11 +501,34 @@ class CommandBuffer:
             if email:
                 self._user["email"] = email
 
+    @property
+    def writes(self) -> int:
+        """How many commands that may change the document this buffer has
+        taken, buffered or sent, plus each :meth:`forget_reads` (which a batch
+        another handle of the document sends calls). A read kept at one count
+        shows the document while the count stays, but for a collaborator's
+        edit."""
+        with self._lock:
+            return self._writes
+
     def forget_reads(self) -> None:
         """The next node read goes to the server, not to the read before it
-        (:meth:`call`): for a read that checks the document before a write."""
+        (:meth:`call`), and so does a table's next read (``writes``): for a
+        read that checks the document before a write."""
         with self._lock:
             self._last_read = None
+            self._writes += 1
+
+    def ensure_usable(self) -> None:
+        """Raise as :meth:`call` does before it sends or reuses anything: for a
+        buffer of an earlier execution, a batch the idle timer failed to send,
+        and a closed buffer. A read kept outside the buffer checks it too."""
+        self._assert_current_execution()
+        self._raise_deferred_flush_error()
+        if self._closed:
+            raise RuntimeError(
+                f"CommandBuffer for {self._asset_id} is closed",
+            )
 
     def call(self, cmd: Command) -> Any:
         """Execute or buffer ``cmd``.
@@ -508,12 +547,7 @@ class CommandBuffer:
         ``clientIdMap`` on flush and the buffer rewrites each registered
         proxy's ``_node_id`` in-place.
         """
-        self._assert_current_execution()
-        self._raise_deferred_flush_error()
-        if self._closed:
-            raise RuntimeError(
-                f"CommandBuffer for {self._asset_id} is closed",
-            )
+        self.ensure_usable()
 
         # A read of the node the last command read, with nothing sent or
         # buffered since and within READ_REUSE_SECONDS of it, answers from
@@ -532,6 +566,9 @@ class CommandBuffer:
             and _now() - last_read[2] <= READ_REUSE_SECONDS
         ):
             return copy.deepcopy(last_read[1])
+        if not is_query(cmd):
+            with self._lock:
+                self._writes += 1
 
         # PTC begin: emit only for commands in the allow-list. Other
         # commands still flow through the buffer (and through the batched

athena_python_docx-0.29.0/docx/_capabilities.py

@@ -0,0 +1,38 @@
+"""What the docx-studio a session talks to takes, from its ``Info`` reply.
+
+A command shape an older docx-studio would refuse (``InsertLineBreak`` with
+``breakType: "page"``) is sent only to a server that names it in
+``Info.capabilities``; a server that names none gets the older shape. The
+promotion rings put tenants on different docx-studio trains, so an SDK release
+meets servers from before and after the capability.
+"""
+
+from __future__ import annotations
+
+import weakref
+from typing import Any
+
+from docx._batching import run_sync
+
+# Session -> the capabilities its server reported, read once.
+_capabilities: "weakref.WeakKeyDictionary[Any, dict[str, Any]]" = weakref.WeakKeyDictionary()
+
+
+def server_takes(session: Any, capability: str) -> bool:
+    """True when the session's docx-studio reports ``capability``
+    (``Info.capabilities``), read on first use and kept for the session.
+
+    ``Info`` flushes the edits queued before it, as every read does.
+    """
+    if session is None:
+        return False
+    try:
+        known = _capabilities.get(session)
+    except TypeError:
+        return False
+    if known is None:
+        info: object = run_sync(session.doc.info({}))
+        reported = info.get("capabilities") if isinstance(info, dict) else None
+        known = reported if isinstance(reported, dict) else {}
+        _capabilities[session] = known
+    return known.get(capability) is True