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

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

@@ -31,14 +31,14 @@ These standard python-docx members don't apply to a DOCX Studio-backed SDK:
 
 - `Paragraph._p`, `Run._r` — XML element access (no local XML)
 - `Document.part`, `Paragraph.part`, `Run.part` — package part access
-- `Document.core_properties.last_modified_by` — we use Keryx attribution instead
 - `Document.settings` — Word app settings (not surfaced by DOCX Studio)
 - `InlineShape.chart` — charts are not currently surfaced by the SDK.
 - `Comment.add_paragraph` / `Comment.add_table` /
   `Comment.iter_inner_content` / `Comment.paragraphs` /
-  `Comment.tables` — DOCX Studio models a comment as a single text body,
-  not a `BlockItemContainer`. Use `Comment.text` instead. The
-  paragraph/table-bearing surface raises `CommentsNotImplementedError`.
+  `Comment.tables` — DOCX Studio models a comment as a single text body.
+  `Comment` is a `docx.blkcntnr.BlockItemContainer`, as `_Cell` and the
+  header/footer proxies are, but its paragraph/table-bearing surface raises
+  `CommentsNotImplementedError`. Use `Comment.text` instead.
 - **`_Cell.add_table(rows, cols)`** — surface preserved for parity
   (signature matches python-docx, no `width` kwarg) but raises
   :class:`docx.errors.NestedTableNotSupportedError` (subclass of
@@ -71,18 +71,41 @@ runtime, pending additional docx-editor command support. Behavior should be
 pinned by focused tests and documented in
 `docx-studio/DOCX_STUDIO_LIMITATIONS.md`.
 
-- **24 setters on `BaseStyle` / `CharacterStyle` / `ParagraphStyle`**
-  (`name`, `style_id`, `hidden`, `locked`, `priority`, `quick_style`,
-  `unhide_when_used`, `base_style`, `next_paragraph_style`) emit
-  `PendingStyleMutationWarning` and stash on `_overrides`.
-  The current `doc.styles.apply` command surface is constrained to
-  `target.scope: "docDefaults"` — no per-style metadata variant.
-  Behavior pinned by `tests/test_style_setters_contract.py` (11
-  tests); when docx-editor lands a metadata op, those tests will need
-  to flip to assert real bus calls.
-- **`Styles.latent_styles`** returns an empty `_LatentStyles` —
-  `DocInfoResult.styles` only surfaces `paragraphStyles[]` (a flat
-  usage-count list), not the OOXML `<w:latentStyles>` block.
+- **Style setters on `BaseStyle` / `CharacterStyle` / `ParagraphStyle`.**
+  The metadata setters (`name`, `hidden`, `locked`, `priority`,
+  `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
+  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`).
+- **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
+  text `""` for each picture (docx-studio reports it as a
+  `{drawing: {imageId}}` inline), and a linked picture is a run of its
+  `Hyperlink`. `run.text = ...` and `run.clear()` on a picture run remove the
+  picture with its text (`Replace` with `removePictures`). The drawing's
+  `has_picture` is True and its `image` is a `docx.image.image.Image` read
+  through `ImagesGet` (python-docx's `blob`, `content_type`, `px_width`,
+  `horz_dpi`, `width`, `scaled_dimensions`, …). A picture in a table cell or
+  a header has no id to read its image by, so `.image` raises `ValueError`;
+  an older docx-studio does not report pictures, so they are not runs there.
+- **`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
+  `PendingLatentStylesReadWarning`.
 
 ### Intentional deviations (additions / different semantics)
 
@@ -100,31 +123,36 @@ not file-backed. Each is documented in the relevant docstring.
   URIs. Local paths and file-like streams behave exactly as upstream.
   The dispatch lives in ``docx._image_utils.load_image_bytes``; a failed
   fetch/decode raises a ``ValueError`` at the call site rather than a
-  bare transport error. This is the only image-input deviation — the
-  resulting bytes still flow through the same magic-byte
-  ``sniff_content_type`` → base64 ``data:`` URI → ``create.image`` path.
+  bare transport error. The resulting bytes go through the same
+  signature check as upstream: a stream that is no PNG, JPEG, GIF, BMP or
+  TIFF (nor, beyond python-docx, WebP or SVG) raises
+  ``docx.image.exceptions.UnrecognizedImageError`` whatever its file name,
+  where it used to land as a 6" x 4.5" guess
+  (``docx._image_utils.image_content_type``).
 
 - **Built-in table style friendly names resolve to OOXML styleIds.**
   Word's ``styles.xml`` ships built-in table styles whose styleIds
   (``LightGrid-Accent1``, ``MediumShading1-Accent2``, …) differ from
-  their display names (``"Light Grid Accent 1"``, …). Stock
-  python-docx resolves the friendly form against the loaded
-  document's styles collection at write time. We can't read
-  ``styles.xml`` over HTTP, so ``Document.add_table(style=...)`` /
-  ``Table.style`` setter consult an in-process map
-  (``docx._table_styles.BUILTIN_TABLE_STYLE_IDS``) covering every
-  Word 2007 and Word 2013+ built-in table style (204 entries) before
-  the value reaches ``<w:tblStyle w:val="..."/>``. Without this
-  mapping Word can't resolve the friendly name in ``styles.xml``
-  and silently falls back to ``Normal Table`` (no borders, no
-  header fill, no banding). Custom user-defined style names pass
-  through unchanged. Whether Word actually renders a Word 2013+
-  style after resolution also depends on the exported
-  ``styles.xml`` containing the matching ``<w:style w:type="table">``
-  definition. If the exported ``styles.xml`` only carries the Word 2007
-  set, Word 2013+ styleIds resolve in the ``<w:tblStyle>`` element but
-  still fall back to ``Normal Table`` until the export path ships an
-  expanded ``styles.xml``.
+  their display names (``"Light Grid Accent 1"``, …). Like python-docx,
+  ``Document.add_table(style=...)`` / the ``Table.style`` setter resolve
+  a name through the document's style table (docx-studio ``Info``) and
+  raise ``KeyError`` for a name it lacks — except a Word built-in table
+  style docx-studio holds Word's definition of (python-docx's default
+  template: Table Grid, Light Shading … Colorful Grid and their accents),
+  which resolves through an in-process map
+  (``docx._table_styles.BUILTIN_TABLE_STYLE_IDS``) when the document does
+  not define it: the editor draws it from that definition and the export
+  adds the definition to ``styles.xml``, as Word does when the style is
+  applied. A Word 2013+ table style (Grid Table, List Table, Plain Table)
+  the document lacks raises ``KeyError``, as in python-docx, whose
+  template defines none. Against a docx-studio that sends no table every
+  built-in name (Word 2007 and 2013+, 204 entries) is sent as its id, and
+  custom names pass through unchanged. ``Document.add_table`` with no
+  style keeps Athena's brand table look (direct cell borders and zebra
+  fill, no ``w:tblStyle``) where python-docx's table has none; a style
+  set on the table replaces that look, and borders and fills set on its
+  cells stay. ``table.style = None`` removes an existing table's style as
+  python-docx does (``DOCX_STUDIO_LIMITATIONS.md`` § 25).
 
 - **`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
@@ -185,10 +213,10 @@ not file-backed. Each is documented in the relevant docstring.
 
 - **`Document.user_name: str | None` / `Document.user_email: str |
   None`** — author identity threaded through to DOCX Studio on session-
-  open for tracked-change attribution. python-docx's
-  `Document.core_properties.last_modified_by` is the closest upstream
-  surface; we use the DOCX Studio-native fields directly because DOCX Studio
-  bakes them into the change records.
+  open for tracked-change attribution; DOCX Studio bakes them into the
+  change records. Separate from `Document.core_properties.last_modified_by`,
+  the `docProps/core.xml` metadata the SDK reads and writes as python-docx
+  does.
 
 - **`Document.revisions: Revisions`** — collection of tracked changes
   with iteration, `get(id)`, `accept_all()`, `reject_all()`,
@@ -196,6 +224,26 @@ 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,
+  because the result would be a document Word cannot resolve
+  (`tests/test_style_metadata_writes.py`):
+  - `Styles.add_style` raises `ValueError` for a style id the document
+    already has (a name without the space, `"Heading1"`, derives the id
+    of the existing Heading 1), where python-docx appends a second
+    definition of that id;
+  - `base_style = ` a style whose `basedOn` chain reaches this one (itself
+    included) raises `ValueError`, where python-docx writes a chain Word
+    refuses;
+  - `priority = True` raises `TypeError`, where python-docx (to which a
+    `bool` is an `int`) writes `w:uiPriority w:val="True"`, not a
+    number; any other non-`int` raises `TypeError` in both.
 
 ### Athena extensions for most-requested upstream features (v0.11.0+)
 
@@ -287,7 +335,10 @@ Issue numbers reference `python-openxml/python-docx`.
   python-docx surfaces `_Cell.grid_span` (horizontal) but the
   vertical merge state and master detection are issue #1312, #1434,
   #1458. Pure derived properties from existing `tables.getCells`
-  data.
+  data: docx-studio reports `vMerge` for the grid position asked
+  about (`"restart"` on the merged cell's first row, `"continue"`
+  below it), while `text`, `grid_span` and writes resolve to the
+  merged cell from any position it covers.
 
 - **`Table.add_row(*, copy_format_from=None)`** — when `copy_format_from`
   is provided (int row index or `_Row`), the new row inherits height,
@@ -373,6 +424,30 @@ Issue numbers reference `python-openxml/python-docx`.
   numbering reads. python-docx issue #471 (13 👍) demands access to
   list metadata. Routes through `NumberingGet`.
 
+- **`Paragraph.restart_numbering(start=1)`** (0.26.0+) — restart the
+  paragraph's numbered list at `start`, as Word's "Restart at 1" does
+  ("Set Numbering Value" for another start). All `"List Number"`
+  paragraphs share one numbering, as in Word and python-docx, so a list
+  after a heading or table counts on (3, 4) until restarted. python-docx
+  has no way to restart a list: issue #25, open since 2014. Routes
+  through `ListsSplit` (`restartNumbering: true`, `start`), sent in a
+  request of its own after the buffered edits. docx-studio adds a `w:num`
+  on the list's `w:abstractNum` whose
+  `<w:lvlOverride w:ilvl="N"><w:startOverride w:val="start"/>` (ECMA-376
+  §17.9.27) starts the paragraph's level, and points the paragraph and the
+  later items of its `w:num` at it: up to the next item of a shallower
+  level, the next list restarted on its own, or the end of the document.
+  Headings, tables, body text and other lists between the items do not
+  end the list, because Word counts across them. A header or footer
+  paragraph restarts within its part, whose paragraphs count on their own.
+  The same restart again changes nothing. A paragraph that takes no number (plain, heading,
+  bullet) raises `docx.errors.NotNumberedListItemError` (a `ValueError`);
+  `start` outside 0..32767 raises `ValueError`; a docx-studio API without
+  the handler raises `DocxUnsupportedCommandError`. The new `w:num` lives
+  in the source package, so each restart stores the package again (one
+  copy in the room's history) until #41656 item 7's writers store it by
+  reference.
+
 - **`Document.to_pdf(*, quality=None, destination=None,
   include_revisions=False) -> bytes`** — render to PDF. python-docx
   issue #113 was closed as
@@ -752,28 +827,35 @@ gaps. The items below are the **residual intentional deviations** that
 remain because matching upstream would break the asset-backed/HTTP
 architecture or a DOCX Studio constraint:
 
-- **`WD_*` enum `.value` is the DOCX Studio wire string, not the MS Word
-  integer constant.** `WD_ALIGN_PARAGRAPH.CENTER.value == "center"`
-  (upstream: `1`); `int(member)` / `member == 1` / `WD_*(1)` therefore
-  differ. The string value is load-bearing — every command serializes
-  `enum.value` directly onto the wire (`underline=value.value`,
-  `WD_COLOR_INDEX(v).value`, …), so int-valuing the enums would require
-  re-plumbing the entire command layer. Members are accessed by name
-  (`WD_ALIGN_PARAGRAPH.CENTER`), so the drift is academic for normal
-  use. (`WD_STYLE`/`WD_BUILTIN_STYLE` and `WD_INLINE_SHAPE_TYPE` are NOT
-  wire-load-bearing and DO carry the upstream int values.)
+- **Enum-typed setters also take the member's DOCX Studio string.** The
+  `WD_*` / `MSO_*` enums are python-docx's (`docx.enum.base.BaseEnum` /
+  `BaseXmlEnum`): every member is its MS API int
+  (`WD_ALIGN_PARAGRAPH.CENTER == 1`, `str()` is `"CENTER (1)"`), XML
+  enums carry `xml_value` and `from_xml`/`to_xml`, and the aliases are
+  upstream's (`WD_ALIGN_PARAGRAPH is WD_PARAGRAPH_ALIGNMENT`,
+  `WD_BREAK.TEXT_WRAPPING is WD_BREAK.LINE_CLEAR_ALL`). Setters take a
+  member or its int value as upstream does; they additionally accept the
+  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`
+  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`
+  reads as `WD_TABLE_ALIGNMENT` and takes its three members (upstream
+  reads the equal `WD_PARAGRAPH_ALIGNMENT` member and takes any of its
+  values), and `Table.table_direction` reads as `WD_TABLE_DIRECTION`
+  (upstream: the equal bool). `WD_BUILTIN_STYLE` members carry no
+  per-member docstring.
 
 - **`RGBColor.from_string` additionally accepts a leading `#`.** Upstream
   rejects `"#FF0000"`; agents routinely pass it, so a single `#` is
   stripped before the (otherwise byte-identical) upstream slice parse.
   A strict superset — every value upstream accepts parses identically.
 
