athena-python-docx 0.39.0__tar.gz → 0.41.0__tar.gz

{athena_python_docx-0.39.0 → athena_python_docx-0.41.0}/AGENTS.md

@@ -363,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.
@@ -1050,7 +1057,11 @@ architecture or a DOCX Studio constraint:
   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, so the
-  paragraph reads back as that built-in. A header or footer part a read adds
+  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
@@ -1193,14 +1204,29 @@ architecture or a DOCX Studio constraint:
   the paragraph's runs are as its records hold them, in the body, a table cell,
   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`) until an edit changes them, and a
-  paragraph with a tracked change, an edited one with a link, and a header's,
-  footer's or comment's with a link read their runs from their marks, the base
-  text included. A write to the run
+  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`. `Document.find_replace` keeps each hyphen
+  the replacement shares with the match as the match held it, and writes any
+  other in a `w:t`, as upstream writes text.
+
 - **`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
@@ -1220,6 +1246,111 @@ 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
+    (`tables-undefined-style`): checked on 2026-10-24 against the one sample
+    document's Word PDF, whose tables draw alike under either style (empty
+    paragraph defaults, the tables' own borders and margins) and match the
+    editor's Table Grid layout, so no corpus document yet tells the two apart.
+  - 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.
+
+- **One more read follows the model where python-docx reads the source**
+  (2026-10-22 SDK live parity run over 398 customer documents, round 3). It is
+  recorded in `tests/parity/intentional_deviations.json` (`live_deviations`)
+  with a synthetic fixture:
+  - 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 comment whose range ends between paragraphs (`w:commentRangeEnd` a child
+  of `w:body`; 1 document, 11 of 6,826 uploads) is no longer a deviation, with
+  the other comments whose reference run stands apart from the text their
+  range marks: one over links alone in several paragraphs or over a picture or
+  an object alone, which the model holds no range for, one that ends in a
+  paragraph holding none of its text, and one whose run follows a field's end
+  run. The import records where the source body holds each reference run and
+  range end (`commentReferenceRunPlaces`: the paragraph and how many of its
+  runs come before it), the paragraphs whose text it marks for the comment,
+  and the fingerprint of each body block that holds them. While those blocks
+  are as imported and the comment marks the same paragraphs, the run reads
+  where the source holds it, where the export keeps the blocks' source XML,
+  and a reply added since reads beside the comment's range end, where the
+  export writes it (`comments-range-end-between-paragraphs`,
+  `comments-range-over-links`, `comments-range-end-without-text`,
+  `comments-range-over-object`). A block an edit changed, a comment moved to
+  new text, and a room imported before the record read where the model places
+  the run, as before.
+
+  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 format of one of a field's own runs is carried too, into the
+  field's record (2026-10-24, #46477). A write the records cannot describe (a
+  write across a field, a field's result written, 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`,
+  `fixture-fields-beside-pictures-run-writes` and
+  `fixture-fields-beside-pictures-field-run-formats`.
+
 - **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,
@@ -1246,7 +1377,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.39.0 → athena_python_docx-0.41.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.39.0
+Version: 0.41.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.39.0 → athena_python_docx-0.41.0}/docx/__init__.py

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