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

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

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

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

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

@@ -565,10 +565,21 @@ class SetSectionLinkToPrevious(Command):
 
 @dataclass
 class TablesInsertRow(Command):
+    """``grid_row`` is python-docx's ``Table.add_row()``: the row goes after
+    the table's last one, with a cell for each grid column as wide as the
+    column, holding one empty paragraph, and nothing of the rows above.
+    ``copy_format_from`` is the Athena extension
+    ``Table.add_row(copy_format_from=k)``: the row goes after the table's
+    last one, formatted as Word's Insert Row below row ``k`` formats it.
+    Without either, the row is Word's Insert Row next to ``row_index``. A
+    docx-studio that predates a field ignores it."""
+
     node_id: str
     row_index: int
     position: str  # "above" | "below"
     count: int = 1
+    grid_row: bool | None = None
+    copy_format_from: int | None = None
 
 
 @dataclass

{athena_python_docx-0.36.0 → athena_python_docx-0.38.0}/docx/table.py

@@ -1053,6 +1053,11 @@ class Table:
         }
         if source_index is not None:
             params["copyFormatFrom"] = source_index
+        else:
+            # python-docx's row: a cell for each grid column, as wide as the
+            # column, and nothing of the last row (its height, grid skips,
+            # header flag or cell formatting).
+            params["gridRow"] = True
         run_sync(self._session.doc.tables.insert_row(params))
         # Keep the bounds-check cache current so the next ``cell()``
         # access still hits the fast path.
@@ -1235,7 +1240,13 @@ class Table:
             self._session.doc.tables.get_properties({"nodeId": self._fresh_node_id()}),
         )
         if isinstance(info, dict):
-            return WD_PARAGRAPH_ALIGNMENT.from_docx_studio(info.get("alignment"))
+            raw: object = info.get("alignment")
+            member = WD_PARAGRAPH_ALIGNMENT.from_docx_studio(raw)
+            # python-docx reads `w:jc` through `from_xml`, which raises
+            # ValueError for a value it has no member for (`start`, `end`).
+            if member is None and isinstance(raw, str) and raw:
+                return WD_PARAGRAPH_ALIGNMENT.from_xml(raw)
+            return member
         return None
 
     @alignment.setter

{athena_python_docx-0.36.0 → athena_python_docx-0.38.0}/docx/text/run.py

@@ -454,11 +454,16 @@ class Run:
         formatting, so the formatting waits for content the run takes. So
         does a break the read says is no node of the paragraph
         (``breakApart``): one only its source run holds, a column-break