-- **`_Cell.vertical_alignment` setter accepts the four DOCX Studio wire
-  tokens** (`"top"`/`"center"`/`"bottom"`/`"both"`) in addition to
-  `WD_ALIGN_VERTICAL` members. Upstream rejects all plain strings; this
-  is an ergonomic superset (typos like `"middle"` still raise
-  `ValueError`).
-
 - **`Table.cell(row, col)` bounds-checks each axis independently** and
   raises `IndexError` for an out-of-range row or column. Upstream
   indexes a single flat row-major `_cells` list, so a column overflow
@@ -783,35 +865,151 @@ architecture or a DOCX Studio constraint:
   cheaply enumerate every cell. `(0,0)` and in-range negative indices
   behave identically to upstream.
 
-- **Unknown paragraph style names raise only when Word has no such
-  built-in.** Style names and ids follow python-docx: `.name` is the UI
-  name (`"Heading 1"`), `.style_id` the id (`"Heading1"`), read from the
-  document's style table (docx-studio `Info` with `includeStyles`, fetched
-  once per session in `docx/styles/_table.py`). A style set by name or id
-  is sent as the document's id, and an unstyled paragraph reads as the
+- **Unknown paragraph style names raise only when docx-studio has no
+  definition for them.** Style names and ids follow python-docx: `.name` is
+  the UI name (`"Heading 1"`), `.style_id` the id (`"Heading1"`), read from
+  the document's style table (docx-studio `Info` with `includeStyles`,
+  fetched once per session in `docx/styles/_table.py`). A style set by name
+  or id is sent as the document's id, and an unstyled paragraph reads as the
   default paragraph style. `paragraph.style = …` raises `KeyError` for a
