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

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

@@ -1223,7 +1223,9 @@ architecture or a DOCX Studio constraint:
   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`.
+  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
@@ -1292,24 +1294,19 @@ architecture or a DOCX Studio constraint:
     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 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.
 
-- **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
+- **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 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
@@ -1317,6 +1314,25 @@ architecture or a DOCX Studio constraint:
     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
@@ -1324,14 +1340,16 @@ architecture or a DOCX Studio constraint:
   `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
+  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` and
-  `fixture-fields-beside-pictures-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

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

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

{athena_python_docx-0.40.0 → athena_python_docx-0.41.0}/docx/comments.py

@@ -40,6 +40,7 @@ from docx._batching import run_sync
 from docx._buffer import writes_unapplied
 from docx.blkcntnr import BlockItemContainer
 from docx.errors import DocxError, NotFoundError
+from docx.text.paragraph import _buffer_writes
 
 if TYPE_CHECKING:
     from collections.abc import Iterator, Sequence
@@ -186,6 +187,35 @@ def _coerce_timestamp(raw: object) -> datetime | None:
     return None
 
 
+def _word_date(raw: object) -> datetime | None:
+    """A comment's ``w:date`` as python-docx 1.2.0's ``Comment.timestamp``
+    reads it (``ST_DateTime.convert_from_xml``): with a trailing ``Z``, a time
+    in UTC; with an offset, a time in that zone; without either, a time in no
+    zone, as Word writes the author's local time; one it cannot parse, the
+    epoch in UTC. ``None`` for a comment with no ``w:date``."""
+    if not isinstance(raw, str):
+        return None
+
+    def parse(text: str) -> datetime:
+        if text.endswith("Z"):
+            try:
+                return datetime.strptime(text, "%Y-%m-%dT%H:%M:%S.%fZ").replace(tzinfo=timezone.utc)
+            except ValueError:
+                return datetime.strptime(text, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+        try:
+            return datetime.fromisoformat(text)
+        except ValueError:
+            try:
+                return datetime.strptime(text, "%Y-%m-%dT%H:%M:%S.%f")
+            except ValueError:
+                return datetime.strptime(text, "%Y-%m-%dT%H:%M:%S")
+
+    try:
+        return parse(raw)
+    except Exception:
+        return datetime(1970, 1, 1, tzinfo=timezone.utc)
+
+
 # docx-studio's caps (``MAX_COMMENT_AUTHOR_LENGTH`` /
 # ``MAX_COMMENT_INITIALS_LENGTH`` in apps/api/src/commands/types.ts), in
 # UTF-16 code units as the server counts them.
@@ -274,7 +304,7 @@ def _created_comment_info(
     }
     stored = result.get("comment") if isinstance(result, dict) else None
     if isinstance(stored, dict):
-        for key in ("creatorName", "initials", "createdTime"):
+        for key in ("creatorName", "initials", "createdTime", "wordDate"):
             if key in stored:
                 info[key] = stored[key]
     return info
@@ -291,6 +321,10 @@ class Comment(BlockItemContainer):
     ) -> None:
         self._session: "Session" = session
         self._info: dict = dict(info or {})
+        # The command buffer's ``writes`` count the info was read at: a later
+        # write (to the comment's paragraphs or runs, its replies' root, or
+        # anything the export writes it anew for) may change its ``w:date``.
+        self._dated_at: int | None = _buffer_writes(session)
 
     # ---- identity / metadata ----
     @property
@@ -336,6 +370,29 @@ class Comment(BlockItemContainer):
 
     @property
     def timestamp(self) -> datetime | None:
