hlink: add Hyperlink.runs

scanny · scanny · commit 01061a8f5da7 · 2023-10-01T20:08:33.000-07:00
diff --git a/features/hlk-props.feature b/features/hlk-props.feature
@@ -19,7 +19,6 @@ Feature: Access hyperlink properties
       | one          | True  |
 
 
-  @wip
   Scenario Outline: Hyperlink.runs contains Run for each run in hyperlink
     Given a hyperlink having <zero-or-more> runs
      Then hyperlink.runs has length <value>
diff --git a/src/docx/text/hyperlink.py b/src/docx/text/hyperlink.py
@@ -7,9 +7,12 @@
 
 from __future__ import annotations
 
+from typing import List
+
 from docx import types as t
 from docx.oxml.text.hyperlink import CT_Hyperlink
 from docx.shared import Parented
+from docx.text.run import Run
 
 
 class Hyperlink(Parented):
@@ -46,3 +49,14 @@ def contains_page_break(self) -> bool:
         rendered page breaks are present.
         """
         return bool(self._hyperlink.lastRenderedPageBreaks)
+
+    @property
+    def runs(self) -> List[Run]:
+        """List of |Run| instances in this hyperlink.
+
+        Together these define the visible text of the hyperlink. The text of a hyperlink
+        is typically contained in a single run will be broken into multiple runs if for
+        example part of the hyperlink is bold or the text was changed after the document
+        was saved.
+        """
+        return [Run(r, self) for r in self._hyperlink.r_lst]
diff --git a/tests/text/test_hyperlink.py b/tests/text/test_hyperlink.py
@@ -42,6 +42,29 @@ def it_knows_whether_it_contains_a_page_break(
 
         assert hyperlink.contains_page_break is expected_value
 
+    @pytest.mark.parametrize(
+        ("hlink_cxml", "count"),
+        [
+            ("w:hyperlink", 0),
+            ("w:hyperlink/w:r", 1),
+            ("w:hyperlink/(w:r,w:r)", 2),
+            ("w:hyperlink/(w:r,w:lastRenderedPageBreak)", 1),
+            ("w:hyperlink/(w:lastRenderedPageBreak,w:r)", 1),
+            ("w:hyperlink/(w:r,w:lastRenderedPageBreak,w:r)", 2),
+        ],
+    )
+    def it_provides_access_to_the_runs_it_contains(
+        self, hlink_cxml: str, count: int, fake_parent: t.StoryChild
+    ):
+        hlink = cast(CT_Hyperlink, element(hlink_cxml))
+        hyperlink = Hyperlink(hlink, fake_parent)
+
+        runs = hyperlink.runs
+
+        actual = [type(item).__name__ for item in runs]
+        expected = ["Run" for _ in range(count)]
+        assert actual == expected, f"expected: {expected}, got: {actual}"
+
     # -- fixtures --------------------------------------------------------------------
 
     @pytest.fixture