-        block's, or the page break that opens the paragraph."""
+        block's, or the page break that opens the paragraph. The paragraph's
+        closing page break run (``closingBreak``) is formatted where the
+        docx-studio reports ``capabilities.closingBreakRunFormat``, which puts
+        its breaks back in the paragraph to take it."""
         if not self._is_collapsed_range or not self._holds_break() or tracking(self._session):
             return None
         if self._inline_snapshot.get("breakApart") is True:
-            return None
+            closing = self._inline_snapshot.get("closingBreak") is True
+            if not closing or not server_takes(self._session, "closingBreakRunFormat"):
+                return None
         if self._inline_snapshot.get("break") == "column" and not server_takes(self._session, "inlineColumnBreak"):
             return None
         return self._later_runs()
@@ -468,14 +473,23 @@ class Run:
         and no text (a picture's run, ``drawing``), which a whole-run
         ``FormatApply`` of its collapsed range formats, untracked, on a
         docx-studio that reports ``capabilities.pictureRuns``: python-docx
-        formats the run's ``w:r``, and docx-studio its picture. Else None."""
+        formats the run's ``w:r``, and docx-studio its picture. A legacy
+        picture's or object's run (``w:pict``, ``w:object``: ``drawing.legacy``
+        with its ``imageId``) too, on one that reports
+        ``capabilities.legacyPictureRuns``; not a preserved shape's (a
+        ``drawing.legacy`` with no ``imageId``), which no picture holds and the
+        format cannot reach. Else None."""
         if not self._is_collapsed_range or tracking(self._session):
             return None
         drawing = self._inline_snapshot.get("drawing")
-        if not isinstance(drawing, dict) or drawing.get("legacy") is True:
+        if not isinstance(drawing, dict):
             return None
         if not server_takes(self._session, "pictureRuns"):
             return None
+        if drawing.get("legacy") is True and (
+            not drawing.get("imageId") or not server_takes(self._session, "legacyPictureRuns")
+        ):
+            return None
         return self._later_runs()
 
     def _empty_run_identity(self) -> int | None:
@@ -866,6 +880,15 @@ class Run:
             items: list[tuple[int, float, dict, bool]] = [
                 (offset, index, info, True) for index, (offset, info) in enumerate(pictures)
             ]
+            # python-docx yields "" for each stretch of the run that the pictures
+            # bound and that holds a page or column break and no text, by how
+            # many pictures come before it (``emptyTextAfterPictures``). From a
+            # docx-studio that does not say, a run of a break and pictures and
+            # no text yields the break's "" before them.
+            empty_after = self._empty_text_after_pictures()
+            if empty_after is None:
+                breaks = not raw and self._inline_snapshot.get("break") in ("page", "column")
+                empty_after = {0} if breaks else set()
             rendered = self._rendered_page_breaks()
             for info in rendered:
                 offset = int(info.get("offset", 0) or 0)
@@ -875,15 +898,23 @@ class Run:
                 items.append((offset, after - 0.5, info, False))
             items.sort(key=lambda item: (item[0], item[1]))
             cut = 0
+            pictures_yielded = 0
             for offset, _order, info, is_picture in items:
                 at = min(max(offset, cut), len(raw))
                 if _word_text(raw[cut:at], font):
                     yield _word_text(raw[cut:at], font)
                 if not is_picture:
                     yield RenderedPageBreak(paragraph=self._page_break_paragraph(), offset=self._range[0] + at, info=info)
-                elif info.get("legacy") is not True:
-                    yield Drawing(session=self._session, info=info)
+                else:
+                    if pictures_yielded in empty_after:
+                        yield ""
+                        empty_after.discard(pictures_yielded)
+                    if info.get("legacy") is not True:
+                        yield Drawing(session=self._session, info=info)
+                    pictures_yielded += 1
                 cut = at
+            if pictures_yielded in empty_after:
+                yield ""
             if _word_text(raw[cut:], font):
                 yield _word_text(raw[cut:], font)
             return
@@ -1063,11 +1094,14 @@ class Run:
         # server keeps its own properties (``w:bCs``, an off toggle) for the
         # new text, as python-docx keeps the run's ``w:rPr``. A docx-studio
         # from before the field ignores it.
-        run_sync(
-            self._session.doc.replace(
-                {"target": self._text_range, "text": value, "wholeRun": True},
-            ),
-        )
+        command: dict = {"target": self._text_range, "text": value, "wholeRun": True}
+        later = later_runs_at_end(self)
+        if later and server_takes(self._session, "runIdentity"):
+            # A run after this one ends where it does (an empty run, a text
+            # box's or a SmartArt drawing's): docx-studio tells this run's
+            # record from its by the run's identity, and keeps both.
+            command["run"] = {"laterRuns": later}
+        run_sync(self._session.doc.replace(command))
         if not tracked:
             new_end: int = self._range[0] + len(value)
             self._range = (self._range[0], new_end)
@@ -1237,6 +1271,34 @@ class Run:
             snapshot.setdefault("break", kind)
             if held:
                 snapshot.pop("breakApart", None)
+            self._note_empty_text_after_pictures()
+
+    def _note_empty_text_after_pictures(self) -> None:
+        """This run took a page or column break at its end, after its pictures:
+        python-docx yields its ``""`` after the last of them while no text
+        follows it there (``emptyTextAfterPictures``). A picture's run
+        (``drawing``) holds its picture among its pictures (``pictures``) then."""
+        snapshot = self._inline_snapshot
+        alone = snapshot.get("drawing")
+        pictures = self._pictures() or ([(0, alone)] if isinstance(alone, dict) else [])
+        if not pictures or self._raw_text()[pictures[-1][0]:]:
+            return
+        if isinstance(alone, dict):
+            snapshot.pop("drawing")
+            snapshot["pictures"] = [{"offset": 0, "drawing": alone}]
+        places = snapshot.setdefault("emptyTextAfterPictures", [])
+        if isinstance(places, list) and len(pictures) not in places:
+            places.append(len(pictures))
+
+    def _empty_text_after_pictures(self) -> "set[int] | None":
+        """Where :meth:`iter_inner_content` yields ``""`` among this run's
+        pictures (``emptyTextAfterPictures``): each stretch the pictures bound
+        that holds a page or column break and no text, by how many pictures
+        come before it. None when the read does not say."""
+        places: object = self._inline_snapshot.get("emptyTextAfterPictures")
+        if not isinstance(places, list):
+            return None
+        return {p for p in places if isinstance(p, int) and not isinstance(p, bool)}
 
     def add_break(self, break_type: "WD_BREAK" = WD_BREAK.LINE) -> None:
         """Insert a break at the end of the run.
