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

{athena_python_docx-0.38.0 → athena_python_docx-0.39.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
@@ -1019,8 +1031,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 +1049,12 @@ 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 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 +1130,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,8 +1191,12 @@ 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`) 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
   (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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.38.0
+Version: 0.39.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.39.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.39.0"
 
 from docx.api import Document
 from docx._buffer import discard_all, flush_all

{athena_python_docx-0.38.0 → athena_python_docx-0.39.0}/docx/commands.py

@@ -797,6 +797,11 @@ class ImagesList(Command):
     # ``False`` leaves out each picture's ``src`` (a data URI can be MBs); an
     # older docx-studio ignores the field and sends ``src``.
     include_src: bool | None = None
+    # ``True`` also lists the copy of each picture in a text box that the
+    # box's VML fallback holds (a row with ``fallbackCopy``, under no id), as
+    # python-docx's ``inline_shapes`` lists it; an older docx-studio ignores
+    # the field and lists none.
+    fallback_copies: bool | None = None
 
 
 @dataclass

{athena_python_docx-0.38.0 → athena_python_docx-0.39.0}/docx/comments.py

@@ -289,9 +289,21 @@ class Comment(BlockItemContainer):
 
     # ---- identity / metadata ----
     @property
-    def comment_id(self) -> str:
-        cid = self._info.get("id") or self._info.get("commentId") or ""
-        return str(cid)
+    def _id(self) -> str:
+        """The id docx-studio addresses the comment by: its ``w:id``, as text."""
+        cid = self._info.get("id")
+        if cid is None or cid == "":
+            cid = self._info.get("commentId")
+        return "" if cid is None else str(cid)
+
+    @property
+    def comment_id(self) -> int:
+        """The comment's ``w:id``, an ``int`` as python-docx's
+        ``Comment.comment_id`` reads it (``ST_DecimalNumber``). docx-studio
+        reports it as text; an id that is not a number (no Word comment has
+        one) is returned as that text."""
+        cid = self._id
+        return int(cid) if re.fullmatch(r"-?\d+", cid) else cid  # type: ignore[return-value]
 
     @property
     def author(self) -> str:
@@ -330,7 +342,7 @@ class Comment(BlockItemContainer):
         with when docx-studio does not answer, or holds no record of it (a
         comment range listed without one, with empty text)."""
         try:
-            result: object = run_sync(self._session.doc.comments.get({"id": self.comment_id}))
+            result: object = run_sync(self._session.doc.comments.get({"id": self._id}))
         except NotFoundError as exc:
             if writes_unapplied(exc):
                 raise
@@ -344,7 +356,7 @@ class Comment(BlockItemContainer):
     def text(self, value: str) -> None:
         from docx.commands import CommentsPatch
 
-        run_sync(self._session.doc.comments.patch({"id": self.comment_id, "text": value}))
+        run_sync(self._session.doc.comments.patch({"id": self._id, "text": value}))
         self._info["text"] = value
         # CommentsPatch is a Command type — referenced for clarity / parity
         # with the bus dispatch path.
@@ -360,7 +372,7 @@ class Comment(BlockItemContainer):
         raw: object = run_sync(
             self._session.doc.blocks.list(
                 {
-                    "in": {"kind": "story", "storyType": "comment", "commentId": self.comment_id},
+                    "in": {"kind": "story", "storyType": "comment", "commentId": self._id},
                     "nodeTypes": ["paragraph"],
                     "includeText": True,
                     "includeRuns": True,
@@ -437,7 +449,7 @@ class Comment(BlockItemContainer):
             # unlike python-docx's in-memory tree).
             paragraph_style_id(self._session, style)
         result: object = run_sync(
-            self._session.doc.comments.paragraph_append({"id": self.comment_id, "text": text}),
+            self._session.doc.comments.paragraph_append({"id": self._id, "text": text}),
         )
         node_id = result.get("nodeId") if isinstance(result, dict) else None
         if not isinstance(node_id, str) or not node_id:

{athena_python_docx-0.38.0 → athena_python_docx-0.39.0}/docx/opc/coreprops.py

@@ -17,7 +17,11 @@ whatever its ``tzinfo``), ``revision`` only as a positive ``int``.
 
 docx-studio stamps ``modified`` with the time of a save that changes the
 package, a core property included, as Word does; a ``modified`` the script
-sets is kept instead. Every read asks docx-studio, so it sees that stamp, an
+sets is kept instead. A package 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), whose ``modified`` is the time
+of the session's first read, kept for later reads as python-docx keeps its
+part's, until a write gives the document a part of its own. Every read asks docx-studio, so it sees that stamp, an
 edit another collaborator saved, and a write queued before it (sent in the
 same batch, saved before the read answers).
 
@@ -93,23 +97,30 @@ class _Record:
     writes: bool
     #: What this process set, which is all there is when ``writes`` is False.
     texts: dict[str, str | None]
+    #: For a package without ``docProps/core.xml``: the ``modified`` of
+    #: python-docx's default part as this session first read it. python-docx
+    #: adds that part once, on first access, and keeps its time; docx-studio
+    #: reports it with each read's time (``corePropertiesDefault``).
+    default_modified: str | None = None
 
 
 _records: "weakref.WeakKeyDictionary[Any, _Record]" = weakref.WeakKeyDictionary()
 
 
-def _served_texts(session: Any) -> dict[str, str | None] | None:
+def _served_texts(session: Any) -> tuple[dict[str, str | None] | None, bool]:
     """The texts docx-studio reports (flushing the edits queued before), or
-    None from one that reports none."""
+    None from one that reports none; and whether they are python-docx's
+    default part, which a package without the part reads as
+    (``corePropertiesDefault``)."""
     info: object = run_sync(session.doc.info({"includeCoreProperties": True}))
     served = info.get("coreProperties") if isinstance(info, dict) else None
     if not isinstance(served, dict):
-        return None
+        return None, False
     texts: dict[str, str | None] = {}
     for name, wire in _WIRE_NAMES.items():
         text = served.get(wire)
         texts[name] = text if isinstance(text, str) else None
-    return texts
+    return texts, isinstance(info, dict) and info.get("corePropertiesDefault") is True
 
 
 def _known_record(session: Any) -> _Record | None:
@@ -134,14 +145,22 @@ def _texts(session: Any) -> dict[str, str | None]:
     record = _known_record(session)
     if record is not None and not record.writes:
         return record.texts
-    served = _served_texts(session)
+    served, default_part = _served_texts(session)
     if record is None:
         record = _remember(session, served)
-    return served if served is not None else record.texts
+    if served is None:
+        return record.texts
+    if not default_part:
+        record.default_modified = None
+        return served
+    # python-docx's default part keeps the time of its first access.
+    if record.default_modified is None:
+        record.default_modified = served["modified"]
+    return {**served, "modified": record.default_modified}
 
 
 def _write(session: Any, name: str, text: str) -> None:
-    record = _known_record(session) or _remember(session, _served_texts(session))
+    record = _known_record(session) or _remember(session, _served_texts(session)[0])
     if not record.writes:
         record.texts[name] = text
         warnings.warn(

{athena_python_docx-0.38.0 → athena_python_docx-0.39.0}/docx/section.py

@@ -96,6 +96,21 @@ def _extract_part_ref_id(response: object) -> str:
     return ""
 
 
+def _resolves_as_paragraph_style(session: object, style_id: str) -> bool:
+    """Whether a ``w:pStyle`` of ``style_id`` names a style of the session's
+    document: its first style of that id is a paragraph style (python-docx's
+    ``Styles.get_by_id``). Without a style table (an older docx-studio) the
+    reference is written as python-docx writes it."""
+    from docx.enum.style import WD_STYLE_TYPE
+    from docx.styles._table import first_of_id, style_table
+
+    table = style_table(session)
+    if table is None:
+        return True
+    record = first_of_id(table, style_id)
+    return record is not None and record.type == WD_STYLE_TYPE.PARAGRAPH
+
+
 def _remember_header_footer_paragraph(session: object, node_id: str) -> None:
     """Note a header/footer paragraph id on the session's HTTP client, so a
     ``block not found`` on it gets the header/footer hint, not the
@@ -893,15 +908,24 @@ class _HeaderFooter(BlockItemContainer):
         in the Header (or Footer) style. docx-studio stores an empty part with
         one empty paragraph (a part needs a block), which gets the style; a
         part that holds none gets the paragraph. A server that does not list
-        header/footer stories keeps its part as it stores it."""
+        header/footer stories keeps its part as it stores it.
+
+        python-docx's ``default-header.xml`` names the style by its id,
+        ``Header`` (``Footer``), whatever the document's styles are, and adds
+        no definition of it: in a document whose ``styles.xml`` has no
+        paragraph style of that id, the paragraph reads as the default
+        paragraph style (None without one). The paragraph then names no style,
+        which reads the same, and gives the export no reference to add Word's
+        definition for (``addReferencedBuiltInStyles``), so its ``styles.xml``
+        stays the document's, as python-docx's does."""
         listing = self._listing({"kind": "story", "storyType": "headerFooterPart", "refId": ref_id})
         if listing is None:
             return
         paragraphs = self._paragraphs_of(listing)
         first = paragraphs[0] if paragraphs else self._append_paragraph(ref_id, "")
-        # python-docx writes this style id whatever the document's styles are;
-        # docx-studio resolves it against them.
-        first._set_style_id("Header" if self._kind == "header" else "Footer")
+        style_id = "Header" if self._kind == "header" else "Footer"
+        if _resolves_as_paragraph_style(self._section._session, style_id):
+            first._set_style_id(style_id)
 
     def _append_paragraph(self, ref_id: str, text: str) -> "Paragraph":
         """Append a paragraph holding ``text`` to the part ``ref_id``."""

{athena_python_docx-0.38.0 → athena_python_docx-0.39.0}/docx/shape.py

@@ -113,15 +113,23 @@ class InlineShape:
         """``True`` (with a warning) for a shape docx-studio does not change
         through ``InlineShape``.
 
-        docx-studio writes a SmartArt drawing back as its source has it, and
-        holds a text box (a row with ``textBox``) as a text box, so a change of
-        its size, alt text, title or decorative flag is not sent and the shape
-        keeps reading what it has, where python-docx would change it.
+        docx-studio writes a SmartArt drawing back as its source has it, holds
+        a text box (a row with ``textBox``) as a text box, and writes the copy
+        of a text box's picture that the box's VML fallback holds (a row with
+        ``fallbackCopy``, which python-docx lists beside the picture itself)
+        from the box, so a change of its size, alt text, title or decorative
+        flag is not sent and the shape keeps reading what it has, where
+        python-docx would change it.
         """
         if self._info.get("kind") == "smartArt":
             held = "a SmartArt drawing, which docx-studio writes back as its source has it"
         elif self._info.get("textBox") is True:
             held = "a text box, which docx-studio holds as a text box"
+        elif self._info.get("fallbackCopy") is True:
+            held = (
+                "the copy of a text box's picture that its VML fallback holds,"
+                " which docx-studio writes from the box"
+            )
         else:
             return False
         from docx.errors import DocxUnsupportedCommandWarning
@@ -392,9 +400,15 @@ class InlineShapes:
     def __init__(self, *, session: "Session") -> None:
         self._session: "Session" = session
 
-    def _rows(self, *, include_src: bool = True) -> list[dict]:
-        """Every picture ``ImagesList`` names, a floating one too."""
-        params: dict = {} if include_src else {"includeSrc": False}
+    def _rows(self, *, include_src: bool = True, fallback_copies: bool = False) -> list[dict]:
+        """Every picture ``ImagesList`` names, a floating one too, and with
+        ``fallback_copies`` the copy of a text box's picture that the box's
+        VML fallback holds, which python-docx lists as an inline shape too."""
+        params: dict = {}
+        if not include_src:
+            params["includeSrc"] = False
+        if fallback_copies:
+            params["fallbackCopies"] = True
         info: object = run_sync(self._session.doc.images.list(params))
         if isinstance(info, dict):
             items: object = info.get("items") or info.get("images") or []
@@ -408,7 +422,8 @@ class InlineShapes:
         # python-docx lists the pictures in the line (``wp:inline``) only; a
         # floating one (``wp:anchor``) is not an inline shape. A docx-studio
         # that does not say which a picture is gives every one.
-        return [row for row in self._rows(include_src=include_src) if row.get("inline") is not False]
+        rows = self._rows(include_src=include_src, fallback_copies=True)
+        return [row for row in rows if row.get("inline") is not False]
 
     def __len__(self) -> int:
         return len(self._items())