athena-python-docx 0.33.0__tar.gz → 0.35.0__tar.gz

{athena_python_docx-0.33.0 → athena_python_docx-0.35.0}/AGENTS.md

@@ -85,16 +85,30 @@ pinned by focused tests and documented in
   `quick_style`, `unhide_when_used`, `base_style`,
   `next_paragraph_style`) write the style's definition
   (`SetStyleMetadata`), `Styles.add_style` adds one (`CreateStyle`), and
-  a paragraph or character style's formatting (`style.font.*`,
-  `style.paragraph_format.*`) is written too (`SetStyleFormatting`); each
+  a paragraph, character or table style's formatting (`style.font.*`,
+  `style.paragraph_format.*`; a table style's on a docx-studio that reports
+  `tableStyleFormatting`, which a room imported before its cells resolved
+  table styles does not) is written too (`SetStyleFormatting`); each
   reads back from the style table, whose `metadata` / `font` /
   `paragraphFormat` entries are the capability signal
   (`tests/test_style_metadata_writes.py`,
-  `tests/test_style_formatting_writes.py`). `style_id`, `delete()`, a
-  table style's formatting and base, a style's tab stops, and every style write on
-  a docx-studio without that signal emit `PendingStyleMutationWarning`
-  (or its paragraph-format / registry variant) and stash on
-  `_overrides` (`tests/test_style_setters_contract.py`).
+  `tests/test_style_formatting_writes.py`), a paragraph style's
+  `tab_stops` (each mutation sends the style's whole `w:tabs` as python-docx's
+  `TabStops` leaves it, on a docx-studio that reports `styleTabStops`; each
+  tab stop object is its place in that list, which a write to another moves,
+  so of two equal stops each writes itself, and one removed writes nothing;
+  `tests/test_style_tab_stops.py`). `delete()` removes a paragraph
+  or character style's definition (`DeleteStyle`, on a docx-studio that
+  reports `deleteStyle`; `tests/test_style_delete.py`): its content keeps the
+  style's name and shows the default style, as in Word. A table style's
+  `delete()`, `base_style` and `style_id` are sent where docx-studio also
+  reports `tableStyleRestyles` (it draws the style's tables again), and its
+  font and paragraph format where it reports `tableStyleFormatting`; a room
+  imported before its cells resolved table styles reports neither. A
+  numbering style's `style_id` and deletion, and every style write on a
+  docx-studio without that signal emit
+  `PendingStyleMutationWarning` (or its delete / paragraph-format / registry
+  variant) and stash on `_overrides` (`tests/test_style_setters_contract.py`).
 - **A picture is a run, and `Run.iter_inner_content()` yields its
   `docx.drawing.Drawing`.** As python-docx reads a `w:r` holding a
   `w:drawing`, `Paragraph.runs` and `iter_inner_content()` hold a run with
@@ -116,10 +130,15 @@ pinned by focused tests and documented in
 - **`Styles.latent_styles`** (`docx.styles.latent.LatentStyles`) reads
   the document's `<w:latentStyles>` (defaults and each `w:lsdException`)
   from docx-studio's `Info` (`includeStyles` → `latentStyles`), as python-docx
-  reads them. Writing them is not supported: a setter, `add_latent_style`
-  and `_LatentStyle.delete` emit `PendingLatentStylesWriteWarning` and
-  change nothing. A docx-studio that predates the read (or a document
-  without a source copy) reads as empty, with
+  reads them, and writes them as python-docx does: each setter,
+  `add_latent_style` and `_LatentStyle.delete` sends one `EditLatentStyles`
+  to a docx-studio that reports `latentStyleWrites`
+  (`tests/test_latent_style_writes.py`); an older one keeps the value, with
+  `PendingLatentStylesWriteWarning`. A `_LatentStyle` addresses its exception
+  by name and `occurrence` (which of that name's exceptions it is), moved
+  when an earlier one is deleted, so one `add_latent_style` returns beside an
+  exception of the same name writes to itself, as python-docx's element does. A docx-studio that predates the read (or
+  a document without a source copy) reads as empty, with
   `PendingLatentStylesReadWarning`.
 
 ### Intentional deviations (additions / different semantics)
@@ -169,6 +188,22 @@ not file-backed. Each is documented in the relevant docstring.
   cells stay. ``table.style = None`` removes an existing table's style as
   python-docx does (``DOCX_STUDIO_LIMITATIONS.md`` § 25).
 
+- **Table, row and cell properties set to None, and row height parts**, as
+  python-docx 1.2.0 writes them on a docx-studio that reports
+  ``tableClears`` (``tests/test_table_clears.py``): ``Table.alignment =
+  None`` removes ``w:jc`` (a header or footer table's too),
+  ``_Cell.vertical_alignment = None`` removes
+  ``w:vAlign``, and ``_Row.height`` / ``_Row.height_rule`` each write their
+  own part of ``w:trHeight``, None removing it (``<w:trHeight
+  w:hRule="exact"/>``); a height set without a rule is the value alone.
+  ``_Cell.width = None`` raises ``TypeError`` and ``Table.autofit = None``
+  changes nothing, as in python-docx. An older docx-studio keeps the
+  ``PendingTableClearWarning`` and sends a rule (at least) with each height.
+  ``_Column.width = None`` still warns: a ``w:gridCol`` without a width
+  needs the layout to size the column from its cells. An invalid height or
+  rule is refused before the capability read, whose ``Info`` would send the
+  edits still buffered.
+
 - **`Document.create(name=, base_url=, api_key=, parent_folder_id=, workspace_id=, docx=, agora_base_url=)`**
   classmethod. Stock python-docx returns a blank in-memory document
   for `Document(None)`; we can't fabricate a Word document asset
@@ -921,10 +956,26 @@ architecture or a DOCX Studio constraint:
   string DOCX Studio's commands carry for a member (`"center"`, `"wavy"`,
   the `w:` XML value, …) where upstream rejects strings. The SDK sends
   `member.to_docx_studio()` and reads with `from_docx_studio()`, never
-  `.value`. Members DOCX Studio can't apply are sent as their closest
-  value with `PendingEnumCoercionWarning` (distributed / kashida / Thai
-  justification → `"justify"`; `LIST`/`CLEAR`/`END`/`NUM`/`START` tabs →
-  `"left"`); `WD_ALIGN_VERTICAL.BOTH` goes as `"center"`. `INHERITED`
+  `.value`. A paragraph's alignment and tab stops go as python-docx writes
+  them (distributed / kashida / Thai justification, `LIST`/`CLEAR`/`END`/
+  `NUM`/`START` tabs) to a DOCX Studio that reports `alignmentValues`
+  (`tests/test_alignment_values.py`); to an older one, as their closest
+  value (`"justify"`, `"left"`) with `PendingEnumCoercionWarning`.
+  `TabStops.add_tab_stop` keeps a stop already at its position and goes in
+  after it, as python-docx's `insert_tab_in_order` puts it
+  (`SetParagraphTabStop` with `insert`, sent to a DOCX Studio that reports
+  `tabStopInserts`; an older one replaces that stop). A stop's `alignment`
+  and `leader` change it in place, and its `position` moves it where
+  python-docx moves its `w:tab` (`tests/test_tab_stop_writes.py`). A
+  `TabStop` is its place in the paragraph's list, which a write through any
+  other moves (the live stops of each paragraph are held weakly per
+  session), as python-docx's proxy holds its `w:tab`: two stops at one
+  position are each their own, and two objects of one stop both write it.
+  One the paragraph no longer holds takes a value and writes nothing; its
+  `position` raises `AttributeError`, except for one `clear_all` took out,
+  as python-docx's do. An add reads nothing unless a stop of the paragraph
+  holds a place: the next read finds where it went.
+  `WD_ALIGN_VERTICAL.BOTH` goes as `"center"`. `INHERITED`
   raises `ValueError` ("has no XML representation") as upstream's
   `to_xml` does, and a bool is its int value (`True` is the member valued
   1), as upstream reads it. `Table.alignment`
@@ -1009,7 +1060,10 @@ architecture or a DOCX Studio constraint:
   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
+  written, as python-docx's proxies follow the elements they hold. A write
+  that replaces one of those paragraphs (`cell.text = …` on the first or last
+  cell) leaves its paraId on the table as an alias (`anchorAliases`), so the
+  proxy reaches the table in later batches on any docx-studio replica. 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
@@ -1069,11 +1123,16 @@ architecture or a DOCX Studio constraint:
   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
-  `Pending…ClearWarning` and leaves the value intact instead of
-  destructively clearing the whole block. The `Section` dimension setters
+- **A `ParagraphFormat` setter given `None` clears that property alone**, as
+  upstream does, on a docx-studio that reports `paragraphFormatClears`:
+  `space_before`, `space_after`, `line_spacing` (the line with its rule) and
+  `line_spacing_rule` (the rule alone) send `ClearParagraphSpacing.only`;
+  `left_indent`, `right_indent` and `first_line_indent` send
+  `ClearParagraphIndentation.only`; `keep_with_next`, `keep_together` and
+  `widow_control` send `SetParagraphKeepOptions.clear…`. On an older one a
+  spacing or indent `None` clears all of the paragraph's spacing or indents,
+  as before, and the keep options and `line_spacing_rule` warn
+  (`PendingParfmtClearWarning`) and keep the value. The `Section` dimension setters
   remove the attribute for `None`, as upstream does (`null` on the wire),
   on a docx-studio whose section read reports `clearsDimensions`; on an
   older one they warn (`PendingSectionDimensionClearWarning`) and keep the
@@ -1156,18 +1215,37 @@ architecture or a DOCX Studio constraint:
     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;
+  - formatting a field's one result run formats the field's whole result
+    (`FormatApply` with a `field` target), from its source formatting, as
+    python-docx formats that run, and in a body paragraph docx-studio writes
+    the run's own `w:rPr` with it (a caption's number keeps its `w:noProof`
+    and takes nothing of the Caption style); of a result of several runs, it formats that
+    run alone, as python-docx does, against a docx-studio that reports
+    `capabilities.fieldRunFormats` (an older one formats the whole result).
+    The SDK names that run by its place among the result's runs and the text
+    it was read with, and renumbers the result runs a read holds when a write
+    through one of them empties it (docx-studio writes no emptied result
+    run): a run that no longer has a place, or holds other text, is not
+    formatted alone. The SDK warns (`PendingFieldRunFormatWarning`), or
+    docx-studio refuses the format, so it never lands on another run;
   - `.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;
+  - formatting set on a field character or field code run, a table of
+    contents' own runs among them, is written to that run's `w:rPr` as
+    python-docx writes it, so `for run in p.runs: run.bold = True` formats
+    every run, against a docx-studio that reports
+    `capabilities.fieldRunFormats` (the SDK names the run: its `part`, with its
+    field's index and which run of that part it is, or which of the
+    paragraph's field runs no field node stands for it is). It is refused and
+    warns (`DocxUnsupportedCommandWarning`) for a run of a field `add_field`
+    added since the import, whose runs docx-studio writes from its node, and
+    of a paragraph a field was added to or taken out of since; a tracked
+    format raises naming `TrackedChangesUnsupported`. An older docx-studio has
+    no command that writes those runs' `w:rPr`: there the setter changes
+    nothing and emits `PendingFieldRunFormatWarning`
+    (`tests/test_field_runs.py`, `DOCX_STUDIO_LIMITATIONS.md` § 27);
   - `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
