athena-python-docx 0.26.0__tar.gz → 0.27.0__tar.gz

{athena_python_docx-0.26.0 → athena_python_docx-0.27.0}/AGENTS.md

@@ -224,6 +224,11 @@ not file-backed. Each is documented in the relevant docstring.
   `Revision.reject()` resolve a single change. python-docx upstream
   has zero track-changes API, so this entire surface is an Athena
   extension wired to DOCX Studio's `doc.trackChanges.{list,get,decide}`.
+  A run's tracked formatting change (`w:rPrChange`) and a paragraph's
+  (`w:pPrChange`) are `"format"` revisions; `reject()` gives the run or
+  paragraph exactly the earlier properties the change recorded
+  (`tests/test_revisions.py`, docx-studio's
+  `tracked-run-property-changes.test.ts`).
 
 - **Style writes refuse what would write a broken document.** python-docx
   writes these into `styles.xml`; the SDK raises before anything is sent,
@@ -968,6 +973,44 @@ architecture or a DOCX Studio constraint:
   Markup) show insertions and hide deletions, as these reads do.
   `doc.revisions` lists every change (`tests/test_run_text_python_docx.py`).
 
+- **A field's runs read as python-docx reads them; some writes to them
+  differ.** `Paragraph.text` includes a complex field's displayed result and
+  `Paragraph.runs` holds its begin, field code, separate, result and end runs
+  (each with its own formatting), as python-docx reads the `w:r` children of
+  a `w:p`; a simple field (`w:fldSimple`) reads as nothing, and a field in a
+  link is the link's, as in python-docx. Each paragraph of a field that spans
+  paragraphs (a table of contents) holds the field character runs it has
+  (`tests/test_field_reads_python_docx_parity.py`, against stock python-docx
+  on the same `.docx`; `DOCX_STUDIO_LIMITATIONS.md` § 27). A field takes no
+  room in the text-address space, so its runs stand at one offset. Writes:
+  - setting a result run's `.text` changes the field's displayed result,
+    as in python-docx (`Replace` with a `field` target), but the export
+    writes a changed result of several runs as one run, in the first run's
+    formatting, and a result run read before the field's result changed
+    (through another read's run, or by a collaborator) raises
+    `FieldRunWriteError` rather than write over that change, where
+    python-docx's run is live;
+  - formatting a result run formats the field's whole result (`FormatApply`
+    with a `field` target), from its source formatting, where python-docx
+    formats that run alone;
+  - `.text` (and `clear()`) on a field character or field code run raises
+    `docx.errors.FieldRunWriteError` naming the field: python-docx replaces
+    the run's `w:fldChar` or `w:instrText` with the text, which breaks the
+    field;
+  - formatting set on a field character or field code run is not applied and
+    emits `PendingFieldRunFormatWarning` (those runs show nothing; docx-studio
+    has no command that writes their own `w:rPr`), where python-docx writes
+    it, so `for run in p.runs: run.bold = True` formats the text and the
+    field's result and warns for the rest;
+  - `add_text`, `add_tab`, `add_break`, `add_picture`, `add_field`,
+    `add_footnote`, `add_endnote`, `add_math` and `add_cross_reference` on
+    any of a field's runs raise `FieldRunWriteError`; python-docx appends to
+    that `w:r`.
+  A field that `Run.add_field` adds is a simple field, so it reads as no
+  runs and no text, though docx-studio's export writes it as a complex field.
+  Against a docx-studio that predates `fieldRun` reads, a field reads as no
+  runs and no text, as before (`tests/test_field_runs.py`).
+
 ### If you need a deviation
 
 If there is a genuine technical reason why a deviation from python-docx is necessary:

{athena_python_docx-0.26.0 → athena_python_docx-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.26.0
+Version: 0.27.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.26.0 → athena_python_docx-0.27.0}/docx/__init__.py

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

{athena_python_docx-0.26.0 → athena_python_docx-0.27.0}/docx/errors.py

