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

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

@@ -986,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

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

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

{athena_python_docx-0.30.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.30.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.30.0 → athena_python_docx-0.31.0}/docx/_http_doc.py

@@ -5,7 +5,7 @@ Wire format (matches ``apps/api/src/commands/types.ts``):
     POST /docs/:id/commands
     {
       "client": {"type": "python-sdk", "version": "<x.y.z>",
-                 "capabilities": ["trackedAuthoring", "trackedMinimalParagraphText"]},
+                 "capabilities": ["trackedAuthoring", "trackedMinimalParagraphText", "tableAnchors"]},
       "commands": [
         {"type": "CreateParagraph", "text": "Hi", "at": {"kind": "documentEnd"}},
         ...
@@ -42,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._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,
@@ -194,6 +195,7 @@ from docx.errors import (
     NotFoundError,
     NotNumberedListItemError,
     SessionError,
+    StaleTableError,
     _missing_block_id,
 )
 from docx.exceptions import InvalidSpanError
@@ -284,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)
@@ -333,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
 
@@ -838,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(
@@ -1198,10 +1209,11 @@ class HttpClient:
                 "version": _sdk_version(),
                 # Keeps its offsets as a tracked edit moves them, and reads a
                 # paragraph's length back after a tracked ``paragraph.text``
-                # (``docx._tracked``).
+                # (``docx._tracked``); holds anchored table ids (``docx.table``).
                 "capabilities": [
                     TRACKED_AUTHORING_CAPABILITY,
                     TRACKED_MINIMAL_PARAGRAPH_TEXT_CAPABILITY,
+                    TABLE_ANCHORS_CLIENT_CAPABILITY,
                 ],
             },
             "commands": [

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

@@ -24,6 +24,7 @@ from __future__ import annotations
 
 import io
 import re as _re
+import warnings
 import zipfile
 from dataclasses import dataclass, field, replace
 from typing import Any, Iterable
@@ -32,6 +33,41 @@ from xml.etree import ElementTree as ET
 
 WORD_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
 W_NS = f"{{{WORD_NS}}}"
+W14_NS = "{http://schemas.microsoft.com/office/word/2010/wordml}"
+
+
+class UnidentifiedTableRewriteWarning(UserWarning):
+    """Emitted when the export rescue skips its rewrites of a table the
+    script created because it cannot find that table in the exported
+    ``word/document.xml``: no one table holds the paragraphs its anchors
+    name (a table was added before it, or it is gone), or, its id carrying
+    no anchors (a docx-studio from before anchored table ids), the table at
+    its place is not provably it, or more than one table looks like it. The
+    table keeps the formatting docx-studio wrote for it; no other table is
+    patched in its place."""
+
+
+@dataclass(frozen=True)
+class CreatedTableIdentity:
+    """How the export rescue tells, in the exported body, a table the script
+    created (``Document.add_table``).
+
+    ``anchors``: the ``w14:paraId``s of its first and last own paragraphs,
+    from the id docx-studio gives it now; the table is the one holding them.
+    From a docx-studio without anchored ids, ``position`` (its ``t:N``) names
+    a candidate, which is taken only when it holds what the script knows of
+    its table and no other table of the body does, nested ones included:
+    ``rows`` × ``columns`` cells, and the ``texts`` the script wrote to them;
+    with none written, the size it was ``created`` with and an empty first
+    cell. Neither (``CreatedTableIdentity()``): not to be found.
+    """
+
+    anchors: tuple[str, ...] = ()
+    position: int | None = None
+    rows: int | None = None
+    columns: int | None = None
+    texts: tuple[tuple[int, int, str], ...] = ()
+    created: tuple[int, int] | None = None
 
 
 # Every well-known OOXML namespace that may appear in a DOCX Studio-exported
@@ -249,6 +285,134 @@ class CellAddress:
     part_key: str | None = None
 
 
+def _own_paragraph_ids(tbl: ET.Element) -> set[str]:
+    """The ``w14:paraId`` of each paragraph ``tbl`` holds as its own: not
+    one of a table nested in it."""
+    ids: set[str] = set()
+    pending = list(tbl)
+    while pending:
+        element = pending.pop()
+        if element.tag == f"{W_NS}tbl":
+            continue
+        if element.tag == f"{W_NS}p":
+            para_id = element.get(f"{W14_NS}paraId")
+            if para_id:
+                ids.add(para_id)
+            continue
+        pending.extend(list(element))
+    return ids
+
+
+def _cell_text(tbl: ET.Element, row: int, col: int) -> str | None:
+    """The text of the cell of ``tbl`` starting at grid (``row``, ``col``), its
+    own paragraphs' joined with ``"\\n"`` (a tab ``"\\t"``, a line break
+    ``"\\n"``); ``None`` when no cell starts there."""
+    rows = tbl.findall(f"{W_NS}tr")
+    if not 0 <= row < len(rows):
+        return None
+    cell = next((tc for start, tc in _cells_by_grid_column(rows[row]) if start == col), None)
+    if cell is None:
+        return None
+    paragraphs: list[str] = []
+    for paragraph in cell.findall(f"{W_NS}p"):
+        parts: list[str] = []
+        for run in paragraph.iter(f"{W_NS}r"):
+            for element in run:
+                if element.tag == f"{W_NS}t":
+                    parts.append(element.text or "")
+                elif element.tag == f"{W_NS}tab":
+                    parts.append("\t")
+                elif element.tag == f"{W_NS}br":
+                    parts.append("\n")
+        paragraphs.append("".join(parts))
+    return "\n".join(paragraphs)
+
+
+def _mismatch(tbl: ET.Element, identity: CreatedTableIdentity) -> str | None:
+    """Why the table ``tbl`` is not provably the created table ``identity``
+    tells (:class:`CreatedTableIdentity`); ``None`` when it is."""
+    if identity.rows is None or identity.columns is None:
+        return "the script does not know its table's size"
+    size = (len(tbl.findall(f"{W_NS}tr")), len(tbl.findall(f"{W_NS}tblGrid/{W_NS}gridCol")))
+    if size != (identity.rows, identity.columns):
+        return f"it holds {size[0]} × {size[1]} cells, the script's table {identity.rows} × {identity.columns}"
+    for row, col, text in identity.texts:
+        if _cell_text(tbl, row, col) != text:
+            return f"its cell ({row}, {col}) does not hold the text the script wrote there"
+    if not identity.texts and (identity.created != size or _cell_text(tbl, 0, 0) != ""):
+        return "the script wrote no text to tell it by, and it is not as the script created it"
+    return None
+
+
+def _locate_body_tables(
+    body: ET.Element, created_tables: "dict[int, CreatedTableIdentity | None]"
+) -> dict[int, int | None]:
+    """Where each created table is among the body's tables now
+    (``created_tables``, by ``Table._doc_index``): the one table holding a
+    paragraph its anchors name, or, without anchors, the table at its
+    position when it is what the script knows of its table
+    (:func:`_mismatch`) and no other table of the body is, nested ones
+    included (with a look-alike, a position that may have shifted proves
+    nothing); ``None``, with an
+    :class:`UnidentifiedTableRewriteWarning`, for a table that is gone
+    (``None``), or that cannot be told."""
+    tables = body.findall(f"{W_NS}tbl")
+    every_table = list(body.iter(f"{W_NS}tbl"))
+    owned = [_own_paragraph_ids(tbl) for tbl in tables]
+    located: dict[int, int | None] = {}
+    for doc_index, identity in created_tables.items():
+        wanted = set(identity.anchors) if identity is not None else set()
+        holders = [index for index, ids in enumerate(owned) if wanted & ids]
+        located[doc_index] = holders[0] if len(holders) == 1 else None
+        reason = ""
+        if identity is None:
+            reason = "docx-studio refused its id, so the table is gone"
+        elif wanted:
+            if located[doc_index] is None:
+                held = "no" if not holders else str(len(holders))
+                reason = f"{held} tables of the export hold the paragraphs its anchors name"
+        elif identity.position is None or not 0 <= identity.position < len(tables):
+            reason = "its id carries no anchors (a docx-studio from before anchored table ids) and names no table of the export"
+        else:
+            alike = sum(1 for tbl in every_table if _mismatch(tbl, identity) is None)
+            mismatch = _mismatch(tables[identity.position], identity)
+            if alike > 1:
+                reason = (
+                    f"ambiguous: {alike} tables of the export match what the script knows of it"
+                )
+            elif mismatch is None:
+                located[doc_index] = identity.position
+            else:
+                reason = (
+                    f"the table at its place (t:{identity.position}) is not provably it: {mismatch}"
+                )
+        if located[doc_index] is None:
+            warnings.warn(
+                UnidentifiedTableRewriteWarning(
+                    f"The export rescue skipped its rewrites of table {doc_index} this script created: "
+                    f"{reason}. The table keeps the formatting docx-studio wrote for it, and no other "
+                    "table was patched in its place."
+                ),
+                stacklevel=4,
+            )
+    return located
+
+
+def _relocated_ops(ops: dict, located: dict[int, int | None]) -> dict:
+    """``ops`` with each body address's ``table_doc_index`` re-addressed to
+    where its table is now (``located``), dropping those of a table that
+    cannot be found; a header or footer address (``part_key``) as it is."""
+    out: dict = {}
+    for address, value in ops.items():
+        if getattr(address, "part_key", None) is not None:
+            out[address] = value
+            continue
+        index = located.get(address.table_doc_index)
+        if index is not None:
+            out[replace(address, table_doc_index=index)] = value
+    return out
+
+
 def _cells_by_grid_column(tr: ET.Element) -> list[tuple[int, ET.Element]]:
     """Each ``<w:tc>`` of a row with the grid column it starts at.
 
@@ -505,6 +669,26 @@ class PostExportOps:
     _header_footer_relocations: list["HeaderFooterRelocation"] = field(
         default_factory=list,
     )
+    # The tables ``Document.add_table`` created, by ``Table._doc_index``:
+    # the export reads each one's id, whose anchors find it in the exported
+    # body (:func:`_locate_body_tables`).
+    _body_tables: dict[int, Any] = field(default_factory=dict)
+
+    def register_body_table(self, doc_index: int, table: Any) -> None:
+        """Remember the table ``Document.add_table`` created at ``doc_index``."""
+        self._body_tables[doc_index] = table
+
+    def body_tables_rewritten(self) -> dict[int, Any]:
+        """The created tables a pending body rewrite addresses, by ``doc_index``
+        (``None`` for an index no created table holds)."""
+        indexes: set[int] = set()
+        for ops in (self._cell_format_ops, self._cell_run_format_ops, self._cell_hyperlink_ops):
+            indexes.update(address.table_doc_index for address in ops if address.part_key is None)
+        indexes.update(address.table_doc_index for address in self._cell_shading_ops)
+        indexes.update(self._table_borders_ops)
+        indexes.update(address.table_doc_index for address in self._row_height_ops)
+        indexes.update(address.table_doc_index for address in self._row_cant_split_ops)
+        return {index: self._body_tables.get(index) for index in sorted(indexes)}
 
     def has_pending(self) -> bool:
         return (
@@ -549,6 +733,7 @@ class PostExportOps:
         self._row_height_ops.clear()
         self._row_cant_split_ops.clear()
         self._header_footer_relocations.clear()
+        self._body_tables.clear()
 
     def add_row_cant_split(
         self,
@@ -1045,7 +1230,12 @@ class PostExportOps:
             ),
         )
 
-    def apply_to_docx(self, docx_bytes: bytes) -> bytes:
+    def apply_to_docx(
+        self,
+        docx_bytes: bytes,
+        *,
+        created_tables: "dict[int, CreatedTableIdentity | None] | None" = None,
+    ) -> bytes:
         """Return ``docx_bytes`` with every recorded rewrite applied.
 
         ``Document.export_docx`` calls it only while a rewrite is pending
@@ -1053,9 +1243,17 @@ class PostExportOps:
         it is: every ``w:sectPr`` in a paragraph ends a real section of the
         room (``Document.add_section`` writes them; the page-break markers
         DOCX Studio 1.8.1 exported in their place are gone with that engine).
+
+        ``created_tables`` tells, for each created table a body rewrite
+        addresses (:meth:`body_tables_rewritten`), how to find it
+        (:class:`CreatedTableIdentity`): the rewrite finds the table wherever
+        it is in the exported body, and skips
+        (:class:`UnidentifiedTableRewriteWarning`) one it cannot. Without it,
+        a table is found by its index among the body's tables.
         """
         return _rewrite_word_document_xml(
             docx_bytes,
+            created_tables=created_tables,
             cell_format_ops=self._cell_format_ops,
             cell_run_format_ops=self._cell_run_format_ops,
             cell_hyperlink_ops=self._cell_hyperlink_ops,
@@ -1089,6 +1287,7 @@ def _rewrite_word_document_xml(
     header_footer_relocations: "list[HeaderFooterRelocation] | None" = None,
     row_height_ops: "dict[RowHeightAddress, RowHeightProps] | None" = None,
     row_cant_split_ops: "dict[RowHeightAddress, bool] | None" = None,
+    created_tables: "dict[int, CreatedTableIdentity | None] | None" = None,
 ) -> bytes:
     """Unzip the ``.docx``, apply rewrites to ``word/document.xml``,
     re-zip and return the result.
@@ -1209,6 +1408,23 @@ def _rewrite_word_document_xml(
                 body, header_footer_relocations,
             )
 
+        # The body rewrites address a created table by ``Table._doc_index``;
+        # with anchors, each is re-addressed to where its paragraphs are in
+        # the body now, and those of a table that cannot be found are dropped.
+        if created_tables is not None:
+            located = _locate_body_tables(body, created_tables)
+            body_cell_format_ops = _relocated_ops(body_cell_format_ops, located)
+            cell_run_format_ops = _relocated_ops(cell_run_format_ops, located)
+            cell_hyperlink_ops = _relocated_ops(cell_hyperlink_ops, located)
+            cell_shading_ops = _relocated_ops(cell_shading_ops, located)
+            table_borders_ops = {
+                index: edges
+                for doc_index, edges in table_borders_ops.items()
+                if (index := located.get(doc_index)) is not None
+            }
+            row_height_ops = _relocated_ops(row_height_ops or {}, located)
+            row_cant_split_ops = _relocated_ops(row_cant_split_ops or {}, located)
+
         # Body cell-format ops apply AFTER relocation so the body
         # table indices align with ``Table._doc_index``. Pre-relocation,
         # body table 0 was the misplaced header/footer table (which

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

@@ -37,6 +37,7 @@ from datetime import datetime, timezone
 from typing import TYPE_CHECKING
 
 from docx._batching import run_sync
+from docx._buffer import writes_unapplied
 from docx.blkcntnr import BlockItemContainer
 from docx.errors import DocxError, NotFoundError
 
@@ -330,7 +331,9 @@ class Comment(BlockItemContainer):
         comment range listed without one, with empty text)."""
         try:
             result: object = run_sync(self._session.doc.comments.get({"id": self.comment_id}))
-        except NotFoundError:
+        except NotFoundError as exc:
+            if writes_unapplied(exc):
+                raise
             result = None
         read = result.get("text") if isinstance(result, dict) else None
         if isinstance(read, str):
@@ -540,7 +543,9 @@ class Comments:
             result: object = run_sync(
                 self._session.doc.comments.get({"id": str(comment_id)}),
             )
-        except NotFoundError:
+        except NotFoundError as exc:
+            if writes_unapplied(exc):
+                raise
             return None
         if isinstance(result, dict):
             # DOCX Studio may surface the id under ``id`` or ``commentId`` —