@@ -1177,6 +1255,34 @@ architecture or a DOCX Studio constraint:
   exported file. Against a docx-studio that predates `fieldRun` reads, a
   field reads as no runs and no text, as before (`tests/test_field_runs.py`).
 
+- **A run that holds a page number block refuses a tracked whole-run format
+  and two text writes.** A page number block (`w:pgNum`) reads as a run with
+  no text, and a run that holds text and blocks (or two blocks) reads as
+  python-docx's one run. A whole-run format (`run.bold = True`, `run.font.*`,
+  a format of a block's run) formats every piece of it, as python-docx formats
+  its `w:rPr`, the on/off properties no editor mark holds included
+  (`font.no_proof`, `snap_to_grid`, `web_hidden`, `spec_vanish`, `math`,
+  `complex_script`, `cs_bold`, `cs_italic`). A tracked format
+  (`track_revisions`) is refused while a block of the run has a node, and
+  raises `DocxError` naming `TrackedChangesUnsupported`, because docx-studio
+  records no tracked change on a block. A link's block has none, and takes it
+  as the run's text does. In a document imported before docx-studio gave a
+  block's node its run's properties (in October 2026, between the release that
+  first read `w:pgNum` and the next), and in a comment, the on/off properties
+  are refused too, in any format that reaches a block, and warn
+  (`DocxUnsupportedCommandWarning`), because there a block keeps its source
+  run's. python-docx writes both into the run's `w:rPr`. Made on the run's
+  text alone, either would leave the run half formatted and split it in two
+  (`DOCX_STUDIO_LIMITATIONS.md` § 27). `run.text = …` and `clear()` replace
+  all of such a run, its blocks too, as upstream does: the SDK declares
+  `wholeRunPieces`, and renumbers the field runs it holds of the paragraph,
+  since each field after the blocks is numbered one lower for each
+  (`tests/test_run_page_number_blocks.py`). Two text writes are refused and
+  warn (`DocxUnsupportedCommandWarning`), where upstream replaces the blocks:
+  text written to a block's run (a run of blocks alone, or a lone block),
+  which would move the text offsets the SDK keeps, and the text of a link's
+  run that holds a block, which has no node to take out.
+
 - **`Font.name = "…"` also clears the theme fonts of the two slots it
   sets.** python-docx writes the name to `w:rFonts`' `w:ascii` and `w:hAnsi`
   and leaves a `w:asciiTheme` / `w:hAnsiTheme` beside them; Word reads a

