para: add Paragraph.contains_page_break

Author: scanny

features/par-access-inner-content.feature

@@ -4,7 +4,6 @@ Feature: Access paragraph inner-content including hyperlinks
   I need to access differentiated paragraph content in document order
 
 
-  @wip
   Scenario Outline: Paragraph.contains_page_break reports presence of page-break
     Given a paragraph having <zero-or-more> rendered page breaks
      Then paragraph.contains_page_break is <value>

src/docx/oxml/text/paragraph.py

@@ -9,6 +9,7 @@
 
 if TYPE_CHECKING:
     from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
+    from docx.oxml.text.pagebreak import CT_LastRenderedPageBreak
     from docx.oxml.text.parfmt import CT_PPr
     from docx.oxml.text.run import CT_R
 
@@ -46,6 +47,17 @@ def clear_content(self):
         for child in self.xpath("./*[not(self::w:pPr)]"):
             self.remove(child)
 
+    @property
+    def lastRenderedPageBreaks(self) -> List[CT_LastRenderedPageBreak]:
+        """All `w:lastRenderedPageBreak` descendants of this paragraph.
+
+        Rendered page-breaks commonly occur in a run but can also occur in a run inside
+        a hyperlink. This returns both.
+        """
+        return self.xpath(
+            "./w:r/w:lastRenderedPageBreak | ./w:hyperlink/w:r/w:lastRenderedPageBreak"
+        )
+
     def set_sectPr(self, sectPr):
         """Unconditionally replace or add `sectPr` as grandchild in correct sequence."""
         pPr = self.get_or_add_pPr()

src/docx/text/paragraph.py

@@ -64,6 +64,11 @@ def clear(self):
         self._p.clear_content()
         return self
 
+    @property
+    def contains_page_break(self) -> bool:
+        """`True` when one or more rendered page-breaks occur in this paragraph."""
+        return bool(self._p.lastRenderedPageBreaks)
+
     def insert_paragraph_before(
         self, text: str | None = None, style: str | ParagraphStyle | None = None
     ) -> Self:

tests/conftest.py

@@ -0,0 +1,16 @@
+"""pytest fixtures that are shared across test modules."""
+
+import pytest
+
+from docx import types as t
+from docx.parts.story import StoryPart
+
+
+@pytest.fixture
+def fake_parent() -> t.StoryChild:
+    class StoryChild:
+        @property
+        def part(self) -> StoryPart:
+            raise NotImplementedError
+
+    return StoryChild()

tests/text/test_paragraph.py

@@ -1,7 +1,10 @@
 """Unit test suite for the docx.text.paragraph module."""
 
+from typing import cast
+
 import pytest
 
+from docx import types as t
 from docx.enum.style import WD_STYLE_TYPE
 from docx.enum.text import WD_ALIGN_PARAGRAPH
 from docx.oxml.text.paragraph import CT_P
@@ -16,6 +19,25 @@
 
 
 class DescribeParagraph(object):
+    """Unit-test suite for `docx.text.run.Paragraph`."""
+
+    @pytest.mark.parametrize(
+        ("p_cxml", "expected_value"),
+        [
+            ("w:p/w:r", False),
+            ('w:p/w:r/w:t"foobar"', False),
+            ('w:p/w:hyperlink/w:r/(w:t"abc",w:lastRenderedPageBreak,w:t"def")', True),
+            ("w:p/w:r/(w:lastRenderedPageBreak, w:lastRenderedPageBreak)", True),
+        ],
+    )
+    def it_knows_whether_it_contains_a_page_break(
+        self, p_cxml: str, expected_value: bool, fake_parent: t.StoryChild
+    ):
+        p = cast(CT_P, element(p_cxml))
+        paragraph = Paragraph(p, fake_parent)
+
+        assert paragraph.contains_page_break == expected_value
+
     def it_knows_its_paragraph_style(self, style_get_fixture):
         paragraph, style_id_, style_ = style_get_fixture
         style = paragraph.style

tests/text/test_run.py

@@ -11,7 +11,6 @@
 from docx.enum.text import WD_BREAK, WD_UNDERLINE
 from docx.oxml.text.run import CT_R
 from docx.parts.document import DocumentPart
-from docx.parts.story import StoryPart
 from docx.shape import InlineShape
 from docx.text.font import Font
 from docx.text.run import Run
@@ -278,15 +277,6 @@ def clear_fixture(self, request):
         expected_xml = xml(expected_cxml)
         return run, expected_xml
 
-    @pytest.fixture
-    def fake_parent(self) -> t.StoryChild:
-        class StoryChild:
-            @property
-            def part(self) -> StoryPart:
-                raise NotImplementedError
-
-        return StoryChild()
-
     @pytest.fixture
     def font_fixture(self, Font_, font_):
         run = Run(element("w:r"), None)