@@ -129,6 +129,16 @@ class NotNumberedListItemError(DocxError, ValueError):
     """
 
 
+class FieldRunWriteError(DocxError, ValueError):
+    """Raised for a write to a run of a Word field that the SDK refuses:
+    text written to a field character or field code run (python-docx's write
+    replaces the run's ``w:fldChar`` or ``w:instrText`` and breaks the field),
+    and content appended to any of a field's runs. The message names the
+    field. Subclasses :class:`ValueError` so ``except ValueError`` also
+    catches it.
+    """
+
+
 class SessionError(DocxError):
     """Raised when the DOCX Studio SDK session cannot be established or used."""
 

{athena_python_docx-0.26.0 → athena_python_docx-0.27.0}/docx/text/paragraph.py

@@ -199,8 +199,10 @@ def _extract_text(info: object, *, final: bool = False) -> str:
     returns: tracked changes as Word's final view shows them, a deletion's
     runs left out and an insertion's read (python-docx leaves out both, as
     it reads only a ``w:p``'s direct ``w:r`` and ``w:hyperlink`` children),
-    and each run's text read as python-docx's ``Run.text`` reads it
-    (:func:`_word_text`).
+    each run's text read as python-docx's ``Run.text`` reads it
+    (:func:`_word_text`), and a complex field's displayed result (the text of
+    its result runs, never its field code), which takes no room in the
+    text-address space.
     """
     if not isinstance(info, dict):
         return ""
@@ -217,6 +219,12 @@ def _extract_text(info: object, *, final: bool = False) -> str:
     for inline in inlines:
         if not isinstance(inline, dict):
             continue
+        field_run: object = inline.get("fieldRun")
+        if isinstance(field_run, dict):
+            shown: object = field_run.get("text")
+            if final and isinstance(shown, str) and not _deleted(field_run):
+                parts.append(_word_text(shown, _symbol_font(field_run)))
+            continue
         run: object = inline.get("run")
         if isinstance(run, dict):
             text: object = run.get("text")
@@ -273,6 +281,61 @@ def _walk_inlines(info: object) -> list[dict]:
     return []
 
 
+def _inline_width(inline: dict) -> int:
+    """The room an inline takes in the text-address space (see ``runs``)."""
+    run: object = inline.get("run")
+    if isinstance(run, dict):
+        text: object = run.get("text")
+        return len(text) if isinstance(text, str) else 0
+    kind: object = inline.get("type")
+    if kind == "text":
+        flat: object = inline.get("text")
+        return len(flat) if isinstance(flat, str) else 0
+    return 1 if kind in ("tab", "lineBreak") else 0
+
+
+def _field_run_proxies(
+    paragraph: "Paragraph", inlines: list[dict], *, marks_known: bool
+) -> dict[int, "Run"]:
+    """The :class:`Run` of each field run of ``inlines`` (a ``fieldRun``
+    read), by its index there: a field's begin, code, separate, result or end
+    run, which python-docx reads as a run of the paragraph. A field takes no
+    room in the text-address space, so each stands at one offset. All are built
+    before any is handed out, so each result run of a field holds all of them
+    (``_field_results``) and setting one's text keeps the others'. A run of a
+    tracked deletion has none, as Word's final view shows it.
+    """
+    from docx.text.run import Run
+
+    proxies: dict[int, Run] = {}
+    results: dict[int, list[Run]] = {}
+    offset = 0
+    for position, inline in enumerate(inlines):
+        field_run: object = inline.get("fieldRun")
+        if not isinstance(field_run, dict):
+            offset += _inline_width(inline)
+            continue
+        if _deleted(field_run):
+            continue
+        run = Run(
+            session=paragraph._session,
+            block_id=paragraph._node_id,
+            range_=(offset, offset),
+            inline=field_run,
+            paragraph=paragraph,
+            in_cell=paragraph._in_cell,
+            cell_ooxml_address=paragraph._cell_ooxml_address,
+        )
+        run._marks_known = marks_known
+        index: object = field_run.get("fieldIndex")
+        if field_run.get("part") == "result" and isinstance(index, int):
+            siblings = results.setdefault(index, [])
+            siblings.append(run)
+            run._field_results = siblings  # type: ignore[attr-defined]
+        proxies[position] = run
+    return proxies
+
+
 def _create_page_break_paragraph(session: Any, client_node_id: str, *, at: dict) -> None:
     """Create, at ``at``, the paragraph python-docx writes for a page break:
     ``<w:p><w:r><w:br w:type="page"/></w:r></w:p>``.
@@ -505,9 +568,10 @@ class Paragraph:
     def text(self) -> str:
         """The paragraph's text: its runs' and hyperlinks' text as
         python-docx's ``Paragraph.text`` reads it (a non-breaking hyphen as
-        ``-``, a soft hyphen and a symbol left out), with tracked changes as
-        Word's final view shows them: an insertion's text in, a deletion's
-        out."""
+        ``-``, a soft hyphen and a symbol left out, a complex field's displayed
+        result in and its field code out, a simple field's result out), with
+        tracked changes as Word's final view shows them: an insertion's text
+        in, a deletion's out."""
         return _extract_text(self._node_info(), final=True)
 
     @text.setter