@@ -1518,17 +1580,25 @@ class Run:
     def _hold_picture(self, drawing: dict) -> None:
         """This run took the picture ``drawing`` at its end (``run.add_picture``),
         as the next read gives it: a run of a picture alone as a picture's run
-        (``drawing``), else among its pictures (``pictures``) where its text ends."""
+        (``drawing``), else among its pictures (``pictures``) where its text ends.
+        A run of a page or column break and no text holds it among its
+        pictures, after the break's ``""`` (``emptyTextAfterPictures``)."""
         snapshot = self._inline_snapshot
         held = self._pictures()
         alone = snapshot.get("drawing")
-        if not held and not self._raw_text() and not isinstance(alone, dict):
+        raw = self._raw_text()
+        break_first = not held and not raw and not isinstance(alone, dict) and snapshot.get("break") in ("page", "column")
+        if not held and not raw and not isinstance(alone, dict) and not break_first:
             snapshot["drawing"] = drawing
             return
         if isinstance(alone, dict):
             held = [(0, snapshot.pop("drawing"))]
-        held.append((len(self._raw_text()), drawing))
+        held.append((len(raw), drawing))
         snapshot["pictures"] = [{"offset": offset, "drawing": info} for offset, info in held]
+        if break_first:
+            places = snapshot.setdefault("emptyTextAfterPictures", [])
+            if isinstance(places, list) and 0 not in places:
+                places.append(0)
 
     @athena_extension(
         issue=498,
@@ -1879,15 +1949,19 @@ class Run:
 
     # ---- formatting helpers ----
     def _formatting_from_snapshot(self) -> dict:
-        """This run's formatting as a ``format.apply`` inline bag.
+        """This run's own formatting as a ``format.apply`` inline bag: the
+        values the run sets itself, an explicit off toggle (``w:b w:val="0"``)
+        included, as python-docx keeps the run's ``w:rPr`` for its next text.
 
         Only for a snapshot with every formatting key that is set
-        (``_marks_known``): a toggle that the snapshot does not hold is sent
-        as ``False``, so the new text does not take a toggle from the
-        paragraph's default run formatting either.
+        (``_marks_known``). A toggle the run does not set stays unset: the new
+        text, which docx-studio gives no formatting of its own (no
+        ``inheritMarks``), shows what the styles give it, as python-docx's
+        does. Sending it as ``False`` wrote an explicit off, so text written
+        into an emptied heading run lost the heading's bold.
         """
         snapshot = self._inline_snapshot
-        out: dict = {key: False for key in _RUN_MARK_TOGGLES}
+        out: dict = {}
         for key in _RUN_MARK_KEYS:
             value = snapshot.get(key)
             if value is not None:
@@ -2002,6 +2076,9 @@ class Run:
             )
             # Its break or picture holds the formatting now, which what it takes next continues.
             self._fresh = False
+            # A closing page break run's breaks are the paragraph's now, as the next read gives them.
+            if self._inline_snapshot.pop("closingBreak", None) is True:
+                self._inline_snapshot.pop("breakApart", None)
             return
         if self._is_collapsed_range:
             pending = getattr(self, "_pending_inline", None)
@@ -2016,17 +2093,23 @@ class Run:
                 {"target": self._text_range, "inline": kwargs, "wholeRun": True},
             ),
         )
-        self._edited_ruby()
+        self._edited_ruby(formatted=True)
 
-    def _edited_ruby(self) -> None:
+    def _edited_ruby(self, *, formatted: bool = False) -> None:
         """This run's text or formatting changed: docx-studio writes the base
         text of each ruby it held as text from then on (it keeps no guide
-        through an edit), so the run reads it as text. It writes the run's
-        symbol-block characters as a ``w:sym`` in the font the run owns too,
-        so a read's null ``symbolFont`` (a source ``w:t``'s characters) gives
-        way to the run's font (``_symbol_font``)."""
+        through an edit), so the run reads it as text. A docx-studio that
+        reports ``capabilities.rubyThroughFormat`` keeps the ruby through a
+        whole-run format (``formatted``), as python-docx keeps the run's
+        ``w:ruby``, so the run goes on reading it as the ruby's. It writes the
+        run's symbol-block characters as a ``w:sym`` in the font the run owns
+        too, so a read's null ``symbolFont`` (a source ``w:t``'s characters)
+        gives way to the run's font (``_symbol_font``)."""
         snapshot = getattr(self, "_inline_snapshot", {})
