athena-python-docx 0.38.0__tar.gz → 0.40.0__tar.gz

{athena_python_docx-0.38.0 → athena_python_docx-0.40.0}/AGENTS.md

@@ -136,12 +136,24 @@ pinned by focused tests and documented in
   r.add_picture(img)` writes the bold `w:rPr` beside the `w:drawing`. An older
   docx-studio puts the picture in a run of its own (`tests/test_drawing_image.py`,
   battery `ab_probe/picture_runs.py`).
-- **A run holding only a page or column break yields `""` from
-  `Run.iter_inner_content()`,** as python-docx reads a `w:br` of type `page`
-  or `column` as empty text; an empty run (a comment reference's) yields
-  nothing. docx-studio's read marks such a run with `break`, and
-  `Run.add_break` marks the run it adds one to. Against an older docx-studio,
-  which sends no `break`, a re-read run yields nothing.
+- **A run holding only a page or column break, or an empty text element
+  (`<w:t/>`), yields `""` from `Run.iter_inner_content()`,** as python-docx
+  reads a `w:br` of type `page` or `column`, and a `w:t` with no text, as
+  empty text; an empty run (a comment reference's) yields nothing.
+  docx-studio's read marks such a run with `break` (or `emptyText`), and
+  `Run.add_break` marks the run it adds one to; a text write to the run
+  drops `emptyText`. Against an older docx-studio, which sends neither, a
+  re-read run yields nothing.
+- **`doc.inline_shapes` lists a picture in a text box twice, as python-docx
+  does.** Word writes a text box in `mc:AlternateContent` as a DrawingML
+  shape and as its VML copy, each with the box's text, and python-docx's
+  `//w:p/w:r/w:drawing/wp:inline` finds the picture in both. The SDK asks
+  `ImagesList` for the second (`fallbackCopies`): a row under no id
+  (`fallbackCopy`) that reads its size, type and alt text as the export
+  writes the copy. A change of its size, alt text, title or decorative flag
+  warns (`DocxUnsupportedCommandWarning`) and sends nothing, as docx-studio
+  writes the copy from the box (`tests/test_inline_shape_type.py`). An older
+  docx-studio lists the picture once.
 - **`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
@@ -351,6 +363,13 @@ Issue numbers reference `python-openxml/python-docx`.
   through `CreateHyperlink` (DOCX Studio `doc.hyperlinks.create`). Returns
   the same `Hyperlink` class the read path already exposes. Also
   available as `Run.add_hyperlink` for convenience.
+  A link whose target has a scheme the editor does not keep (`file:`, a
+  mistyped `Mail:`, `javascript:`), written by a script or in the source, is
+  stored as written beside an empty clickable target (`unsafeHref`): it reads
+  as python-docx reads it (`Hyperlink`, `address`, `url`, its runs), the
+  export writes the target back, and the editor draws its text as a link that
+  nothing makes clickable (owner decision, 2026-10-23;
+  `hyperlinks-unlisted-schemes`).
 
 - **`Run.add_field(kind, *, args=None, cached_result=None) -> Field`**
   + **`Document.fields: Fields`** — generic Word field insertion.
@@ -1019,8 +1038,17 @@ architecture or a DOCX Studio constraint:
   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
+  or id is sent as the document's id. A style read resolves as python-docx's
+  `Styles.get_by_id`: the document's first style of the stored id when it is
+  of the type read; else, for an unstyled paragraph, run or table or one
+  naming a style of another type, the type's default style (the last the
+  document flags `w:default`), and None in a document that flags none, as
+  generated documents often do (`styles.default(...)` is None there too).
+  Each `w:style` is a style of its own, a second definition of an id (and
+  one with no `w:name`, whose name is None) included, reading its own name,
+  flags and formatting; a write to it changes the first definition of its id,
+  which docx-studio addresses by the id, where python-docx changes the one it
+  wraps. `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"`,
@@ -1028,7 +1056,16 @@ architecture or a DOCX Studio constraint:
   `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,
+  numbered list style), as Word does when the style is applied, so the
+  paragraph reads back as that built-in. A built-in the uploaded document's
+  source already named without defining it (`Info`'s `undefinedStyleIds`)
+  reads as the default paragraph style, as python-docx reads it and Word
+  draws it: the editor paints it so and the export adds no definition.
+  A header or footer part a read adds
+  (python-docx's `default-header.xml`) names `Header` (`Footer`) only where
+  the document defines it: elsewhere python-docx's reference resolves to the
+  default paragraph style and adds no definition, so the SDK's paragraph
+  names no style and the export adds none. 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
@@ -1104,13 +1141,12 @@ architecture or a DOCX Studio constraint:
   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`.
