hlink: add Hyperlink.contains_page_break

Author: scanny

features/hlk-props.feature

@@ -9,7 +9,6 @@ Feature: Access hyperlink properties
      Then hyperlink.address is the URL of the hyperlink
 
 
-  @wip
   Scenario Outline: Hyperlink.contains_page_break reports presence of page-break
     Given a hyperlink having <zero-or-more> rendered page breaks
      Then hyperlink.contains_page_break is <value>

src/docx/oxml/text/hyperlink.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import List
+from typing import TYPE_CHECKING, List
 
 from docx.oxml.simpletypes import ST_OnOff, XsdString
 from docx.oxml.text.run import CT_R
@@ -13,6 +13,9 @@
     ZeroOrMore,
 )
 
+if TYPE_CHECKING:
+    from docx.oxml.text.pagebreak import CT_LastRenderedPageBreak
+
 
 class CT_Hyperlink(BaseOxmlElement):
     """`<w:hyperlink>` element, containing the text and address for a hyperlink."""
@@ -23,3 +26,8 @@ class CT_Hyperlink(BaseOxmlElement):
     history = OptionalAttribute("w:history", ST_OnOff, default=True)
 
     r = ZeroOrMore("w:r")
+
+    @property
+    def lastRenderedPageBreaks(self) -> List[CT_LastRenderedPageBreak]:
+        """All `w:lastRenderedPageBreak` descendants of this hyperlink."""
+        return self.xpath("./w:r/w:lastRenderedPageBreak")

src/docx/text/hyperlink.py

@@ -34,3 +34,15 @@ def address(self) -> str:
         within the document.
         """
         return self._parent.part.rels[self._hyperlink.rId].target_ref
+
+    @property
+    def contains_page_break(self) -> bool:
+        """True when the text of this hyperlink is broken across page boundaries.
+
+        This is not uncommon and can happen for example when the hyperlink text is
+        multiple words and occurs in the last line of a page. Theoretically, a hyperlink
+        can contain more than one page break but that would be extremely uncommon in
+        practice. Still, this value should be understood to mean that "one-or-more"
+        rendered page breaks are present.
+        """
+        return bool(self._hyperlink.lastRenderedPageBreaks)

tests/text/test_hyperlink.py

@@ -24,6 +24,24 @@ def it_knows_the_hyperlink_URL(self, fake_parent: t.StoryChild):
 
         assert hyperlink.address == "https://google.com/"
 
+    @pytest.mark.parametrize(
+        ("hlink_cxml", "expected_value"),
+        [
+            ("w:hyperlink", False),
+            ("w:hyperlink/w:r", False),
+            ('w:hyperlink/w:r/(w:t"abc",w:lastRenderedPageBreak,w:t"def")', True),
+            ('w:hyperlink/w:r/(w:lastRenderedPageBreak,w:t"abc",w:t"def")', True),
+            ('w:hyperlink/w:r/(w:t"abc",w:t"def",w:lastRenderedPageBreak)', True),
+        ],
+    )
+    def it_knows_whether_it_contains_a_page_break(
+        self, hlink_cxml: str, expected_value: bool, fake_parent: t.StoryChild
+    ):
+        hlink = cast(CT_Hyperlink, element(hlink_cxml))
+        hyperlink = Hyperlink(hlink, fake_parent)
+
+        assert hyperlink.contains_page_break is expected_value
+
     # -- fixtures --------------------------------------------------------------------
 
     @pytest.fixture