hlink: add Hyperlink.text

Author: scanny

features/hlk-props.feature

@@ -30,7 +30,6 @@ Feature: Access hyperlink properties
       | two          |   2   |
 
 
-  @wip
   Scenario: Hyperlink.text has the visible text of the hyperlink
     Given a hyperlink
      Then hyperlink.text is the visible text of the hyperlink

src/docx/oxml/text/hyperlink.py

@@ -31,3 +31,11 @@ class CT_Hyperlink(BaseOxmlElement):
     def lastRenderedPageBreaks(self) -> List[CT_LastRenderedPageBreak]:
         """All `w:lastRenderedPageBreak` descendants of this hyperlink."""
         return self.xpath("./w:r/w:lastRenderedPageBreak")
+
+    @property  # pyright: ignore[reportIncompatibleVariableOverride]
+    def text(self) -> str:
+        """The textual content of this hyperlink.
+
+        `CT_Hyperlink` stores the hyperlink-text as one or more `w:r` children.
+        """
+        return "".join(r.text for r in self.xpath("w:r"))

src/docx/text/hyperlink.py

@@ -60,3 +60,13 @@ def runs(self) -> List[Run]:
         was saved.
         """
         return [Run(r, self) for r in self._hyperlink.r_lst]
+
+    @property
+    def text(self) -> str:
+        """String formed by concatenating the text of each run in the hyperlink.
+
+        Tabs and line breaks in the XML are mapped to ``\\t`` and ``\\n`` characters
+        respectively. Note that rendered page-breaks can occur within a hyperlink but
+        they are not reflected in this text.
+        """
+        return self._hyperlink.text

tests/text/test_hyperlink.py

@@ -63,7 +63,27 @@ def it_provides_access_to_the_runs_it_contains(
 
         actual = [type(item).__name__ for item in runs]
         expected = ["Run" for _ in range(count)]
-        assert actual == expected, f"expected: {expected}, got: {actual}"
+        assert actual == expected
+
+    @pytest.mark.parametrize(
+        ("hlink_cxml", "expected_text"),
+        [
+            ("w:hyperlink", ""),
+            ("w:hyperlink/w:r", ""),
+            ('w:hyperlink/w:r/w:t"foobar"', "foobar"),
+            ('w:hyperlink/w:r/(w:t"foo",w:lastRenderedPageBreak,w:t"bar")', "foobar"),
+            ('w:hyperlink/w:r/(w:t"abc",w:tab,w:t"def",w:noBreakHyphen)', "abc\tdef-"),
+        ],
+    )
+    def it_knows_the_visible_text_of_the_link(
+        self, hlink_cxml: str, expected_text: str, fake_parent: t.StoryChild
+    ):
+        hlink = cast(CT_Hyperlink, element(hlink_cxml))
+        hyperlink = Hyperlink(hlink, fake_parent)
+
+        text = hyperlink.text
+
+        assert text == expected_text
 
     # -- fixtures --------------------------------------------------------------------