-  name the document defines no style for, like python-docx — except Word's
-  built-in styles (`"Heading 4"`, `"List Bullet"`, `"Title"`…), which many
-  templates never write into `styles.xml` until used. Those are sent by
-  their Word id; Word and docx-studio apply the built-in definition. Against
-  an older docx-studio (no style table) a built-in name is sent as its id
-  and anything else as given.
+  name the document defines no style for, like python-docx — except the
+  Word built-ins docx-studio holds a definition of
+  (`BUILTIN_PARAGRAPH_STYLE_NAMES`: `"Heading 4"`, `"List Bullet"`,
+  `"Footnote Text"`, `"TOC 1"`…), which many templates never write into
+  `styles.xml` until used. Those are sent by their Word id; the paragraph
+  holds `w:pStyle` alone, the editor paints it from that definition and
+  the export adds the definition (with a list of the document's own for a
+  numbered list style), as Word does when the style is applied. Heading 1–9,
+  Title, Subtitle, Quote, Intense Quote, List Paragraph, No Spacing and
+  Caption are defined by hand to current Word's definitions
+  (`packages/core/src/prosemirror/styles/latentBuiltInStyles.ts`); the
+  others are python-docx's default template's, and docx4j's
+  `KnownStyles.xml` (Word 2007) for the ones it lacks
+  (`packages/core/src/docx/builtInStyles.generated.ts`). `"List Bullet 4"`/
+  `"5"` and `"List Number 4"`/`"5"` raise `KeyError`: python-docx's template
+  holds no numbering for them. Against an older docx-studio (no style table)
+  a built-in name is sent as its id and anything else as given.
+  `Run.style` follows the same rule for character styles: it returns a
+  `CharacterStyle` (Default Paragraph Font for a run naming none), and a
+  name the document lacks raises `KeyError` unless docx-studio holds Word's
+  definition of it (`BUILTIN_CHARACTER_STYLE_NAMES` in
+  `docx/styles/_table.py`: `"Strong"`, `"Intense Emphasis"`, `"Book Title"`…).
+  `Document.add_table(style=)` and `Paragraph.add_run(style=)` resolve the
+  style before creating anything, so a rejected style leaves the document
+  untouched; python-docx raises after adding the table or run to its
+  in-memory tree, but an edit here is live.
 
 - **`Document.add_table(rows, cols)` requires `rows >= 1` and
   `cols >= 1`.** Upstream allows a 0-row/0-col grid you later populate,
   but DOCX Studio's ProseMirror table node can't represent one; the SDK
   raises eagerly rather than failing opaquely on the wire.
 