{athena_python_docx-0.33.0 → athena_python_docx-0.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.33.0
+Version: 0.35.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.33.0 → athena_python_docx-0.35.0}/docx/__init__.py

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

{athena_python_docx-0.33.0 → athena_python_docx-0.35.0}/docx/_buffer.py

@@ -43,6 +43,7 @@ from docx._execution import (
     is_stale_execution,
 )
 from docx._timeouts import timeout_for_commands
+from docx._xml_text import check_command_text
 from docx.commands import (
     Command,
     GetNodeById,
@@ -596,6 +597,11 @@ class CommandBuffer:
         proxy's ``_node_id`` in-place.
         """
         self.ensure_usable()
+        # A write whose text holds a character XML does not allow raises
+        # python-docx's ValueError here, before anything is sent: every command
+        # comes through, a path-proxy op's and a direct ``send_command``'s.
+        if not is_query(cmd):
+            check_command_text(cmd.to_dict())
 
         # A read of the node the last command read, with nothing sent or
         # buffered since and within READ_REUSE_SECONDS of it, answers from

{athena_python_docx-0.33.0 → athena_python_docx-0.35.0}/docx/_capabilities.py

@@ -22,6 +22,16 @@ from docx._batching import run_sync
 # An older docx-studio gives none, so the SDK needs no check.
 TABLE_ANCHORS_CLIENT_CAPABILITY = "tableAnchors"
 
+# What this SDK declares in ``client.capabilities``: it renumbers the field
+# runs it holds once a whole run's text write (``run.text = …``, ``clear()``)
+# took out the page number blocks (``w:pgNum``) of a run docx-studio cut at
+# them, whose read lists their field indices (``pageNumberBlocks``). Such a
+# write then replaces all of the run, its blocks too, as python-docx replaces
+# its ``w:r``'s content, and each field after the blocks is numbered one lower
+# for each. An older docx-studio lists no blocks and keeps them, so the SDK
+# renumbers nothing.
+WHOLE_RUN_PIECES_CLIENT_CAPABILITY = "wholeRunPieces"
+
 # Session -> the capabilities its server reported, read once.
 _capabilities: "weakref.WeakKeyDictionary[Any, dict[str, Any]]" = weakref.WeakKeyDictionary()
 

{athena_python_docx-0.33.0 → athena_python_docx-0.35.0}/docx/_http_doc.py

@@ -44,7 +44,7 @@ from urllib3.util.retry import Retry
 from docx._batching import call_abandoned, note_progress
 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._capabilities import TABLE_ANCHORS_CLIENT_CAPABILITY, WHOLE_RUN_PIECES_CLIENT_CAPABILITY
 from docx._timeouts import (
     DEFAULT_OP_TIMEOUT_SECONDS,
     LONG_RUNNING_COMMAND_TIMEOUT_SECONDS,
@@ -87,6 +87,8 @@ from docx.commands import (
     CreateParagraph,
     CreateSectionBreak,
     CreateStyle,
+    EditLatentStyles,
+    DeleteStyle,
     CreateTable,
     CreateTOC,
     CreateWatermark,
@@ -1209,11 +1211,13 @@ 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``); holds anchored table ids (``docx.table``).
+                # (``docx._tracked``); holds anchored table ids (``docx.table``);
+                # renumbers its field runs after a cut run's whole write (``docx._run_order``).
                 "capabilities": [
                     TRACKED_AUTHORING_CAPABILITY,
                     TRACKED_MINIMAL_PARAGRAPH_TEXT_CAPABILITY,
                     TABLE_ANCHORS_CLIENT_CAPABILITY,
+                    WHOLE_RUN_PIECES_CLIENT_CAPABILITY,
                 ],
             },
             "commands": [
@@ -1374,6 +1378,8 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "styles.set_formatting": SetStyleFormatting,
     "styles.set_metadata": SetStyleMetadata,
     "styles.create": CreateStyle,
+    "styles.edit_latent": EditLatentStyles,
+    "styles.delete": DeleteStyle,
     "core_properties.set": SetCoreProperties,
     # Sections
     "sections.set_page_margins": SetSectionPageMargins,

{athena_python_docx-0.33.0 → athena_python_docx-0.35.0}/docx/_postproc.py

@@ -2897,6 +2897,15 @@ def _replace_flag(
         elem.set(f"{W_NS}val", "0")
 
 
+# The other ``w:jc`` justifications python-docx writes, by their lower case.
+_JUSTIFICATIONS_BY_LOWER = {
+    "mediumkashida": "mediumKashida",
+    "highkashida": "highKashida",
+    "lowkashida": "lowKashida",
+    "thaidistribute": "thaiDistribute",
+}
+
+
 def normalize_alignment(value: Any) -> str | None:
     """Convert a python-docx ``WD_ALIGN_PARAGRAPH`` value (or string) to
     the OOXML ``w:jc`` value (``left`` / ``center`` / ``right`` /
@@ -2919,7 +2928,7 @@ def normalize_alignment(value: Any) -> str | None:
             return "both"
         if s in {"distribute"}:
             return "distribute"
-        return None
+        return _JUSTIFICATIONS_BY_LOWER.get(s)
 
     # WD_ALIGN_PARAGRAPH enum values (int-like).
     name = getattr(value, "name", None)

athena_python_docx-0.35.0/docx/_proxy.py

@@ -0,0 +1,85 @@
+"""python-docx's ``ElementProxy`` equality, for the SDK's proxies of the
+objects python-docx wraps in one: styles, the styles part, settings, a
+paragraph's or a style's paragraph format, a run's or a style's font."""
+
+from __future__ import annotations
+
+import weakref
+from typing import Any
+
+
+class ElementProxyEquality:
+    """python-docx's ``docx.shared.ElementProxy`` equality: two proxies of the
+    same element are equal (``paragraph.style == doc.styles["Heading 1"]``),
+    a proxy of another element or anything else is not, and, as python-docx
+    defines ``__eq__`` there, a proxy is not hashable.
+
+    The element is :meth:`_proxy_element`: the docx-studio object it stands
+    for, named as the XML element python-docx's proxy wraps (a style's
+    ``w:style``, so a style, its font and its paragraph format are equal, as
+    they are in python-docx).
+    """
+
+    __slots__ = ()
+
+    def _proxy_element(self) -> tuple[object, ...]:
+        raise NotImplementedError
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ElementProxyEquality):
+            return False
+        return self._proxy_element() == other._proxy_element()
+
+    def __ne__(self, other: object) -> bool:
+        return not self.__eq__(other)
+
+    __hash__ = None  # type: ignore[assignment]
+
+
+# Session -> style id -> the style definition that id names in the session's
+# document now (:func:`style_definition`). Held weakly by session, as the
+# run order is (``docx._run_order``); the document stores none of it.
+_STYLE_DEFINITIONS: "weakref.WeakKeyDictionary[Any, dict[str, object]]" = weakref.WeakKeyDictionary()
+
+
+def _definitions(session: object) -> "dict[str, object] | None":
+    if session is None:
+        return None
+    try:
+        return _STYLE_DEFINITIONS.setdefault(session, {})
+    except TypeError:  # a session that takes no weak reference
+        return None
+
+
+def style_definition(session: object, style_id: str) -> object:
+    """The style definition (its ``w:style`` element) that ``style_id`` names in
+    ``session``'s document now, which a style proxy holds from its first read:
+    the same one after a rename (:func:`style_renamed`), another for a style
+    made after one of that id was deleted (:func:`style_deleted`)."""
+    definitions = _definitions(session)
+    if definitions is None:
+        return ("w:styleId", style_id)
+    return definitions.setdefault(style_id, object())
+
+
+def style_renamed(session: object, old: str, new: str) -> None:
+    """``style_id`` renamed the definition ``old`` named to ``new``."""
+    definitions = _definitions(session)
+    if definitions is not None:
+        definitions[new] = definitions.pop(old, None) or object()
+
+
+def style_deleted(session: object, style_id: str) -> None:
+    """``delete`` removed the definition ``style_id`` named."""
+    definitions = _definitions(session)
+    if definitions is not None:
+        definitions.pop(style_id, None)
+
+
+def style_element(style: object) -> tuple[object, ...]:
+    """The ``w:style`` element of ``style`` (a ``BaseStyle``): its document and
+    its definition (:func:`style_definition`), which a rename keeps."""
+    definition = getattr(style, "_definition", None)
+    if definition is None:
+        definition = ("w:styleId", getattr(style, "_style_id", None))
+    return ("w:style", getattr(style, "_session", None), definition)

{athena_python_docx-0.33.0 → athena_python_docx-0.35.0}/docx/_run_order.py

@@ -29,6 +29,7 @@ document stores none of it.
 
 from __future__ import annotations
 
+import bisect
 import itertools
 import weakref
 from dataclasses import dataclass, field
@@ -105,6 +106,36 @@ def _live_runs(run: "Run") -> list["Run"]:
     return [proxy for block_id in ids for proxy in list(blocks.get(block_id, ()))]
 
 
+def page_number_blocks_gone(run: "Run", gone: list[int], *, taken_out: bool) -> None:
+    """The page number blocks ``gone`` (their field indices) are no run's of
+    ``run``'s paragraph now: a whole run's text write took them out
+    (``taken_out``), or, with tracking on, deleted them, where they keep
+    their place and their numbers.
+
+    No live run proxy of the paragraph, read or created, lists them
+    (``pageNumberBlocks``). Taken out, each field after them is numbered one
+    lower for each, as docx-studio numbers them, so every proxy names its
+    field (``fieldIndex``) and the blocks it holds by the new numbers.
+    """
+    removed = sorted(set(gone))
+
+    def renumbered(index: int) -> int:
+        return index - bisect.bisect_left(removed, index) if taken_out else index
+
+    for proxy in _live_runs(run):
+        snapshot: object = getattr(proxy, "_inline_snapshot", None)
+        if not isinstance(snapshot, dict):
+            continue
+        index: object = snapshot.get("fieldIndex")
+        if isinstance(index, int) and not isinstance(index, bool):
+            snapshot["fieldIndex"] = renumbered(index)
+        blocks: object = snapshot.get("pageNumberBlocks")
+        if isinstance(blocks, list):
+            snapshot["pageNumberBlocks"] = [
+                renumbered(block) for block in blocks if isinstance(block, int) and block not in removed
+            ]
+
+
 def _move_live_runs(
     run: "Run",
     old_span: tuple[int, int],

athena_python_docx-0.35.0/docx/_xml_text.py

@@ -0,0 +1,46 @@
+"""What lxml refuses in XML text and attribute values, where python-docx meets it.
+
+python-docx writes every string it is given into an lxml element, and lxml
+raises ``ValueError`` for a character XML does not allow: C0 controls other
+than tab, LF and CR, the noncharacters U+FFFE / U+FFFF, and lone surrogates.
+So ``run.text = "a\\x0bb"`` (a vertical tab, Word's line break in its object
+model) raises there, before anything is written. docx-studio would take the
+text, and a part holding it is one Word refuses to open.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+XML_INCOMPATIBLE_CHARACTER = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\ud800-\udfff￾￿]")
+XML_INCOMPATIBLE_MESSAGE = (
+    "All strings must be XML compatible: Unicode or ASCII, no NULL bytes or control characters"
+)
+
+
+def check_xml_compatible(value: Any) -> None:
+    """Raise python-docx's ``ValueError`` (lxml's) when a string in ``value``,
+    a command's params (strings, lists, dicts), holds a character XML does
+    not allow."""
+    if isinstance(value, str):
+        if XML_INCOMPATIBLE_CHARACTER.search(value):
+            raise ValueError(XML_INCOMPATIBLE_MESSAGE)
+    elif isinstance(value, dict):
+        for item in value.values():
+            check_xml_compatible(item)
+    elif isinstance(value, (list, tuple)):
+        for item in value:
+            check_xml_compatible(item)
+
+
+#: Fields of a write that name text to find, not text to write
+#: (``FindReplace.pattern``): a pattern may match what a document already holds.
+_SEARCH_FIELDS: frozenset[str] = frozenset({"pattern"})
+
+
+def check_command_text(command: dict[str, Any]) -> None:
+    """:func:`check_xml_compatible` over a write's wire fields (a command's
+    ``to_dict()``), but for the text it searches for (``_SEARCH_FIELDS``)."""
+    check_xml_compatible({key: value for key, value in command.items() if key not in _SEARCH_FIELDS})
+

{athena_python_docx-0.33.0 → athena_python_docx-0.35.0}/docx/blkcntnr.py

@@ -9,6 +9,8 @@ docx-studio; ``isinstance(cell, BlockItemContainer)`` holds as in python-docx.
 
 from __future__ import annotations
 
+from docx._xml_text import check_xml_compatible
+
 from typing import TYPE_CHECKING, Iterator
 
 if TYPE_CHECKING:
@@ -30,6 +32,7 @@ class BlockItemContainer:
         self, text: str = "", style: "str | ParagraphStyle | None" = None
     ) -> "Paragraph":
         """Return paragraph newly added to the end of the content in this container."""
+        check_xml_compatible(text)
         raise NotImplementedError(f"{type(self).__name__} holds no paragraphs")
 
     def add_table(self, rows: int, cols: int, width: "Length") -> "Table":