athena-python-docx 0.32.0__tar.gz → 0.33.0__tar.gz

{athena_python_docx-0.32.0 → athena_python_docx-0.33.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.32.0
+Version: 0.33.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.32.0 → athena_python_docx-0.33.0}/docx/__init__.py

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

{athena_python_docx-0.32.0 → athena_python_docx-0.33.0}/docx/text/hyperlink.py

@@ -171,13 +171,16 @@ class Hyperlink:
 
     @property
     def contains_page_break(self) -> bool:
-        """True when the text of this hyperlink contains a hard page break.
+        """True when a rendered page break (a page Word's last layout began)
+        occurs in one of the hyperlink's runs, as python-docx 1.x reads it.
 
-        Mirrors python-docx 1.x. Detection uses DOCX Studio's ``\\f`` form-
-        feed sentinel inside any wrapped run's text (matching
-        ``Run.contains_page_break`` / ``Paragraph.contains_page_break``).
+        docx-studio reads them in the runs (``renderedPageBreaks``); the
+        ``\\f`` sentinel is an older docx-studio's mark.
         """
         for run_data, _ in self._segments:
+            breaks = run_data.get("renderedPageBreaks")
+            if isinstance(breaks, list) and any(isinstance(brk, dict) for brk in breaks):
+                return True
             text = run_data.get("text", "")
             if isinstance(text, str) and "\f" in text:
                 return True

{athena_python_docx-0.32.0 → athena_python_docx-0.33.0}/docx/text/pagebreak.py

@@ -53,15 +53,45 @@ def _warn_pagebreak_fragment(prop: str) -> None:
     )
 
 
+class _ParagraphFragment:
+    """The part of a paragraph before or after one of its rendered page breaks.
+
+    python-docx returns a ``Paragraph`` divorced from the document body: a
+    copy of the paragraph cut at the break, whose changes the document never
+    sees. This one reads what text extraction asks of it, its ``text`` and
+    ``style``, and changes nothing.
+    """
+
+    __slots__ = ("_paragraph", "_text")
+
+    def __init__(self, *, paragraph: "Paragraph", text: str) -> None:
+        self._paragraph = paragraph
+        self._text = text
+
+    @property
+    def text(self) -> str:
+        """The fragment's text, as ``Paragraph.text`` reads it."""
+        return self._text
+
+    @property
+    def style(self):
+        """The paragraph's style: the fragment keeps the paragraph's properties."""
+        return self._paragraph.style
+
+    def __repr__(self) -> str:
+        return f"<_ParagraphFragment text={self._text!r}>"
+
+
 class RenderedPageBreak:
-    """A hard page break inside a paragraph, as Word would render it.
+    """A page break Word's last layout put in a paragraph (``w:lastRenderedPageBreak``).
 
-    Constructed by :meth:`Paragraph.rendered_page_breaks` and yielded
-    by :meth:`Paragraph.iter_inner_content`; not intended for direct
-    user instantiation.
+    Constructed by :meth:`Paragraph.rendered_page_breaks` and yielded by
+    :meth:`Run.iter_inner_content`; not intended for direct user
+    instantiation. ``info`` is the break as docx-studio reads it in its run
+    (``renderedPageBreaks``): its fragments' text, or no fragment.
     """
 
-    __slots__ = ("_paragraph", "_offset", "_preceding_text")
+    __slots__ = ("_paragraph", "_offset", "_preceding_text", "_info")
 
     def __init__(
         self,
@@ -69,30 +99,47 @@ class RenderedPageBreak:
         paragraph: "Paragraph",
         offset: int = 0,
         preceding_text: str = "",
+        info: "dict | None" = None,
     ) -> None:
         self._paragraph: "Paragraph" = paragraph
         self._offset: int = offset
         self._preceding_text: str = preceding_text
+        self._info: "dict | None" = info
+
+    def _fragment(self, side: str) -> "_ParagraphFragment | None":
+        """python-docx's fragment on `side` (``preceding``/``following``) of this break."""
+        info = self._info
+        if info is None:
+            _warn_pagebreak_fragment(f"{side}_paragraph_fragment")
+            return None
+        if side not in info:
+            raise ValueError("only defined on first rendered page-break in paragraph")
+        text = info[side]
+        return (
+            None if text is None else _ParagraphFragment(paragraph=self._paragraph, text=str(text))
+        )
 
     # ---- python-docx canonical surface ----
     @property
