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

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

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

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

@@ -568,14 +568,18 @@ 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.
-    Without it, the row is Word's Insert Row next to ``row_index``. A
-    docx-studio that predates the field ignores it."""
+    ``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.37.0 → athena_python_docx-0.38.0}/docx/table.py

@@ -1240,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.37.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
@@ -1240,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.
@@ -1521,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,
@@ -1882,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:
@@ -2005,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)
@@ -2019,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.37.0 → athena_python_docx-0.38.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.37.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.37.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.37.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.37.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 == ""

athena_python_docx-0.38.0/tests/test_run_break_inner_content.py

@@ -0,0 +1,254 @@
+"""A run holding only a page or column break, as ``Run.iter_inner_content()`` yields it.
+
+python-docx reads a ``<w:br w:type="page"/>`` or ``<w:br w:type="column"/>`` as
+text, an empty string, so a run holding one and no other text yields ``""``;
+an empty ``w:r`` (a comment reference's) yields nothing. docx-studio reads such
+a break's run as ``{"run": {"text": "", "break": "page"}}`` (or ``"column"``);
+an older one sends no ``break`` and the run yields nothing, as before.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+
+def _make_paragraph(inlines: list[dict]) -> Any:
+    from docx.client import Session
+    from docx.text.paragraph import Paragraph
+
+    session = MagicMock(spec=Session)
+    session.asset_id = "asset_fake"
+    session.is_open = True
+    session.doc = MagicMock()
+    session.doc.get_node_by_id = AsyncMock(
+        return_value={"node": {"paragraph": {"inlines": inlines}}}
+    )
+    return Paragraph(session=session, node_id="p1", node_type="paragraph")
+
+
+def _inner(paragraph: Any) -> list[list[Any]]:
+    return [list(run.iter_inner_content()) for run in paragraph.runs]
+
+
+def test_a_run_holding_only_a_page_or_column_break_yields_empty_text() -> None:
+    p = _make_paragraph(
+        [
+            {"run": {"text": "Before the breaks.", "bold": True}},
+            {"run": {"text": "", "break": "page"}},
+            {"run": {"text": "", "break": "column"}},
+            {"run": {"text": "After them.", "italic": True}},
+        ]
+    )
+
+    assert _inner(p) == [["Before the breaks."], [""], [""], ["After them."]]
+    assert [run.text for run in p.runs] == ["Before the breaks.", "", "", "After them."]
+
+
+def test_an_empty_run_yields_nothing() -> None:
+    # A comment reference's run, and a break's from a docx-studio that sends no ``break``.
+    p = _make_paragraph([{"run": {"text": "Commented."}}, {"run": {"text": ""}}])
+
+    assert _inner(p) == [["Commented."], []]
+
+
+def test_the_empty_run_a_page_or_column_break_is_added_to_yields_empty_text(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    from docx.enum.text import WD_BREAK
+    from docx.text.paragraph import Paragraph
+
+    fake_sd_methods.scripted_returns["info"] = {"capabilities": {"inlinePageBreak": True}}
+    paragraph = Paragraph(session=mock_session, node_id="p-1", text_len=0)
+    page = paragraph.add_run()
+    page.add_break(WD_BREAK.PAGE)
+    column = paragraph.add_run()
+    column.add_break(WD_BREAK.COLUMN)
+    empty = paragraph.add_run()
+
+    assert list(page.iter_inner_content()) == [""]
+    assert list(column.iter_inner_content()) == [""]
+    assert list(empty.iter_inner_content()) == []
+
+
+def _replaces(fake: Any) -> list[dict[str, Any]]:
+    return [params for op, params in fake.calls if op == "replace"]
+
+
+def test_clearing_a_run_holding_a_break_removes_it_and_its_proxy_forgets_it(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    # python-docx: run.clear() removes all of the run's content, its w:br too.
+    from docx.enum.text import WD_BREAK
+    from docx.text.paragraph import Paragraph
+
+    fake_sd_methods.scripted_returns["info"] = {
+        "capabilities": {"inlinePageBreak": True, "wholeRunBreaks": True}
+    }
+    paragraph = Paragraph(session=mock_session, node_id="p-1", text_len=0)
+    texted = paragraph.add_run("Hello")
+    texted.add_break(WD_BREAK.PAGE)
+    alone = paragraph.add_run()
+    alone.add_break(WD_BREAK.PAGE)
+
+    texted.clear()
+    alone.clear()
+
+    assert list(texted.iter_inner_content()) == []
+    assert list(alone.iter_inner_content()) == []
+    # Each run's content went with a wholeRun Replace, the empty run's at its place.
+    assert [(r["text"], r.get("wholeRun")) for r in _replaces(fake_sd_methods)] == [
+        ("", True),
+        ("", True),
+    ]
+
+
+def test_a_docx_studio_that_keeps_a_run_s_breaks_keeps_them_on_the_proxy(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    # Before `wholeRunBreaks`, a wholeRun Replace leaves a break at the run's edge.
+    from docx.enum.text import WD_BREAK
+    from docx.text.paragraph import Paragraph
+
+    fake_sd_methods.scripted_returns["info"] = {"capabilities": {"inlinePageBreak": True}}
+    paragraph = Paragraph(session=mock_session, node_id="p-1", text_len=0)
+    alone = paragraph.add_run()
+    alone.add_break(WD_BREAK.PAGE)
+
+    alone.clear()
+
+    assert list(alone.iter_inner_content()) == [""]
+    assert _replaces(fake_sd_methods) == []
+
+
+def _kinds(paragraph: Any) -> list[list[Any]]:
+    """Each run's inner content, a picture as ``"Drawing"``."""
+    from docx.drawing import Drawing
+
+    return [
+        ["Drawing" if isinstance(item, Drawing) else item for item in run.iter_inner_content()]
+        for run in paragraph.runs
+    ]
+
+
+def test_a_run_of_a_page_break_and_a_picture_yields_the_breaks_text_where_it_stands() -> None:
+    # `<w:r><w:br w:type="page"/><w:drawing/></w:r>`: python-docx 1.2.0 yields ["", Drawing];
+    # `<w:r><w:drawing/><w:br w:type="page"/></w:r>`: [Drawing, ""].
+    picture = {"offset": 0, "drawing": {"imageId": "p1:0:abc"}}
+    p = _make_paragraph(
+        [
+            {"run": {"text": "Before."}},
+            {"run": {"text": "", "break": "page", "pictures": [picture], "emptyTextAfterPictures": [0]}},
+            {"run": {"text": "", "break": "page", "pictures": [picture], "emptyTextAfterPictures": [1]}},
+        ]
+    )
+
+    assert _kinds(p) == [["Before."], ["", "Drawing"], ["Drawing", ""]]
+
+
+def test_a_break_on_each_side_of_a_picture_yields_empty_text_on_each_side() -> None:
+    # `<w:r><w:br w:type="page"/><w:drawing/><w:br w:type="page"/></w:r>`: python-docx 1.2.0
+    # yields ["", Drawing, ""].
+    picture = {"offset": 0, "drawing": {"imageId": "p1:0:abc"}}
+    p = _make_paragraph(
+        [{"run": {"text": "", "break": "page", "pictures": [picture], "emptyTextAfterPictures": [0, 1]}}]
+    )
+
+    assert _kinds(p) == [["", "Drawing", ""]]
+
+
+def test_text_then_a_picture_then_a_page_break_yields_the_breaks_text_after_the_picture() -> None:
+    # `<w:r><w:t>Logo</w:t><w:drawing/><w:br w:type="page"/></w:r>`: ["Logo", Drawing, ""].
+    picture = {"offset": 4, "drawing": {"imageId": "p1:0:abc"}}
+    p = _make_paragraph([{"run": {"text": "Logo", "pictures": [picture], "emptyTextAfterPictures": [1]}}])
+
+    assert _kinds(p) == [["Logo", "Drawing", ""]]
+
+
+def test_without_the_breaks_place_its_text_comes_before_the_pictures() -> None:
+    # A docx-studio before `emptyTextAfterPictures`: the break first, as a page that opens with the picture.
+    picture = {"offset": 0, "drawing": {"imageId": "p1:0:abc"}}
+    p = _make_paragraph([{"run": {"text": "", "break": "page", "pictures": [picture]}}])
+
+    assert _kinds(p) == [["", "Drawing"]]
+
+
+def test_a_run_of_text_and_a_picture_yields_no_empty_text() -> None:
+    picture = {"offset": 4, "drawing": {"imageId": "p1:0:abc"}}
+    p = _make_paragraph([{"run": {"text": "Logo", "pictures": [picture]}}])
+
+    assert _kinds(p) == [["Logo", "Drawing"]]
+
+
+PNG = bytes.fromhex(
+    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c489"
+    "0000000d4944415478da63f8ffff3f0005fe02fea7d6a4b60000000049454e44ae426082"
+)
+
+
+def _live_paragraph(mock_session: Any, fake_sd_methods: Any) -> Any:
+    from docx.text.paragraph import Paragraph
+
+    fake_sd_methods.scripted_returns["info"] = {
+        "capabilities": {"inlinePageBreak": True, "pictureRuns": True, "runIdentity": True}
+    }
+    fake_sd_methods.scripted_returns["create.image"] = {"nodeId": "p-1", "image": {"nodeId": "p-1:0:cc"}}
+    return Paragraph(session=mock_session, node_id="p-1", text_len=0)
+
+
+def _live_kinds(run: Any) -> list[Any]:
+    from docx.drawing import Drawing
+
+    return ["Drawing" if isinstance(item, Drawing) else item for item in run.iter_inner_content()]
+
+
+def test_the_run_add_break_then_add_picture_built_yields_the_breaks_text_first(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    # python-docx: `r = p.add_run(); r.add_break(PAGE); r.add_picture(png)` → ["", Drawing].
+    import io
+
+    from docx.enum.text import WD_BREAK
+
+    run = _live_paragraph(mock_session, fake_sd_methods).add_run()
+    run.add_break(WD_BREAK.PAGE)
+    run.add_picture(io.BytesIO(PNG))
+
+    assert _live_kinds(run) == ["", "Drawing"]
+
+
+def test_the_run_add_picture_then_add_break_built_yields_the_breaks_text_last(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    # python-docx: `r.add_picture(png); r.add_break(PAGE)` → [Drawing, ""]; one more picture, then
+    # a column break: [Drawing, "", Drawing, ""].
+    import io
+
+    from docx.enum.text import WD_BREAK
+
+    run = _live_paragraph(mock_session, fake_sd_methods).add_run()
+    run.add_picture(io.BytesIO(PNG))
+    run.add_break(WD_BREAK.PAGE)
+
+    assert _live_kinds(run) == ["Drawing", ""]
+
+    run.add_picture(io.BytesIO(PNG))
+    run.add_break(WD_BREAK.COLUMN)
+
+    assert _live_kinds(run) == ["Drawing", "", "Drawing", ""]
+
+
+def test_a_break_on_each_side_of_a_picture_added_to_the_run_yields_empty_text_on_each_side(
+    mock_session: Any, fake_sd_methods: Any
+) -> None:
+    import io
+
+    from docx.enum.text import WD_BREAK
+
+    run = _live_paragraph(mock_session, fake_sd_methods).add_run()
+    run.add_break(WD_BREAK.PAGE)
+    run.add_picture(io.BytesIO(PNG))
+    run.add_break(WD_BREAK.PAGE)
+
+    assert _live_kinds(run) == ["", "Drawing", ""]
+