@@ -565,13 +629,19 @@ class Paragraph:
         As in python-docx, these are the paragraph's own runs: the runs of a
         hyperlink are the hyperlink's (:attr:`hyperlinks`,
         :meth:`iter_inner_content`), while :attr:`text` includes its text.
+        A complex field's runs are the paragraph's runs, in order: its begin,
+        field code and separate runs (``""``), its result runs with their
+        text, and its end run (``""``), each with its own formatting; so are
+        the field character runs of a field that begins or ends in another
+        paragraph (a table of contents). A simple field (``w:fldSimple``) has
+        no runs here, as in python-docx.
 
         Run offsets are computed against DOCX Studio's text-address space,
         which counts tab and lineBreak inlines as 1 character each
         (so ``insert_tab({offset})`` and the run-range arithmetic stay
-        consistent). A run of a tracked deletion is no run of the
-        paragraph's, as Word's final view shows it, but keeps its offsets;
-        a tracked insertion's runs are runs.
+        consistent). A field's runs take no room in it. A run of a tracked
+        deletion is no run of the paragraph's, as Word's final view shows it,
+        but keeps its offsets; a tracked insertion's runs are runs.
         """
         from docx.text.run import Run
 
@@ -602,8 +672,13 @@ class Paragraph:
         inlines: list[dict] = _walk_inlines(info)
         marks_known: bool = _reports_run_marks(info)
         runs: list["Run"] = []
+        field_runs = _field_run_proxies(self, inlines, marks_known=marks_known)
         offset: int = 0
-        for inline in inlines:
+        for position, inline in enumerate(inlines):
+            if isinstance(inline.get("fieldRun"), dict):
+                if position in field_runs:
+                    runs.append(field_runs[position])
+                continue
             drawing: object = inline.get("drawing")
             if isinstance(drawing, dict):
                 # A picture: python-docx's run holding a ``w:drawing``. It
@@ -1012,6 +1087,7 @@ class Paragraph:
             self._session.doc.get_node_by_id({"id": self._node_id}),
         )
         inlines = _walk_inlines(info)
+        field_runs = _field_run_proxies(self, inlines, marks_known=_reports_run_marks(info))
         offset: int = 0
         # Accumulator for the in-flight hyperlink span. Mirrors the
         # coalesce logic in ``Paragraph.hyperlinks`` — yields a single
@@ -1032,9 +1108,17 @@ class Paragraph:
                 segments=segments,
             )
 
-        for inline in inlines:
+        for position, inline in enumerate(inlines):
             if not isinstance(inline, dict):
                 continue
+            if isinstance(inline.get("fieldRun"), dict):
+                # A field's ``w:r`` is a run of the paragraph, never of a link.
+                flushed = _flush_current()
+                if flushed is not None:
+                    yield flushed
+                if position in field_runs:
+                    yield field_runs[position]
+                continue
             # Two DOCX Studio inline shapes are accepted by the rest of the
             # paragraph code (``_extract_text``, ``runs``):
             #   1. typed-wrapper:    {"run": {"text": "...", ...}}

{athena_python_docx-0.26.0 → athena_python_docx-0.27.0}/docx/text/run.py

@@ -70,6 +70,20 @@ class PendingColorTypeWarning(UserWarning):
     ``theme_color`` without a warning."""
 
 
+class PendingFieldRunFormatWarning(UserWarning):
+    """Emitted when formatting is set on a field character or field code run
+    (a field's begin, code, separate or end run). python-docx writes it into
+    that run's ``w:rPr``, which shows nothing; docx-studio keeps those runs'
+    own properties from the source and has no command that writes them, so
+    the setter changes nothing. Formatting a result run formats the field's
+    result.
+    """
+
+
+#: The parts of a field whose runs ``Paragraph.runs`` reads (``fieldRun`` reads).
+_FIELD_RUN_PARTS: frozenset[str] = frozenset({"begin", "code", "separate", "result", "end"})
+
+
 if TYPE_CHECKING:
     from docx.client import Session
     from docx.enum.dml import MSO_COLOR_TYPE, MSO_THEME_COLOR
@@ -399,6 +413,114 @@ class Run:
         self._note_paragraph_len_delta(delta)
         note_length_change(self, at, delta, replaced=replaced, before=_before_image(sent))
 