+- **`_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
+  a cell inside the rectangle crosses its edge python-docx sometimes
+  raises `ValueError` (no `w:tc` at the rectangle's left edge) or writes a
+  vertical merge Word reads as broken. docx-studio applies the merge, so
+  `merge()` sends a request of its own and raises at the call.
+
+- **`core_properties.modified` follows saves that change the package.**
+  `doc.core_properties` reads and writes `docProps/core.xml` as python-docx
+  does (docx-studio `Info` with `includeCoreProperties`, `SetCoreProperties`;
+  `DOCX_STUDIO_LIMITATIONS.md` § 8), but docx-studio stamps `modified` with
+  the time of a save that changes the package, a core property included, as
+  Word does, where python-docx never stamps it. A `modified` the script sets
+  wins in the save that writes it (a later save in the same batch stamps
+  again). Every read asks docx-studio, which saves the batch's edits before it
+  answers, so a read sees the stamp, and a collaborator's save. A package
+  without `docProps/core.xml` reads
+  every property as missing, where python-docx adds its own default part
+  (title "Word Document", last modified by "python-docx").
+
 - **`Comment.comment_id` returns `str`, not `int`.** DOCX Studio uses
   non-numeric entity ids (`"c-42"`), so the upstream `int` contract
   can't be honored. Tracked in `DOCX_STUDIO_LIMITATIONS.md`.
 
-- **`Section` dimension setters and `ParagraphFormat.line_spacing_rule
-  = None` warn-and-preserve on a clear** rather than raising (upstream
-  accepts `None` to clear, but DOCX Studio's merging mutation ops have no
-  single-attribute clear). They emit a `Pending…ClearWarning` and leave
-  the value intact instead of destructively clearing the whole block.
-  Tracked in `DOCX_STUDIO_LIMITATIONS.md`.
+- **`add_comment` without an `author` stores the session's name, not
+  `""`.** `Document.add_comment` / `Comments.add_comment` send `author`
+  and `initials` and docx-studio stores them as `w:author` /
+  `w:initials`, as python-docx does; with none (python-docx's default
+  `""`) the author is `Document.user_name`, else `"Athena"`, and no
+  initials are stored (`initials` then reads `None`). The SDK raises
+  `ValueError` for what lxml refuses in an attribute, as python-docx
+  does, and also past docx-studio's caps (255 UTF-16 code units for an
+  author, 32 for initials); docx-studio turns tabs, line breaks and other
+  control characters into spaces. The author is display text only:
+  Keryx attributes the edit to the signed-in user (and agent), and
+  nothing reads a comment's author as identity.
+
+- **`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
+  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
+  value. Tracked in `DOCX_STUDIO_LIMITATIONS.md`.
+
+- **`Run.text` / `Paragraph.text` read Word's run elements as upstream
+  does** (`-` for a non-breaking hyphen, nothing for a soft hyphen or a
+  symbol; `\t` for a `w:ptab` in a room that holds it as a tab), but a tab or
+  break of an imported run can read as a run of its own. Writes keep text as
+  given. `Run.add_tab()` and `Run.add_break()` take the run's formatting, as
+  upstream appends them to the run's `w:r`; `Run.add_break(WD_BREAK.COLUMN)`
+  sends a column break (`breakType: "column"`), which docx-studio writes after
+  the paragraph's content. `DOCX_STUDIO_LIMITATIONS.md` §26.
+
+- **Tracked changes read as Word's final view.** `Paragraph.text`, `runs`,
+  `iter_inner_content()`, `Hyperlink.text` / `runs` and `_Cell.text` include
+  the runs of a tracked insertion (`w:ins`) and leave out a deletion's
+  (`w:del`); upstream omits both, as it reads only a `w:p`'s direct `w:r` and
+  `w:hyperlink` children. Upstream cannot write tracked changes, so it has no
+  write-then-read case to match; with `track_revisions` on (the Athena
+  extension), `with doc.tracked_revisions(): p.text = "Updated forecast"`
+  deletes the old text and inserts the new, and upstream's omission would
+  read the paragraph back as `""`. Word's default views (Simple Markup, No
+  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
 

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

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

