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

{athena_python_docx-0.24.0 → athena_python_docx-0.26.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()`,
@@ -197,6 +225,21 @@ not file-backed. Each is documented in the relevant docstring.
   has zero track-changes API, so this entire surface is an Athena
   extension wired to DOCX Studio's `doc.trackChanges.{list,get,decide}`.
 
+- **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+)
 
 These surfaces are **additions** to python-docx, not deviations from
@@ -268,7 +311,14 @@ Issue numbers reference `python-openxml/python-docx`.
   inside_horizontal=, inside_vertical=)`** + **`_Cell.borders`**
   property + **`Table.set_borders(...)`** — per-edge border control.
   python-docx issue #201 (5 👍), #1238 demand a cell-borders API.
-  Routes through `SetCellBorders` / `SetTableBorders`.
+  Routes through `SetCellBorders` / `SetTableBorders`. Each edge is
+  `{"style", "size_pt", "color", "space"}` (points; `sizePt` also
+  accepted) or `"single 0.5pt #D9D9D9"`; the SDK validates it and sends
+  `{style, sizePt, color: "#RRGGBB", space}`. Any other key (`val`, `sz`,
+  `size`, `width`) raises `ValueError` naming the accepted form, and
+  docx-studio refuses it too (`InvalidBorderSpec`): such edges were once
+  stored without their size and colour, and one with no style broke every
+  later export of the document.
 
 - **`_Cell.set_shading(*, fill=, pattern=, color=)`** +
   **`_Cell.shading`** property — cell fill / shading. python-docx
@@ -280,7 +330,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,
@@ -366,11 +419,57 @@ 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
   wontfix upstream but the request keeps recurring. Routes through
-  `ExportPDF` (DOCX Studio handles the actual conversion).
+  `ExportPDF` (0.25.0+ opens the session first and sends buffered edits in
+  the same request). DOCX Studio lays the document out with the engine the
+  editor paginates with and paints every page onto Skia's PDF backend: a
+  vector PDF with selectable text in embedded fonts that matches
+  `render_page` — no LibreOffice anywhere, so never install it in a sandbox.
+  `quality` is `"draft"` (pictures as JPEG), `"standard"` (default) or
+  `"high"`; `include_revisions=True` shows tracked changes as markup (the
+  default renders them accepted); `destination` writes a local file and
+  refuses asset ids and URLs with `ValueError`. A deployment that cannot
+  produce the PDF raises `DocxUnsupportedCommandError` naming the reason.
+  `GET /docs/:id/export.pdf` serves the same PDF read-only (VIEW gate).
+
+- **`Document.render_page(page_number=1, scale=2, as_pil=False)`** +
+  **`Document.screenshot_to_path(path, page=1, scale=2) -> Path`** +
+  **`Document.page_count`** (0.25.0+) — look at the document as the editor
+  lays it out: one page (numbered from 1) as PNG bytes or a Pillow image,
+  written to disk, and the page count. Names follow
+  athena-python-pptx's `slide.render(scale=2, as_pil=True)` and
+  athena-openpyxl's `Worksheet.screenshot_to_path`. Buffered edits flush
+  first. Backed by docx-studio's read-only `GET /docs/:id/pages/:n.png` and
+  `GET /docs/:id/layout.json` (VIEW gate, the SDK's API key); a page past
+  the end raises `PageOutOfRangeError` (an `IndexError`) carrying
+  `page_count`.
 
 - **`Document.clear()`** (0.14.0+) — empty the document body so subsequent
   writes start from a clean slate. python-docx has no equivalent (it
@@ -723,28 +822,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
@@ -754,28 +860,113 @@ architecture or a DOCX Studio constraint:
   cheaply enumerate every cell. `(0,0)` and in-range negative indices
   behave identically to upstream.
 
-- **`BaseStyle.style_id` returns the display name for built-ins** (so
-  `style_id == name`). The SDK is HTTP-only and can't read `styles.xml`
-  to recover the OOXML styleId (`"Heading 1"` → `"Heading1"`); the wire
-  format also uses the display name as the style id. Consequently
-  `get_by_id("Heading1", …)` / `"Heading1" in styles` won't resolve the
-  OOXML-id form (use the display name).
+- **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 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`).
 
 ### If you need a deviation
 

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

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

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

{athena_python_docx-0.24.0 → athena_python_docx-0.26.0}/docx/_buffer.py

@@ -341,6 +341,10 @@ class CommandBuffer:
         self._asset_id: str = asset_id
         self._pending: list[Command] = []
         self._lock: threading.RLock = threading.RLock()
+        # Held for the whole of a flush (drain + POST), so batches reach the
+        # server one at a time and in order, and a flush returns only once
+        # every batch taken before it has been delivered.
+        self._post_lock: threading.RLock = threading.RLock()
         self._timer: threading.Timer | None = None
         self._auto_flush_seconds: float = auto_flush_seconds
         self._closed: bool = False
@@ -532,6 +536,14 @@ class CommandBuffer:
         proxies pick up real ids without the caller ever seeing the
         UUID swap.
         """
+        # One batch in flight at a time: a flush that finds the queue empty
+        # still waits for a batch the idle timer already took and is posting,
+        # so a read that follows (a query, a page render) sees those edits and
+        # a failure of that batch is raised here.
+        with self._post_lock:
+            return self._flush_in_order()
+
+    def _flush_in_order(self) -> list[Any]:
         self._assert_current_execution()
         self._raise_deferred_flush_error()
         with self._lock:
@@ -599,7 +611,12 @@ class CommandBuffer:
         still get their real ids written back via the same flush-time
         rewrite that :meth:`flush` does.
         """
+        with self._post_lock:
+            return self._eager_flush_in_order(cmd)
+
+    def _eager_flush_in_order(self, cmd: Command) -> Any:
         self._assert_current_execution()
+        self._raise_deferred_flush_error()
         with self._lock:
             self._cancel_timer_locked()
             pending = self._pending