+    def _field_part(self) -> str | None:
+        """The part of a field this run is (``begin``, ``code``, ``separate``,
+        ``result`` or ``end``), for a run ``Paragraph.runs`` read from a field;
+        else None."""
+        part: object = getattr(self, "_inline_snapshot", {}).get("part")
+        return part if isinstance(part, str) and part in _FIELD_RUN_PARTS else None
+
+    def _field_name(self) -> str:
+        instruction: object = self._inline_snapshot.get("instruction")
+        if isinstance(instruction, str) and instruction:
+            return f"the field {{{instruction}}}"
+        return "a field that begins or ends in another paragraph"
+
+    def _refuse_field_write(self, op: str) -> None:
+        """Raise :class:`docx.errors.FieldRunWriteError` for ``op`` on a run of a field."""
+        part = self._field_part()
+        if part is None:
+            return
+        from docx.errors import FieldRunWriteError
+
+        if op == "text":
+            raise FieldRunWriteError(
+                f"Run.text = ... on the {part} run of {self._field_name()}: python-docx "
+                "replaces the run's field character or field code with the text, which "
+                "breaks the field. Set the text of the field's result run to change "
+                "what it shows.",
+            )
+        raise FieldRunWriteError(
+            f"Run.{op} on the {part} run of {self._field_name()}: content cannot be "
+            "added to a field's run here. Add a run after the field "
+            "(Paragraph.add_run), or set a result run's text.",
+        )
+
+    def _field_target(self) -> dict | None:
+        """The ``field`` target of this run's field node, for a result run."""
+        index: object = self._inline_snapshot.get("fieldIndex")
+        if self._field_part() != "result" or not isinstance(index, int):
+            return None
+        return {"kind": "field", "blockId": self._block_id, "field": index}
+
+    def _set_field_text(self, value: str) -> None:
+        """``Run.text = value`` on a result run: the field shows ``value`` in
+        this run's place, its other result runs' text kept, and its field code
+        stays, as python-docx writes it.
+
+        The field's result is written whole, so it is composed from the result
+        runs of this run's read only while the field still shows what they
+        hold: a field another read's run (or a collaborator) changed since
+        raises :class:`docx.errors.FieldRunWriteError` instead of losing that
+        change.
+        """
+        target = self._field_target()
+        if target is None:
+            self._refuse_field_write("text")
+            return
+        siblings: list[Run] = getattr(self, "_field_results", None) or [self]
+        live: object = run_sync(self._session.doc.get_node_by_id({"id": self._block_id}))
+        if self._shown_result(live) != "".join(run._raw_text() for run in siblings):
+            from docx.errors import FieldRunWriteError
+
+            raise FieldRunWriteError(
+                f"Run.text = ... on a result run of {self._field_name()}: the field's "
+                "result changed since this run was read. Read the paragraph's runs "
+                "again and set the text of a run from that read.",
+            )
+        shown = "".join(value if run is self else run._raw_text() for run in siblings)
+        run_sync(self._session.doc.replace({"target": target, "text": shown}))
+        self._inline_snapshot["text"] = value
+        self._note_paragraph_len_delta(0)
+
+    def _shown_result(self, info: object) -> str:
+        """The displayed result a paragraph read gives this run's field."""
+        from docx.text.paragraph import _walk_inlines
+
+        index: object = self._inline_snapshot.get("fieldIndex")
+        parts: list[str] = []
+        for inline in _walk_inlines(info):
+            field_run: object = inline.get("fieldRun")
+            if (
+                isinstance(field_run, dict)
+                and field_run.get("part") == "result"
+                and field_run.get("fieldIndex") == index
+            ):
+                text: object = field_run.get("text")
+                parts.append(text if isinstance(text, str) else "")
+        return "".join(parts)
+
+    def _format_field(self, kwargs: dict) -> None:
+        """Formatting set on a run of a field: a result run's formats the
+        field node, so every result run of the field takes it."""
+        target = self._field_target()
+        if target is None:
+            import warnings
+
+            warnings.warn(
+                f"Run formatting on the {self._field_part()} run of {self._field_name()} "
+                "was not applied: docx-studio keeps the field character and field code "
+                "runs' own properties from the source and cannot write them (they show "
+                "nothing). Format a result run to format the field's result.",
+                PendingFieldRunFormatWarning,
+                stacklevel=4,
+            )
+            return
+        run_sync(self._session.doc.format.apply({"target": target, "inline": kwargs}))
+        for run in getattr(self, "_field_results", None) or [self]:
+            run._note_inline_applied(kwargs)
+        self._note_paragraph_len_delta(0)
+
     @property
     def _text_range(self) -> dict:
         return {
@@ -449,7 +571,11 @@ class Run:
         return self._inline_snapshot.get("symbolFont") or self._read_inline_attr("fontFamily")
 
     def _raw_text(self) -> str:
-        """The run's slice of its paragraph's text-address space."""
+        """The run's slice of its paragraph's text-address space; for a run of
+        a field, which takes none, the text its read holds (a result run's)."""
+        if self._field_part() is not None:
+            shown: object = self._inline_snapshot.get("text")
+            return shown if isinstance(shown, str) else ""
         # Fast-path runs (see ``Table._fastpath_cell_text``) carry their
         # known text — the whole point is zero read round-trips. Mutations
         # through this proxy keep the attr in sync or clear it.
@@ -525,6 +651,9 @@ class Run:
                 f"Run.text requires str; got {type(value).__name__} "
                 f"{value!r}",
             )