-        snapshot.pop("ruby", None)
+        if "ruby" in snapshot and not (
+            formatted and server_takes(getattr(self, "_session", None), "rubyThroughFormat")
+        ):
+            snapshot.pop("ruby", None)
         if "symbolFont" in snapshot and snapshot["symbolFont"] is None:
             snapshot.pop("symbolFont")
 

{athena_python_docx-0.36.0 → athena_python_docx-0.38.0}/pyproject.toml

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

{athena_python_docx-0.36.0 → athena_python_docx-0.38.0}/tests/test_drawing_image.py

@@ -466,6 +466,62 @@ class TestRunsHoldingPictures:
             assert formats == []
             assert picture_run._pending_inline == {"italic": True}
 
+    @pytest.mark.parametrize(("capability", "sent"), [(True, True), (False, False)])
+    def test_formatting_a_legacy_objects_run_formats_it_where_docx_studio_formats_them(
+        self, mock_session: Any, fake_sd_methods: Any, capability: bool, sent: bool
+    ) -> None:
+        """``p.runs[1].italic = True`` of an embedded object's run
+        (``<w:r><w:object>…</w:object></w:r>``, read as ``drawing.legacy``):
+        python-docx formats its ``w:r``. A docx-studio without
+        ``capabilities.legacyPictureRuns`` keeps the formatting for the text the
+        run takes, as before."""
+        fake_sd_methods.scripted_returns["info"] = {
+            "capabilities": {"pictureRuns": True, "legacyPictureRuns": capability, "runIdentity": True}
+        }
+        paragraph = _paragraph(
+            mock_session,
+            fake_sd_methods,
+            [{"run": {"text": "The figures "}}, {"drawing": {"imageId": "p1:0:aa", "legacy": True}}, {"run": {"text": " sit here."}}],
+        )
+        object_run = paragraph.runs[1]
+
+        object_run.italic = True
+
+        formats = [params for op, params in fake_sd_methods.calls if op == "format.apply"]
+        if sent:
+            assert formats == [
+                {
+                    "target": {"kind": "text", "blockId": "p1", "range": {"start": 12, "end": 12}},
+                    "inline": {"italic": True},
+                    "wholeRun": True,
+                    "run": {"laterRuns": 0},
+                }
+            ]
+        else:
+            assert formats == []
+            assert object_run._pending_inline == {"italic": True}
+
+    def test_formatting_a_preserved_shapes_run_stays_pending(self, mock_session: Any, fake_sd_methods: Any) -> None:
+        """A shape docx-studio keeps as it was (``mc:AlternateContent``) reads
+        as ``drawing.legacy`` with no ``imageId``: no picture holds it, so a
+        format of its run would reply ``formatted: false``. Its formatting stays
+        pending, as before, also on a docx-studio that reports
+        ``legacyPictureRuns``."""
+        fake_sd_methods.scripted_returns["info"] = {
+            "capabilities": {"pictureRuns": True, "legacyPictureRuns": True, "runIdentity": True}
+        }
+        paragraph = _paragraph(
+            mock_session,
+            fake_sd_methods,
+            [{"run": {"text": "Before "}}, {"drawing": {"imageId": None, "legacy": True}}, {"run": {"text": " after"}}],
+        )
+        shape_run = paragraph.runs[1]
+
+        shape_run.italic = True
+
+        assert [params for op, params in fake_sd_methods.calls if op == "format.apply"] == []
+        assert shape_run._pending_inline == {"italic": True}
+
     def test_a_pictures_run_reads_its_formatting(self, mock_session: Any, fake_sd_methods: Any) -> None:
         """python-docx reads a picture's run's ``w:rPr``: docx-studio reads its
         formatting on the picture's inline beside its drawing."""