+        """The ``w:date`` docx-studio says the export writes for the comment
+        (``wordDate``), read as python-docx reads it: the source's own for a
+        comment no write changed, which Word writes in the author's local time
+        with no zone. A docx-studio that does not say gives the comment's
+        time in UTC (``createdTime``). After a write since the comment was
+        read (its text, a paragraph added to it, an edit of its paragraphs or
+        runs, or any other, which may make the export write it anew), it reads
+        the comment again; a read that fails is tried again at the next."""
+        if self._info.get("_wordDateStale") or _buffer_writes(self._session) != self._dated_at:
+            try:
+                fresh: object = run_sync(self._session.doc.comments.get({"id": self._id}))
+            except NotFoundError as exc:
+                if writes_unapplied(exc):
+                    raise
+                fresh = None
+            if isinstance(fresh, dict):
+                for key in ("wordDate", "createdTime"):
+                    if key in fresh:
+                        self._info[key] = fresh[key]
+            self._info.pop("_wordDateStale", None)
+            self._dated_at = _buffer_writes(self._session)
+        if "wordDate" in self._info:
+            return _word_date(self._info.get("wordDate"))
         return _coerce_timestamp(self._info.get("createdTime"))
 
     # ---- body ----
@@ -363,6 +420,8 @@ class Comment(BlockItemContainer):
 
         run_sync(self._session.doc.comments.patch({"id": self._id, "text": value}))
         self._info["text"] = value
+        # The export writes the comment anew, with the date its record holds.
+        self._info["_wordDateStale"] = True
         # CommentsPatch is a Command type — referenced for clarity / parity
         # with the bus dispatch path.
         del CommentsPatch
@@ -459,6 +518,8 @@ class Comment(BlockItemContainer):
         node_id = result.get("nodeId") if isinstance(result, dict) else None
         if not isinstance(node_id, str) or not node_id:
             raise CommentsNotImplementedError("Paragraphs added to comments")
+        # The export writes the comment anew, with the date its record holds.
+        self._info["_wordDateStale"] = True
         paragraph = Paragraph(session=self._session, node_id=node_id, node_type="paragraph", text_len=len(text))
         if style is not None:
             paragraph.style = style

{athena_python_docx-0.40.0 → athena_python_docx-0.41.0}/docx/text/paragraph.py

@@ -347,10 +347,24 @@ def _keep_link_address(run_data: dict, inline: dict) -> None:
     """Give a picture's run the address of the link it is in where its read
     sends one apart (``hyperlinkAddress``, for a target that holds a ``#`` of
     its own), as a text run's read holds it: :attr:`Hyperlink.address` reads
-    the whole target then, as python-docx does."""
+    the whole target then, as python-docx does; that it opens a link of its
+    own (``newLink``, :func:`_opens_link`); and that the link has no target
+    (``linkWithoutTarget``)."""
     address: object = inline.get("hyperlinkAddress")
     if isinstance(address, str):
         run_data["hyperlinkAddress"] = address
+    if inline.get("newLink") is True:
+        run_data["newLink"] = True
+    if inline.get("linkWithoutTarget") is True:
+        run_data["linkWithoutTarget"] = True
+
+
+def _opens_link(run_data: dict) -> bool:
+    """True for the first run of a link that follows another link to the same
+    target with nothing between them (``newLink``): two ``w:hyperlink``
+    elements side by side, which python-docx reads as two links. Without it,
+    runs of one target side by side are one link."""
+    return run_data.get("newLink") is True
 
 
 def _picture_run_data(inline: dict, drawing: dict) -> dict:
@@ -372,8 +386,9 @@ def _picture_run_data(inline: dict, drawing: dict) -> dict:
 
 def _rendered_page_break_reads(info: object) -> "list[tuple[dict, int]]":
     """Each rendered page break docx-studio reads in the runs of the paragraph