+        if self._field_part() is not None:
+            self._set_field_text(value)
+            return
         if self._check_cell_inner("text"):
             # Warn-and-skip: nothing mutated, so the fast-path text cache
             # (when present) still reflects reality — keep it.
@@ -594,6 +723,7 @@ class Run:
                 f"Run.add_text requires str; got {type(text).__name__} "
                 f"{text!r}",
             )
+        self._refuse_field_write("add_text")
         if self._check_cell_inner("add_text"):
             # Return a stub Run with the same in_cell flag so chained
             # ops on the result also short-circuit cleanly. Propagate
@@ -678,6 +808,7 @@ class Run:
 
     def add_tab(self) -> None:
         """Insert a tab character at the end of the run, in its formatting."""
+        self._refuse_field_write("add_tab")
         if self._check_cell_inner("add_tab"):
             return
         end: int = self._range[1]
@@ -721,6 +852,7 @@ class Run:
         """
         import warnings
 
+        self._refuse_field_write("add_break")
         if self._check_cell_inner("add_break"):
             return
         end: int = self._range[1]
@@ -843,6 +975,7 @@ class Run:
         from docx.shape import InlineShape
         import base64
 
+        self._refuse_field_write("add_picture")
         image_bytes, _fallback_path = load_image_bytes(image_path_or_stream)
         # The image's signature, as python-docx reads it: a stream with none
         # (an empty one, or one read to its end already) raises
@@ -918,6 +1051,7 @@ class Run:
         from docx.commands import CreateField
         from docx.fields import Field
 
+        self._refuse_field_write("add_field")
         if self._check_cell_inner("add_field"):
             return Field(
                 session=self._session,
@@ -1000,6 +1134,7 @@ class Run:
         from docx.commands import CreateFootnote
         from docx.footnotes import Footnote
 
+        self._refuse_field_write("add_footnote")
         end: int = self._range[1]
         cursor: dict = {
             "kind": "text",
@@ -1036,6 +1171,7 @@ class Run:
         from docx.commands import CreateEndnote
         from docx.footnotes import Endnote
 
+        self._refuse_field_write("add_endnote")
         end: int = self._range[1]
         cursor: dict = {
             "kind": "text",
@@ -1086,6 +1222,7 @@ class Run:
         from docx.commands import CreateCrossReference
         from docx.fields import Field
 
+        self._refuse_field_write("add_cross_reference")
         end: int = self._range[1]
         cursor: dict = {
             "kind": "text",
@@ -1132,6 +1269,7 @@ class Run:
         from docx.commands import CreateMath
         from docx.math import MathEquation
 
+        self._refuse_field_write("add_math")
         end: int = self._range[1]
         cursor: dict = {
             "kind": "text",
@@ -1298,6 +1436,9 @@ class Run:
         # target range.`` Stash the attrs and apply them once the run
         # has text — see ``_pending_inline`` in ``__init__`` for the
         # python-docx parity rationale.
+        if self._field_part() is not None:
+            self._format_field(kwargs)
+            return
         if getattr(self, "_in_cell", False):
             # Stash for the post-export OOXML rewrite FIRST so the formatting
             # lands in the exported ``.docx`` regardless of engine (and is the

{athena_python_docx-0.26.0 → athena_python_docx-0.27.0}/pyproject.toml

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