athena-python-docx 0.32.0__tar.gz → 0.34.0__tar.gz

{athena_python_docx-0.32.0 → athena_python_docx-0.34.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,32 @@ 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 two whole-run formats.** 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`. Two
+  formats are refused while a block of the run has a node. A link's block
+  has none, and takes both as the run's text does. The first is a tracked
+  format (`track_revisions`), which raises `DocxError` naming
+  `TrackedChangesUnsupported`, because docx-studio records no tracked change
+  on a block. The second is the on/off properties no editor mark holds
+  (`font.no_proof`, `snap_to_grid`, `web_hidden`, `spec_vanish`, `math`,
+  `complex_script`, `cs_bold`, `cs_italic`), in any format that reaches a
+  block, which warn (`DocxUnsupportedCommandWarning`), because 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.32.0 → athena_python_docx-0.34.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.32.0
+Version: 0.34.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.32.0 → athena_python_docx-0.34.0}/docx/__init__.py

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

{athena_python_docx-0.32.0 → athena_python_docx-0.34.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.32.0 → athena_python_docx-0.34.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.32.0 → athena_python_docx-0.34.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.32.0 → athena_python_docx-0.34.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.32.0 → athena_python_docx-0.34.0}/docx/commands.py

@@ -248,6 +248,12 @@ class InsertLineBreak(Command):
     # in it, as python-docx writes it. Sent only to a docx-studio reporting
     # ``capabilities.inlineColumnBreak``; an older one ignores it.
     inline: bool | None = None
+    # ``"left"``, ``"right"`` or ``"all"``: a clearing line break
+    # (``Run.add_break(WD_BREAK.LINE_CLEAR_LEFT)`` and the rest), written as
+    # ``<w:br w:type="textWrapping" w:clear="…"/>``. Sent only to a
+    # docx-studio reporting ``capabilities.lineBreakClear``; an older one
+    # ignores it and inserts a line break.
+    clear: str | None = None
 
 
 @dataclass
@@ -304,6 +310,12 @@ class SetParagraphIndentation(Command):
 @dataclass
 class ClearParagraphIndentation(Command):
     target: dict[str, Any]
+    # Only these of the paragraph's own indents ("left", "right", "firstLine":
+    # the first-line or hanging indent), as python-docx's ``left_indent`` /
+    # ``right_indent`` / ``first_line_indent = None`` each clear their own.
+    # Without it, all of them. Sent only to a docx-studio reporting
+    # ``paragraphFormatClears``; an older one drops it and clears all.
+    only: list[str] | None = None
 
 
 @dataclass
@@ -318,6 +330,12 @@ class SetParagraphSpacing(Command):
 @dataclass
 class ClearParagraphSpacing(Command):
     target: dict[str, Any]
+    # Only these of the paragraph's own spacing ("before", "after", "line":
+    # the line spacing with its rule, "lineRule": the rule alone), as
+    # python-docx's ``space_before`` / ``space_after`` / ``line_spacing`` /
+    # ``line_spacing_rule = None`` each clear their own. Without it, all of
+    # them. Sent only to a docx-studio reporting ``paragraphFormatClears``.
+    only: list[str] | None = None
 
 
 @dataclass
@@ -326,6 +344,12 @@ class SetParagraphKeepOptions(Command):
     keep_next: bool | None = None
     keep_lines: bool | None = None
     widow_control: bool | None = None
+    # ``keep_with_next`` / ``keep_together`` / ``widow_control = None``: the
+    # paragraph's own value goes, and it takes its style's again. Sent only to
+    # a docx-studio reporting ``paragraphFormatClears``.
+    clear_keep_next: bool | None = None
+    clear_keep_lines: bool | None = None
+    clear_widow_control: bool | None = None
 
 
 @dataclass
@@ -347,6 +371,10 @@ class SetParagraphTabStop(Command):
     position: float
     alignment: str | None = None
     leader: str | None = None
+    # python-docx's ``add_tab_stop``: the stop goes in after any at its
+    # position, which stays (``insert_tab_in_order``). An older docx-studio
+    # drops the key and replaces that stop.
+    insert: bool | None = None
 
 
 @dataclass
@@ -381,6 +409,30 @@ class CreateStyle(Command):
     builtin: bool | None = None
 
 
+@dataclass
+class EditLatentStyles(Command):
+    """One python-docx write to ``styles.xml``'s ``w:latentStyles``:
+    ``defaults`` (``LatentStyles`` setters), ``add`` (``add_latent_style``,
+    the styles.xml name) or ``exception`` (``{"name", "attrs"}`` for a
+    ``_LatentStyle`` setter, ``{"name", "delete": True}`` for ``delete()``).
+    Sent only to a docx-studio reporting ``latentStyleWrites``."""
+
+    defaults: dict[str, Any] | None = None
+    add: str | None = None
+    exception: dict[str, Any] | None = None
+
+
+@dataclass
+class DeleteStyle(Command):
+    """A style's ``w:style`` removed from ``styles.xml``, as python-docx's
+    ``BaseStyle.delete()`` removes it: ``style_id`` names it, as for
+    ``SetStyleMetadata``. Sent only to a docx-studio reporting
+    ``deleteStyle``."""
+
+    style_id: str
+    style_type: str | None = None
+
+
 @dataclass
 class SetStyleMetadata(Command):
     """A style's metadata in ``styles.xml``, as python-docx's ``BaseStyle``
@@ -599,10 +651,15 @@ class TablesSetColumnWidth(Command):
 
 @dataclass
 class TablesSetRowHeight(Command):
+    """A row's ``w:trHeight``: ``height_pt`` its value and ``rule`` its
+    ``w:hRule`` (``"auto"`` | ``"exact"`` | ``"atLeast"``), each left as it is
+    when not given; ``NULL`` removes it, on a docx-studio that reports
+    ``tableClears``."""
+
     node_id: str
     row_index: int
-    height_pt: float
-    rule: str | None = None  # "auto" | "exact" | "atLeast"
+    height_pt: float | None = None
+    rule: str | None = None
 
 
 @dataclass
@@ -2051,6 +2108,11 @@ def is_response_bearing(cmd: Command) -> bool:
     if isinstance(cmd, CreateSectionBreak):
         # ``Document.add_section`` returns the section the answer names.
         return cmd.new_section is True
+    if isinstance(cmd, SetStyleMetadata):
+        # ``BaseStyle.style_id = …`` takes the new id once docx-studio renamed
+        # the style: a refused rename raises at the call, and the style keeps
+        # the id the document holds.
+        return "id" in (cmd.metadata or {})
     return cmd.type in _RESPONSE_BEARING_TYPES
 
 
@@ -2188,6 +2250,8 @@ __all__ = [
     "ClearParagraphTabStops",
     "SetStyleFormatting",
     "CreateStyle",
+    "EditLatentStyles",
+    "DeleteStyle",
     "SetStyleMetadata",
     "SetCoreProperties",
     # Sections

{athena_python_docx-0.32.0 → athena_python_docx-0.34.0}/docx/enum/base.py

@@ -62,6 +62,33 @@ class _DocxStudioWire:
         """``value`` as ``owner`` sends it: ``TypeError`` for a non-int,
         non-str value and ``ValueError`` for one naming no member, before
         anything reaches the wire."""
+        return cls._member_for(value, owner).to_docx_studio()
+
+    @classmethod
+    def _wire_for(cls, value: object, owner: str, session: Any, capability: str) -> str:
+        """``value`` as ``owner`` sends it to ``session``'s docx-studio: the
+        member's own string where an older docx-studio takes it too, or where
+        this one reports ``capability``; else :meth:`_wire`'s closest value,
+        with its warning. Only a value an older docx-studio collapses asks
+        docx-studio what it takes."""
+        import warnings
+
+        member = cls._member_for(value, owner)
+        exact = _wire_value(member)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            collapsed = member.to_docx_studio()
+        if exact is None or exact == collapsed:
+            return collapsed
+        from docx._capabilities import server_takes
+
+        if session is not None and server_takes(session, capability):
+            return exact
+        return member.to_docx_studio()
+
+    @classmethod
+    def _member_for(cls, value: object, owner: str) -> Any:
+        """The member ``value`` names for ``owner``, validated as :meth:`_wire` says."""
         if not isinstance(value, (int, str)):
             raise TypeError(
                 f"{owner} requires {cls.__name__}, int, or str; "
@@ -75,7 +102,7 @@ class _DocxStudioWire:
                 f"{owner} = {value!r}: not a valid {cls.__name__}. "
                 f"Expected a member or one of {[m.value for m in members]}."
             ) from exc
-        return member.to_docx_studio()
+        return member
 
 
 class BaseEnum(_DocxStudioWire, int, enum.Enum):

{athena_python_docx-0.32.0 → athena_python_docx-0.34.0}/docx/section.py

@@ -242,28 +242,12 @@ def _warn_section_dimension_clear(prop: str) -> None:
 
 
 class PendingSectionOnOffClearWarning(UserWarning):
-    """Emitted when ``Section.different_first_page_header_footer = None``.
-
-    python-docx 1.x semantics: ``None`` clears the OOXML
-    ``<w:titlePg/>`` element back to inherited. DOCX Studio 1.8's
-    ``sections.set_title_page`` only accepts ``enabled: bool`` — the
-    wire can't represent the clear-intent. The warning surfaces
-    silent-divergence. Tracked in
-    ``docx-studio/DOCX_STUDIO_LIMITATIONS.md``.
+    """No longer emitted: ``Section.different_first_page_header_footer =
+    None`` removes ``<w:titlePg/>`` as ``False`` does, as python-docx 1.x
+    does. Kept so code that filters or imports it keeps working.
     """
 
 
-def _warn_section_onoff_clear(prop: str) -> None:
-    warnings.warn(
-        f"Section.{prop} = None was IGNORED — DOCX Studio 1.8 has no "
-        f"clear-op for this OnOff property. The section keeps its "
-        f"previous value. Tracked in "
-        f"docx-studio/DOCX_STUDIO_LIMITATIONS.md.",
-        PendingSectionOnOffClearWarning,
-        stacklevel=3,
-    )
-
-
 def _require_section_bool(prop: str, value: object) -> bool:
     """Reject non-bool input on Section OnOff setters.
 
@@ -592,11 +576,12 @@ class Section:
 
     @different_first_page_header_footer.setter
     def different_first_page_header_footer(self, value: bool | None) -> None:
-        if value is None:
-            _warn_section_onoff_clear("different_first_page_header_footer")
-            return
-        enabled = _require_section_bool(
-            "different_first_page_header_footer", value
+        # python-docx removes ``w:titlePg`` for ``None`` as for ``False``
+        # (``CT_SectPr.titlePg_val``), and so does docx-studio for ``False``.
+        enabled = (
+            False
+            if value is None
+            else _require_section_bool("different_first_page_header_footer", value)
         )
         run_sync(
             self._session.doc.sections.set_title_page(

{athena_python_docx-0.32.0 → athena_python_docx-0.34.0}/docx/styles/_table.py

@@ -204,11 +204,13 @@ def style_table(session: Any) -> tuple[StyleRecord, ...] | None:
         # same session): what an earlier read reported is no longer current.
         _latent.pop(session, None)
     _stale.discard(session)
-    _writes_style_formatting[session] = bool(table) and any(
-        record.font is not None for record in table
+    # A server that showed it writes styles still does once deletes leave its
+    # table without the entries that told: the signal holds for the session.
+    _writes_style_formatting[session] = _writes_style_formatting.get(session, False) or (
+        bool(table) and any(record.font is not None for record in table)
     )
-    _writes_style_metadata[session] = bool(table) and any(
-        record.metadata is not None for record in table
+    _writes_style_metadata[session] = _writes_style_metadata.get(session, False) or (
+        bool(table) and any(record.metadata is not None for record in table)
     )
     return table