-    whose node info is `info` (``renderedPageBreaks``), its links' included, in
-    order, with its offset in the paragraph's text-address space."""
+    whose node info is `info` (``renderedPageBreaks``), its links' and its
+    fields' included, in order, with its offset in the paragraph's
+    text-address space."""
     if not isinstance(info, dict):
         return []
     node: object = info.get("node")
@@ -382,6 +397,16 @@ def _rendered_page_break_reads(info: object) -> "list[tuple[dict, int]]":
     reads: list[tuple[dict, int]] = []
     offset = 0
     for inline in inlines if isinstance(inlines, list) else []:
+        field_run: object = inline.get("fieldRun") if isinstance(inline, dict) else None
+        if isinstance(field_run, dict):
+            # A run of a field (its begin, code, separate, result or end run):
+            # it takes no room in the text-address space, and a break in it
+            # stands there.
+            field_breaks: object = field_run.get("renderedPageBreaks")
+            for brk in field_breaks if isinstance(field_breaks, list) else []:
+                if isinstance(brk, dict):
+                    reads.append((brk, offset))
+            continue
         run: object = inline.get("run") if isinstance(inline, dict) else None
         if not isinstance(run, dict):
             # A picture's run: its breaks stand before its drawing, and it holds no text.
@@ -1015,7 +1040,7 @@ class Paragraph:
             if isinstance(drawing, dict):
                 # A picture: python-docx's run holding a ``w:drawing``. It
                 # takes no room in the text-address space.
-                if self._extract_hyperlink_target(inline):
+                if self._extract_hyperlink_target(inline) is not None:
                     continue
                 run_obj = Run(
                     session=self._session,
@@ -1037,7 +1062,7 @@ class Paragraph:
                 start: int = offset
                 end: int = offset + len(text)
                 offset = end
-                if self._extract_hyperlink_target(run_data) or _deleted(run_data):
+                if self._extract_hyperlink_target(run_data) is not None or _deleted(run_data):
                     continue
                 run_obj = Run(
                     session=self._session,
@@ -1058,7 +1083,7 @@ class Paragraph:
                     start = offset
                     end = offset + len(text2)
                     offset = end
-                    if self._extract_hyperlink_target(inline):
+                    if self._extract_hyperlink_target(inline) is not None:
                         continue
                     runs.append(
                         Run(
@@ -1248,6 +1273,11 @@ class Paragraph:
             maybe = hl.get("url") or hl.get("target")
             if isinstance(maybe, str) and maybe:
                 return maybe
+        # A link with no target (``<w:hyperlink w:history="1">`` holding runs,
+        # with no ``r:id`` and no ``w:anchor``), which python-docx reads as a
+        # link whose address is "" (``linkWithoutTarget``).
+        if run_data.get("linkWithoutTarget") is True:
+            return ""
         return None
 
     @property
@@ -1304,7 +1334,7 @@ class Paragraph:
                 # room in the text-address space.
                 run_data = _picture_run_data(inline, drawing)
                 link = self._extract_hyperlink_target(inline)
-                if link:
+                if link is not None:
                     run_data["hyperlink"] = link
                     _keep_link_address(run_data, inline)
             elif isinstance(maybe_run, dict):
@@ -1373,7 +1403,7 @@ class Paragraph:
 
             # Hyperlinked run. Extend the current span if it shares a
             # target, otherwise close it and start a new one.
-            if current is not None and current[0] == target:
+            if current is not None and current[0] == target and not _opens_link(run_data):
                 current[1].append((run_data, (start, end)))
             else:
                 if current is not None:
@@ -1523,7 +1553,7 @@ class Paragraph:
                 # link when it carries one.
                 run_data = _picture_run_data(inline, drawing)
                 link = self._extract_hyperlink_target(inline)
-                if link:
+                if link is not None:
                     run_data["hyperlink"] = link
                     _keep_link_address(run_data, inline)
                 text = ""
@@ -1549,11 +1579,11 @@ class Paragraph:
                 offset += len(text)
                 continue
             target = self._extract_hyperlink_target(run_data)
-            if target:
+            if target is not None:
                 start = offset
                 offset += len(text)
                 segment = (run_data, (start, start + len(text)))
-                if current is not None and current[0] == target:
+                if current is not None and current[0] == target and not _opens_link(run_data):
                     current[1].append(segment)
                 else:
                     flushed = _flush_current()

{athena_python_docx-0.40.0 → athena_python_docx-0.41.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.40.0"
+version = "0.41.0"
 description = "Drop-in replacement for python-docx that connects to Athena's DOCX Studio collaborative document stack"
 readme = "README.md"
 license = "MIT"