+  without `docProps/core.xml` reads as the default part python-docx adds to
+  it on first access (title "Word Document", last modified by
+  "python-docx", revision 1, and as `modified` the time of the session's
+  first read, which later reads keep, as python-docx keeps its part's;
+  docx-studio's `Info` marks it `corePropertiesDefault`), and a property set
+  there is written into that part, as python-docx writes it.
 
 - **`add_comment` without an `author` stores the session's name, not
   `""`.** `Document.add_comment` / `Comments.add_comment` send `author`
@@ -1166,12 +1202,29 @@ architecture or a DOCX Studio constraint:
   the base text keeps its room in the text-address space (`ruby` spans on the
   read's run; `tests/test_ruby_reads_python_docx_parity.py`). That holds while
   the paragraph's runs are as its records hold them, in the body, a table cell,
-  a header, a footer or a comment; a paragraph with a link or a tracked change
-  reads its runs from their marks, the base text included. A write to the run
+  a header, a footer or a comment; a body or cell paragraph with a link or an
+  inline content control reads its runs from the records its import keeps for
+  the reads alone (`_readRunRecords`), carried through an SDK run write
+  (`_writtenRunRecords`), until another edit changes them, a header's or
+  footer's with a link always does, and a paragraph with a tracked change, an
+  edited one with a link, and a comment's with a link read their runs from
+  their marks, the base text included. A write to the run
   (its text, an append, its formatting) makes the base text ordinary text,
   which then reads as text: docx-studio keeps no guide through an edit, where
   upstream keeps the `w:ruby` through all but a text write.
 
+- **A character of one of Word's run elements that the source wrote as text
+  reads as written.** A source can write a non-breaking or soft hyphen as the
+  character in a `w:t` (generated text holds them so), which upstream reads as
+  it is, where it reads a `w:noBreakHyphen` as `-` and a `w:softHyphen` as
+  nothing. docx-studio keeps each character it lists
+  (`LITERAL_CHARACTERS`, `packages/core/src/utils/wordCharacters.ts`) apart
+  from the element under the `literalCharacter` mark, and its reads send their
+  offsets in a run's text (`literalCharacters`), which `_word_text` reads as
+  written; a docx-studio that sends none reads each as the element, as before.
+  The export writes them back in a `w:t`, and text a script writes holds them
+  as upstream writes it, in a `w:t`.
+
 - **`CoreProperties.modified` is the time of the last save.** The asset is a
   live Word document, and docx-studio stamps `dcterms:modified` when it saves
   a change to the package: a section, style or property write, and the export
@@ -1191,6 +1244,95 @@ architecture or a DOCX Studio constraint:
   Markup) show insertions and hide deletions, as these reads do.
   `doc.revisions` lists every change (`tests/test_run_text_python_docx.py`).
 
+- **Runs inside an inline wrapper read as the paragraph's.** The runs of a
+  `w:smartTag`, an inline `w:customXml`, a `w:dir` or a `w:bdo` read in
+  `Paragraph.text`, `runs`, `iter_inner_content()`, `Hyperlink.runs` and
+  `_Cell.text`, as Word shows them; upstream reads only a `w:p`'s direct
+  `w:r` and `w:hyperlink` children, so it cannot see their text. With
+  upstream's reads, `p.text = p.text.replace(...)` on such a paragraph would
+  delete the wrapped text, which the setter clears unseen: 62 of 6,803
+  customer uploads hold text inside smart tags. Decided on 2026-10-21 under
+  the Word fidelity goal (owner question 47), the same choice as tracked
+  changes; the owner may overrule it. Recorded in
+  `tests/parity/intentional_deviations.json` (`live_deviations`).
+
+- **Two things a source writes that the model holds otherwise read as the
+  model holds them** (2026-10-22 SDK live parity run over 398 customer
+  documents). Each is recorded in
+  `tests/parity/intentional_deviations.json` (`live_deviations`) with a
+  synthetic fixture of `docx-fidelity/regression-fixtures/`:
+  - A run size written as a measure with a unit (`w:sz w:val="6mm"`, as
+    Microsoft Teams transcripts write it; 9 documents) reads in whole
+    half-points (`Length(215900)`, 17pt, where upstream reads 216000): under
+    a hundredth of a point, and holding the measure would change the stored
+    model of a run (`runs-measured-sizes`). Confirmed by the owner,
+    2026-10-23.
+  - A page margin written as decimal twips (`w:left="1440.0000000000002"`;
+    1 document) reads as the length it holds, where upstream raises
+    `ValueError`; the export writes it in whole twips
+    (`sections-fractional-twips`). Confirmed by the owner, 2026-10-23.
+
+- **Four more things a source writes that the model holds otherwise read as the
+  model holds them** (2026-10-22 SDK live parity run over 398 customer
+  documents, round 2). Each is recorded in `tests/parity/intentional_deviations.json`
+  (`live_deviations`) with a synthetic fixture of
+  `docx-fidelity/regression-fixtures/`:
+  - A run that holds Word's rendered page break before a page break
+    (`<w:lastRenderedPageBreak/><w:br w:type="page"/>`; 2 documents) yields the
+    page break's `""` before the `RenderedPageBreak`, as a run that holds them
+    the other way round does: the model holds the page break apart from the
+    paragraph and keeps no order between the two
+    (`breaks-rendered-before-page-break`). Confirmed by the owner, 2026-10-23.
+  - A rendered page break in the run that begins a field (2 documents) reads
+    in no run and no paragraph: the import keeps none in a field's own runs,
+    which its node stands for (`fields-rendered-break-begin-run`). Confirmed
+    by the owner, 2026-10-23.
+  - A table that names a table style its styles.xml does not define (1
+    document; 16 of 6,806 uploads) reads as Word's built-in style of that id,
+    which the editor draws it with, where upstream reads the default table
+    style; reading the default would change how such tables draw. The export
+    leaves the style undefined, as the source has it: an unedited download of
+    a document imported since is the source's bytes (owner, 2026-10-23). The read is kept until Word can be
+    checked, as no Word probe can be made on the machine that recorded it
+    (`tables-undefined-style`).
+  - A package with no styles part (1 document) reads Word's built-in styles,
+    which the editor gives it, where upstream reads its own default template's
+    (`styles-part-absent`). Confirmed by the owner, 2026-10-23.
+
+- **Two more reads follow the model where python-docx reads the source**
+  (2026-10-22 SDK live parity run over 398 customer documents, round 3). Each is
+  recorded in `tests/parity/intentional_deviations.json` (`live_deviations`)
+  with a synthetic fixture:
+  - A comment whose range ends between paragraphs (`w:commentRangeEnd` a
+    child of `w:body`; 1 document, 11 of 6,826 uploads) reads its reference
+    run at the end of the last paragraph its mark covers, where the export
+    writes it from the model, where upstream reads it in the paragraph after
+    the range end: the model holds a range as a mark on its text and no range
+    end between paragraphs (`comments-range-end-between-paragraphs`).
+    Confirmed by the owner, 2026-10-23.
+  - A comment's annotation reference run that names no character style
+    (1 document, 13 of 6,826 uploads) reads in the CommentReference style, in
+    which the export writes every comment's annotation run when it writes the
+    comments part: the model holds no annotation mark, and the parser keeps the
+    run as an empty run nothing tells from another
+    (`comments-annotation-ref-unstyled`). Confirmed by the owner, 2026-10-23.
+
+  A third, runs of one formatting read and exported joined after a run write
+  in a paragraph with a link, an inline content control, an equation or a
+  field beside a picture, is no longer a deviation (the owner asked for it to
+  be fixed, 2026-10-23, #46477): a run write (a format, `run.text`,
+  `add_run`, `add_text`) carries the records the read takes of such a
+  paragraph's runs (`_writtenRunRecords`), each `w:r` kept with the written
+  run changed as python-docx changes it, and the export writes the paragraph
+  from them. A write the records cannot describe (a format of a field's runs,
+  a write across a field, a run the offsets cannot tell from an empty one
+  beside it) leaves the paragraph as before: a link paragraph's kept content,
+  else the runs its marks make. Fixture scripts
+  `fixture-links-run-write-keeps-runs`, `fixture-links-run-writes`,
+  `fixture-content-controls-inline-run-writes`,
+  `fixture-equations-beside-runs-run-writes` and
+  `fixture-fields-beside-pictures-run-writes`.
+
 - **A citation link Athena added reads as its text, as the export writes it**
   (owner decision #40122). Athena's citation flow stamps the links it writes
   with the `Athena citation` tooltip. These links only navigate inside Athena,
@@ -1217,7 +1359,11 @@ architecture or a DOCX Studio constraint:
   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
+  on the same `.docx`; `DOCX_STUDIO_LIMITATIONS.md` § 27). A field the source
+  wrote whole in one `w:r` (begin, field code, separate and end, no result, as
+  generators write a page number) is that one run, a `begin` run with that
+  run's formatting, as python-docx reads it, and docx-studio writes it back
+  as one run. 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): the export keeps

{athena_python_docx-0.38.0 → athena_python_docx-0.40.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.38.0
+Version: 0.40.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.38.0 → athena_python_docx-0.40.0}/docx/__init__.py

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