-    def preceding_paragraph_fragment(self) -> "Paragraph | None":
-        """The portion of the paragraph that flowed onto the page
-        *before* the break.
+    def preceding_paragraph_fragment(self) -> "_ParagraphFragment | None":
+        """The part of the paragraph before this break, as a paragraph.
 
-        DOCX Studio's flat model doesn't preserve mid-paragraph fragments;
-        returns ``None``. Use :attr:`preceding_paragraph_text` for the
-        plain-text equivalent or the parent paragraph for full text.
+        None when no content precedes it (the break precedes all of the
+        paragraph's content). A break in a hyperlink puts the whole hyperlink
+        in this fragment. Raises ``ValueError`` for a break that is not the
+        paragraph's first, as python-docx does.
         """
-        _warn_pagebreak_fragment("preceding_paragraph_fragment")
-        return None
+        return self._fragment("preceding")
 
     @property
-    def following_paragraph_fragment(self) -> "Paragraph | None":
-        """The portion of the paragraph that flowed onto the page
-        *after* the break. See :attr:`preceding_paragraph_fragment`."""
-        _warn_pagebreak_fragment("following_paragraph_fragment")
-        return None
+    def following_paragraph_fragment(self) -> "_ParagraphFragment | None":
+        """The part of the paragraph after this break, as a paragraph.
+
+        None when no content follows it. A break in a hyperlink leaves the
+        whole hyperlink out of this fragment. Raises ``ValueError`` for a
+        break that is not the paragraph's first, as python-docx does.
+        """
+        return self._fragment("following")
 
     # ---- athena-specific extensions (kept for compat) ----
     @property

{athena_python_docx-0.32.0 → athena_python_docx-0.33.0}/docx/text/paragraph.py

@@ -242,6 +242,30 @@ def _node_text(session: "Session", node_id: str, *, final: bool = False) -> str:
     return _extract_text(info, final=final)
 
 
+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."""
+    if not isinstance(info, dict):
+        return []
+    node: object = info.get("node")
+    block: object = (node.get("paragraph") or node.get("heading")) if isinstance(node, dict) else None
+    inlines: object = block.get("inlines") if isinstance(block, dict) else None
+    reads: list[tuple[dict, int]] = []
+    offset = 0
+    for inline in inlines if isinstance(inlines, list) else []:
+        run: object = inline.get("run") if isinstance(inline, dict) else None
+        if not isinstance(run, dict):
+            continue
+        breaks: object = run.get("renderedPageBreaks")
+        for brk in breaks if isinstance(breaks, list) else []:
+            if isinstance(brk, dict):
+                reads.append((brk, offset + int(brk.get("offset", 0) or 0)))
+        text: object = run.get("text")
+        offset += len(text) if isinstance(text, str) else 0
+    return reads
+
+
 def _extract_text(info: object, *, final: bool = False) -> str:
     """Concatenate the text content of a paragraph, mirroring
     python-docx ``Paragraph.text`` semantics:
@@ -1129,22 +1153,28 @@ class Paragraph:
 
     @property
     def contains_page_break(self) -> bool:
-        """python-docx 1.x: True if the paragraph contains a hard page break."""
-        return "\f" in self.text
+        """python-docx 1.x: True when a rendered page break (a page Word's last
+        layout began) occurs in one of the paragraph's runs or its links' runs."""
+        info = self._node_info()
+        return bool(_rendered_page_break_reads(info)) or "\f" in _extract_text(info, final=True)
 
     @property
     def rendered_page_breaks(self) -> "list[RenderedPageBreak]":
-        """Return a list of :class:`RenderedPageBreak` proxies for each
-        hard page break in this paragraph.
-
-        python-docx 1.x exposes this for inspecting Word's rendered
-        page-break positions inside a paragraph. We surface a minimal
-        proxy with a ``preceding_paragraph_text`` property so the
-        common ``len(p.rendered_page_breaks)`` pattern works. The
-        underlying break is detected via the ``\\f`` sentinel in the
-        paragraph text.
+        """python-docx 1.x: a :class:`RenderedPageBreak` for each page Word's
+        last layout began in the paragraph's runs and its links' runs
+        (``w:lastRenderedPageBreak``), in document order.
+
+        Each reads python-docx's fragments: the part of the paragraph before
+        and after the break (``preceding_paragraph_fragment``,
+        ``following_paragraph_fragment``), defined on the first break only.
+        A paragraph from an older docx-studio marks its breaks with the
+        ``\\f`` sentinel in its text instead.
         """
-        text = _extract_text(self._node_info())
+        node_info = self._node_info()
+        reads = _rendered_page_break_reads(node_info)
+        if reads:
+            return [RenderedPageBreak(paragraph=self, offset=offset, info=info) for info, offset in reads]
+        text = _extract_text(node_info)
         if "\f" not in text:
             return []
         out: list[RenderedPageBreak] = []

{athena_python_docx-0.32.0 → athena_python_docx-0.33.0}/docx/text/run.py

@@ -48,11 +48,26 @@ _RUN_MARK_TOGGLES: tuple[str, ...] = (
     "outline",
     "rtl",
 )
+# The on/off properties a read reports that no mark holds: ``w:bCs``, ``w:iCs``,
+# ``w:cs``, ``w:noProof``, ``w:snapToGrid``, ``w:webHidden``, ``w:specVanish``
+# and ``w:oMath`` (``math``), which docx-studio keeps among the run's own
+# properties. An older docx-studio reports none of them.
+_RUN_UNMODELED_TOGGLES: tuple[str, ...] = (
+    "bCs",
+    "iCs",
+    "cs",
+    "noProof",
+    "snapToGrid",
+    "webHidden",
+    "specVanish",
+    "math",
+)
 # Every formatting key of such a read: the toggles, and the value keys
 # (``fontSize`` in points, ``vertAlign``, the character style id ``rStyle``).
 _RUN_MARK_KEYS: frozenset[str] = frozenset(
     (
         *_RUN_MARK_TOGGLES,
+        *_RUN_UNMODELED_TOGGLES,
         "color",
         "themeColor",
         "highlight",
@@ -735,6 +750,37 @@ class Run:
             return
         text = _without_ruby(self._raw_text(), self._inline_snapshot)
         font = self._symbol_font() if _SYMBOL_CHARACTERS.search(text) else None
+        rendered = self._rendered_page_breaks()
+        if rendered and "\f" not in text:
+            # Word's rendered page breaks stand between the run's text, each where
+            # docx-studio reads it: python-docx yields the text before it, the
+            # break, then the text after. A page or column break holding no text
+            # reads as "" before them, as the page it begins starts after it.
+            from docx.text.paragraph import Paragraph
+
+            if not text and self._inline_snapshot.get("break") in ("page", "column"):
+                yield ""
+            paragraph = getattr(self, "_paragraph", None) or Paragraph(session=self._session, node_id=self._block_id)
+            # The offsets count the run's text with its ruby base text, which
+            # each piece leaves out after it is cut.
+            raw = self._raw_text()
+            spans = self._inline_snapshot.get("ruby")
+            ruby = [s for s in spans if isinstance(s, list) and len(s) == 2] if isinstance(spans, list) else []
+
+            def piece(start: int, end: int) -> str:
+                inside = [[a - start, b - start] for a, b in ruby if isinstance(a, int) and isinstance(b, int) and a >= start and b <= end]
+                return _word_text(_without_ruby(raw[start:end], {"ruby": inside}), font)
+
+            cut = 0
+            for info in rendered:
+                at = min(max(int(info.get("offset", 0) or 0), cut), len(raw))
+                if piece(cut, at):
+                    yield piece(cut, at)
+                yield RenderedPageBreak(paragraph=paragraph, offset=self._range[0] + at, info=info)
+                cut = at
+            if piece(cut, len(raw)):
+                yield piece(cut, len(raw))
+            return
         # Fast path — no page breaks, yield the whole run as one string.
         if "\f" not in text:
             if _word_text(text, font):
@@ -785,6 +831,8 @@ class Run:
                 f"{value!r}",
             )
         if self._field_part() is not None:
+            # python-docx replaces all of the run's content, its rendered page breaks too.
+            self._inline_snapshot.pop("renderedPageBreaks", None)
             self._set_field_text(value)
             return
         if self._check_cell_inner("text"):
@@ -792,6 +840,7 @@ class Run:
             # (when present) still reflects reality — keep it.
             return
         self._fastpath_text = None  # type: ignore[attr-defined]
+        self._inline_snapshot.pop("renderedPageBreaks", None)
         drawing = self._inline_snapshot.get("drawing")
         picture = drawing.get("imageId") if isinstance(drawing, dict) else None
         if isinstance(picture, str) and picture:
@@ -961,14 +1010,19 @@ class Run:
 
     @property
     def contains_page_break(self) -> bool:
-        """python-docx 1.x: True if the run contains a hard page break.
+        """python-docx 1.x: True when a rendered page break (a page Word's last
+        layout began, ``w:lastRenderedPageBreak``) occurs in this run.
 
-        A run contains a page break iff its text segment includes the
-        Form Feed sentinel ``\\f`` — that's how DOCX Studio marks a hard
-        page break inside an inline run, mirroring Word's `<w:br
-        w:type="page"/>`.
+        An author's hard page break (``w:br w:type="page"``) is not one, as in
+        python-docx. docx-studio reads them in the run (``renderedPageBreaks``);
+        the ``\\f`` sentinel is an older docx-studio's mark.
         """
-        return "\f" in self.text
+        return bool(self._rendered_page_breaks()) or "\f" in self.text
+
+    def _rendered_page_breaks(self) -> "list[dict]":
+        """The rendered page breaks docx-studio reads in this run, in order (``renderedPageBreaks``)."""
+        breaks = self._inline_snapshot.get("renderedPageBreaks")
+        return [info for info in breaks if isinstance(info, dict)] if isinstance(breaks, list) else []
 
     def _continues_own_formatting(self) -> bool:
         """True when content appended to this run takes its formatting from

{athena_python_docx-0.32.0 → athena_python_docx-0.33.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.32.0"
+version = "0.33.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.32.0 → athena_python_docx-0.33.0}/tests/fixtures/field_reads.json

@@ -52,6 +52,7 @@
           "fieldRun": {
             "text": "1",
             "part": "result",
+            "noProof": true,
             "instruction": "SEQ Figure \\* ARABIC",
             "fieldIndex": 0
           }

{athena_python_docx-0.32.0 → athena_python_docx-0.33.0}/tests/live/baseline.json

@@ -270,19 +270,8 @@
   "rw20_header_table_merges"
  ],
  "gaps": [
-  "38_font_all_properties::export::runs.font.snap_to_grid",
-  "38_font_all_properties::reads::runs.font.snap_to_grid",
   "abp46_comment_rich_text::export::comments.ids",
   "abp46_comment_rich_text::reads::comments.ids",
-  "ex07_every_font_boolean::export::runs.font.complex_script",
-  "ex07_every_font_boolean::export::runs.font.cs_bold",
-  "ex07_every_font_boolean::export::runs.font.cs_italic",
-  "ex07_every_font_boolean::export::runs.font.snap_to_grid",
-  "ex07_every_font_boolean::reads::runs.font.complex_script",
-  "ex07_every_font_boolean::reads::runs.font.cs_bold",
-  "ex07_every_font_boolean::reads::runs.font.cs_italic",
-  "ex07_every_font_boolean::reads::runs.font.snap_to_grid",
-  "fixture-bidi-rtl::reads::runs.font.cs_bold",
   "fixture-bidi-wrappers::reads::hyperlinks",
   "fixture-bidi-wrappers::reads::hyperlinks.runs",
   "fixture-bidi-wrappers::reads::paragraphs.inner_content",
@@ -327,12 +316,7 @@
   "fixture-comments-links::reads::comments.ids",
   "fixture-comments-point::reads::comments.ids",
   "fixture-comments-replies::reads::comments.ids",
-  "fixture-fields-ref-seq-toc::reads::runs.font.no_proof",
-  "fixture-fields-toc-entries::reads::hyperlinks.runs",
-  "fixture-form-fields::reads::runs.font.no_proof",
   "fixture-hyperlinks-empty-comment-drawing::reads::comments.ids",
-  "fixture-index-captions::reads::hyperlinks.runs",
-  "fixture-index-captions::reads::runs.font.no_proof",
   "fixture-inline-tags::reads::hyperlinks",
   "fixture-inline-tags::reads::hyperlinks.runs",
   "fixture-inline-tags::reads::paragraphs.inner_content",
@@ -373,17 +357,7 @@
   "fixture-inline-tags::reads::sections.inner_content",
   "fixture-inline-tags::reads::tables.cell_format",
   "fixture-inline-tags::reads::tables.cell_paragraph_content",
-  "fixture-inline-tags::reads::tables.cells",
-  "fixture-notes-fields-bookmarks::reads::runs.font.no_proof",
-  "fixture-permissions-proofing::reads::paragraphs.contains_page_break",
-  "fixture-permissions-proofing::reads::paragraphs.rendered_page_breaks",
-  "fixture-permissions-proofing::reads::runs.contains_page_break",
-  "fixture-permissions-proofing::reads::runs.inner_content",
-  "fixture-run-properties-unmodeled::reads::runs.font.snap_to_grid",
-  "fixture-smartart-diagram::reads::runs.font.no_proof",
-  "fixture-smartart-diagram::reads::runs.inner_content",
-  "fixture-text-effects-w14::reads::runs.font.no_proof",
-  "fixture-textbox-page-break::reads::runs.font.no_proof"
+  "fixture-inline-tags::reads::tables.cells"
  ],
  "reasons": [
   {
@@ -393,43 +367,11 @@
    ],
    "reason": "Owner question 47 (open): runs inside an inline wrapper (w:dir, w:bdo, w:smartTag, w:customXml) read as the paragraph's runs, where python-docx reads only a w:p's direct w:r and w:hyperlink children, so the runs, their fonts and inner content, the links' runs, the paragraph's text and inner content, and the cells holding them read with the wrapped runs."
   },
-  {
-   "match": [
-    "*::*::runs.font.no_proof",
-    "*::*::runs.font.snap_to_grid",
-    "*::*::runs.font.cs_bold",
-    "*::*::runs.font.cs_italic",
-    "*::*::runs.font.complex_script"
-   ],
-   "reason": "R4 (to fix): a run's w:noProof, w:snapToGrid, w:bCs, w:iCs and w:cs are carried by no model mark, so Font.no_proof, snap_to_grid, cs_bold, cs_italic and complex_script read None, and setting snap_to_grid, cs_bold, cs_italic or complex_script does not reach the export."
-  },
-  {
-   "match": [
-    "fixture-permissions-proofing::reads::paragraphs.contains_page_break",
-    "fixture-permissions-proofing::reads::paragraphs.rendered_page_breaks",
-    "fixture-permissions-proofing::reads::runs.contains_page_break",
-    "fixture-permissions-proofing::reads::runs.inner_content"
-   ],
-   "reason": "R5 (to fix): w:lastRenderedPageBreak is neither kept nor read, so contains_page_break, rendered_page_breaks and a run's inner content leave out the page break Word last laid out there."
-  },
   {
    "match": [
     "*::*::comments.ids"
    ],
    "reason": "R6 (to fix): Comment.comment_id returns a str where python-docx returns an int, and the first comment a script adds is numbered 1 where python-docx numbers it 0."
-  },
-  {
-   "match": [
-    "fixture-smartart-diagram::reads::runs.inner_content"
-   ],
-   "reason": "R11 (to fix): a SmartArt drawing is left out of its run's inner content: the import moves the diagram into text boxes after the paragraph, and the run's record keeps no trace of the drawing for the read to yield a Drawing (has_picture False) from."
-  },
-  {
-   "match": [
-    "fixture-fields-toc-entries::reads::hyperlinks.runs",
-    "fixture-index-captions::reads::hyperlinks.runs"
-   ],
-   "reason": "R13 (to fix): a link's runs read no w:webHidden (the tab and page number runs Word writes in a table of contents or a table of figures entry), where python-docx reads web_hidden True; index-captions' entry runs also read no w:noProof (R4)."
   }
  ]
 }

athena_python_docx-0.33.0/tests/test_rendered_page_breaks.py

@@ -0,0 +1,196 @@
+"""Rendered page breaks (``w:lastRenderedPageBreak``) as python-docx 1.2.0 reads them.
+
+docx-studio reads each one in its run (``renderedPageBreaks``): its place in
+the run's text, and the text of python-docx's fragments around the
+paragraph's first break (``preceding`` / ``following``, null for no fragment,
+absent for a break python-docx raises for). ``Run.contains_page_break`` and
+``Run.iter_inner_content`` read them in the run, and
+``Paragraph.rendered_page_breaks`` in the paragraph's runs and its links' runs.
+An author's hard page break is not one.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+
+@pytest.fixture
+def paragraph_of(mock_session: Any, fake_sd_methods: Any) -> Any:
+    """A paragraph whose read (``get_node_by_id``) holds `inlines`."""
+    from docx.text.paragraph import Paragraph
+
+    def make(inlines: list[dict[str, Any]]) -> Any:
+        text = "".join(inline.get("run", {}).get("text", "") for inline in inlines)
+        fake_sd_methods.scripted_returns["get_node_by_id"] = {
+            "node": {
+                "nodeId": "p-1",
+                "nodeType": "paragraph",
+                "text": text,
+                "paragraph": {"inlines": inlines, "runMarks": True},
+            }
+        }
+        return Paragraph(session=mock_session, node_id="p-1", text_len=len(text))
+
+    return make
+
+
+def _kinds(items: list[Any]) -> list[Any]:
+    return [item if isinstance(item, str) else type(item).__name__ for item in items]
+
+
+FIRST = {"offset": 0, "preceding": "Before, ", "following": "after the break"}
+
+
+def test_a_run_starting_on_a_new_page_yields_the_break_then_its_text(paragraph_of: Any) -> None:
+    paragraph = paragraph_of(
+        [
+            {"run": {"text": "Before, "}},
+            {"run": {"text": "after the break", "renderedPageBreaks": [FIRST]}},
+        ],
+    )
+
+    runs = paragraph.runs
+
+    assert [run.contains_page_break for run in runs] == [False, True]
+    assert _kinds(list(runs[0].iter_inner_content())) == ["Before, "]
+    assert _kinds(list(runs[1].iter_inner_content())) == ["RenderedPageBreak", "after the break"]
+    assert runs[1].text == "after the break"
+
+
+def test_a_break_inside_a_run_yields_its_text_on_each_side(paragraph_of: Any) -> None:
+    paragraph = paragraph_of(
+        [
+            {
+                "run": {
+                    "text": "abcdef",
+                    "renderedPageBreaks": [{"offset": 3, "preceding": "abc", "following": "def"}],
+                }
+            }
+        ],
+    )
+
+    assert _kinds(list(paragraph.runs[0].iter_inner_content())) == [
+        "abc",
+        "RenderedPageBreak",
+        "def",
+    ]
+
+
+def test_the_paragraph_lists_its_breaks_and_their_fragments(paragraph_of: Any) -> None:
+    paragraph = paragraph_of(
+        [
+            {"run": {"text": "Before, "}},
+            {"run": {"text": "after the break", "renderedPageBreaks": [FIRST]}},
+        ],
+    )
+
+    breaks = paragraph.rendered_page_breaks
+
+    assert paragraph.contains_page_break is True
+    assert len(breaks) == 1
+    assert breaks[0].preceding_paragraph_fragment.text == "Before, "
+    assert breaks[0].following_paragraph_fragment.text == "after the break"
+    # A run's break reads the same fragments.
+    from_run = list(paragraph.runs[1].iter_inner_content())[0]
+    assert from_run.preceding_paragraph_fragment.text == "Before, "
+
+
+def test_a_fragment_python_docx_has_none_of_is_none(paragraph_of: Any) -> None:
+    paragraph = paragraph_of(
+        [
+            {
+                "run": {
+                    "text": "All on the new page",
+                    "renderedPageBreaks": [
+                        {"offset": 0, "preceding": None, "following": "All on the new page"}
+                    ],
+                }
+            }
+        ],
+    )
+
+    [brk] = paragraph.rendered_page_breaks
+
+    assert brk.preceding_paragraph_fragment is None
+    assert brk.following_paragraph_fragment.text == "All on the new page"
+
+
+def test_a_later_break_raises_for_its_fragments_as_python_docx_does(paragraph_of: Any) -> None:
+    paragraph = paragraph_of(
+        [
+            {
+                "run": {
+                    "text": "one ",
+                    "renderedPageBreaks": [{"offset": 2, "preceding": "on", "following": "e two"}],
+                }
+            },
+            {"run": {"text": "two", "renderedPageBreaks": [{"offset": 1}]}},
+        ],
+    )
+
+    first, second = paragraph.rendered_page_breaks
+
+    assert first.preceding_paragraph_fragment.text == "on"
+    with pytest.raises(ValueError, match="first rendered page-break"):
+        _ = second.preceding_paragraph_fragment
+    with pytest.raises(ValueError, match="first rendered page-break"):
+        _ = second.following_paragraph_fragment
+
+
+def test_a_link_run_s_break_is_the_link_s_and_the_paragraph_s(paragraph_of: Any) -> None:
+    link_break = {"offset": 2, "preceding": "See link", "following": " after"}
+    paragraph = paragraph_of(
+        [
+            {"run": {"text": "See "}},
+            {
+                "run": {
+                    "text": "link",
+                    "hyperlink": "https://example.com/",
+                    "renderedPageBreaks": [link_break],
+                }
+            },
+            {"run": {"text": " after"}},
+        ],
+    )
+
+    [link] = paragraph.hyperlinks
+
+    assert link.contains_page_break is True
+    assert [brk.following_paragraph_fragment.text for brk in paragraph.rendered_page_breaks] == [
+        " after"
+    ]
+
+
+def test_a_paragraph_without_breaks_reads_none(paragraph_of: Any) -> None:
+    paragraph = paragraph_of([{"run": {"text": "Plain"}}, {"run": {"text": "", "break": "page"}}])
+
+    assert paragraph.contains_page_break is False
+    assert paragraph.rendered_page_breaks == []
+    assert [run.contains_page_break for run in paragraph.runs] == [False, False]
+
+
+def test_a_run_whose_text_is_replaced_holds_its_break_no_more(paragraph_of: Any) -> None:
+    """python-docx's ``run.text = ...`` replaces all of the run's content, its
+    rendered page break too (``Run.clear()`` does the same through it)."""
+    paragraph = paragraph_of(
+        [{"run": {"text": "abcdef", "renderedPageBreaks": [{"offset": 3, "preceding": "abc", "following": "def"}]}}],
+    )
+    run = paragraph.runs[0]
+
+    run.text = "new"
+
+    assert run.contains_page_break is False
+    assert "RenderedPageBreak" not in _kinds(list(run.iter_inner_content()))
+
+
+def test_a_break_after_ruby_base_text_counts_it(paragraph_of: Any) -> None:
+    """The break's offset counts the run's text with its ruby base text, which
+    python-docx's run text leaves out."""
+    paragraph = paragraph_of(
+        [{"run": {"text": "A\u6f22BC", "ruby": [[1, 2]], "renderedPageBreaks": [{"offset": 2, "preceding": "A", "following": "BC"}]}}],
+    )
+
+    assert _kinds(list(paragraph.runs[0].iter_inner_content())) == ["A", "RenderedPageBreak", "BC"]
+