{athena_python_docx-0.36.0 → athena_python_docx-0.38.0}/tests/test_enum_parity.py

@@ -386,6 +386,20 @@ def test_getters_return_int_members(mock_session: Any, fake_sd_methods: Any) ->
     assert table.table_direction is True and table.table_direction == WD_TABLE_DIRECTION.RTL
 
 
+@pytest.mark.parametrize("jc", ["start", "end"])
+def test_a_table_of_start_or_end_justification_raises_as_python_docx_reads_it(
+    mock_session: Any, fake_sd_methods: Any, jc: str
+) -> None:
+    """python-docx 1.2.0 reads a table's ``w:jc`` through the paragraph
+    ``CT_Jc``, whose enum has no member for ``start`` or ``end``."""
+    from docx.table import Table
+
+    fake_sd_methods.scripted_returns["tables.get_properties"] = {"alignment": jc}
+    table = Table(session=mock_session, node_id="tbl-1")
+    with pytest.raises(ValueError, match=f"WD_PARAGRAPH_ALIGNMENT has no XML mapping for '{jc}'"):
+        _ = table.alignment
+
+
 @pytest.mark.parametrize(
     "assign",
     [

{athena_python_docx-0.36.0 → athena_python_docx-0.38.0}/tests/test_ruby_reads_python_docx_parity.py

@@ -13,8 +13,10 @@ is installed.
 
 docx-studio keeps the base text in its run's text, the room it takes in the
 text-address space, and gives its spans as ``ruby``: edits addressed after the
-ruby land after it. Once the run's text or formatting changes, docx-studio
-writes the base text as text, and the run reads it so.
+ruby land after it. Once the run's text changes, docx-studio writes the base
+text as text, and the run reads it so; so does a format of the run, but on a
+docx-studio that reports ``rubyThroughFormat``, which keeps the ruby through it
+as python-docx does.
 """
 
 from __future__ import annotations
@@ -190,3 +192,17 @@ def test_an_edit_of_the_rubys_run_reads_its_base_text_as_text(
 
     assert _writes(fake_sd_methods)
     assert "ruby" not in ruby._inline_snapshot
+
+
+def test_a_format_of_the_rubys_run_keeps_its_ruby_where_docx_studio_keeps_it(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    # A docx-studio that reports `rubyThroughFormat` keeps the run's `w:ruby`
+    # through a whole-run format, as python-docx keeps it: the run still reads "".
+    fake_sd_methods.scripted_returns["info"] = {"capabilities": {"rubyThroughFormat": True}}
+    ruby = _body(mock_session, fake_sd_methods).runs[1]
+
+    ruby.bold = True
+
+    assert ruby._inline_snapshot.get("ruby") == [[0, 1]]
+    assert ruby.text == ""