{athena_python_docx-0.25.0 → athena_python_docx-0.27.0}/docx/_http_doc.py

@@ -76,6 +76,7 @@ from docx.commands import (
     CreateMath,
     CreateParagraph,
     CreateSectionBreak,
+    CreateStyle,
     CreateTable,
     CreateTOC,
     CreateWatermark,
@@ -132,6 +133,7 @@ from docx.commands import (
     SetCellShading,
     SetChartData,
     SetChartType,
+    SetCoreProperties,
     SetImageAltText,
     SetImageAnchor,
     SetImageDecorative,
@@ -151,6 +153,8 @@ from docx.commands import (
     SetSectionPageSetup,
     SetSectionTitlePage,
     SetSectionsOddEvenHeadersFooters,
+    SetStyleFormatting,
+    SetStyleMetadata,
     SetTableBorders,
     TablesGet,
     TablesGetCells,
@@ -177,9 +181,11 @@ from docx.errors import (
     DocxStudioTemporarilyUnavailable,
     DocxUnsupportedCommandWarning,
     NotFoundError,
+    NotNumberedListItemError,
     SessionError,
     _missing_block_id,
 )
+from docx.exceptions import InvalidSpanError
 
 
 _NOT_FOUND_ERROR_NAMES: frozenset[str] = frozenset(
@@ -632,6 +638,17 @@ def _http_post_json(
         err_obj = parsed.get("error") if isinstance(parsed, dict) else None
         if isinstance(err_obj, dict):
             base_msg = f"docx-studio batch reported a partial failure: {parsed!r}"
+            # A merge python-docx refuses (``_Cell.merge``) raises python-docx's
+            # own exception.
+            if err_obj.get("error") == "InvalidSpanError":
+                raise InvalidSpanError(
+                    str(err_obj.get("message") or base_msg),
+                ).with_partial_applied(partial_applied)
+            # ``Paragraph.restart_numbering`` on a paragraph that takes no number.
+            if err_obj.get("error") == "NotNumberedListItem":
+                raise NotNumberedListItemError(
+                    str(err_obj.get("message") or base_msg),
+                ).with_partial_applied(partial_applied)
             # ``BlockNotFoundError`` is the narrower miss — caller is most
             # likely targeting a cell-inner paragraph or stale-session
             # block id. Surface the typed exception plus an agent-readable
@@ -1011,6 +1028,10 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "format.paragraph.set_tab_stop": SetParagraphTabStop,
     "format.paragraph.clear_all_tab_stops": ClearParagraphTabStops,
     "styles.paragraph.set_style": SetParagraphStyle,
+    "styles.set_formatting": SetStyleFormatting,
+    "styles.set_metadata": SetStyleMetadata,
+    "styles.create": CreateStyle,
+    "core_properties.set": SetCoreProperties,
     # Sections
     "sections.set_page_margins": SetSectionPageMargins,
     "sections.set_page_setup": SetSectionPageSetup,
@@ -1069,8 +1090,8 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     # consumed internally by ``Document.add_paragraph`` to make
     # ``style="List Bullet" | "List Number"`` produce real list
     # structure (not just a style attribute on a flat paragraph).
-    # ``lists.merge``/``lists.split`` stay typed-bus-only — no
-    # python-docx parity surface for them.
+    # ``lists.split`` backs the Athena extension
+    # ``Paragraph.restart_numbering``; ``lists.merge`` stays typed-bus-only.
     "lists.create": ListsCreate,
     "lists.attach": ListsAttach,
     "lists.merge": ListsMerge,