para: add Paragraph.hyperlinks

Author: scanny

features/par-access-inner-content.feature

@@ -15,7 +15,6 @@ Feature: Access paragraph inner-content including hyperlinks
       | two          | True  |
 
 
-  @wip
   Scenario Outline: Paragraph.hyperlinks contains Hyperlink for each link in paragraph
     Given a paragraph having <zero-or-more> hyperlinks
      Then paragraph.hyperlinks has length <value>

src/docx/oxml/__init__.py

@@ -21,6 +21,7 @@
     CT_ShapeProperties,
     CT_Transform2D,
 )
+from docx.oxml.text.hyperlink import CT_Hyperlink
 from docx.oxml.text.pagebreak import CT_LastRenderedPageBreak
 from docx.oxml.text.run import (
     CT_R,
@@ -50,6 +51,11 @@
 register_element_cls("wp:extent", CT_PositiveSize2D)
 register_element_cls("wp:inline", CT_Inline)
 
+# ---------------------------------------------------------------------------
+# hyperlink-related elements
+
+register_element_cls("w:hyperlink", CT_Hyperlink)
+
 # ---------------------------------------------------------------------------
 # text-related elements
 

src/docx/oxml/text/hyperlink.py

@@ -0,0 +1,9 @@
+"""Custom element classes related to hyperlinks (CT_Hyperlink)."""
+
+from __future__ import annotations
+
+from docx.oxml.xmlchemy import BaseOxmlElement
+
+
+class CT_Hyperlink(BaseOxmlElement):
+    """`<w:hyperlink>` element, containing the text and address for a hyperlink."""

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.hyperlink import CT_Hyperlink
     from docx.oxml.text.pagebreak import CT_LastRenderedPageBreak
     from docx.oxml.text.parfmt import CT_PPr
     from docx.oxml.text.run import CT_R
@@ -18,9 +19,11 @@ class CT_P(BaseOxmlElement):
     """`<w:p>` element, containing the properties and text for a paragraph."""
 
     get_or_add_pPr: Callable[[], CT_PPr]
+    hyperlink_lst: List[CT_Hyperlink]
     r_lst: List[CT_R]
 
     pPr: CT_PPr | None = ZeroOrOne("w:pPr")  # pyright: ignore[reportGeneralTypeIssues]
+    hyperlink = ZeroOrMore("w:hyperlink")
     r = ZeroOrMore("w:r")
 
     def add_p_before(self) -> CT_P:

src/docx/text/hyperlink.py

@@ -0,0 +1,26 @@
+"""Hyperlink-related proxy objects for python-docx, Hyperlink in particular.
+
+A hyperlink occurs in a paragraph, at the same level as a Run, and a hyperlink itself
+contains runs, which is where the visible text of the hyperlink is stored. So it's kind
+of in-between, less than a paragraph and more than a run. So it gets its own module.
+"""
+
+from __future__ import annotations
+
+from docx import types as t
+from docx.oxml.text.hyperlink import CT_Hyperlink
+from docx.shared import Parented
+
+
+class Hyperlink(Parented):
+    """Proxy object wrapping a `<w:hyperlink>` element.
+
+    A hyperlink occurs as a child of a paragraph, at the same level as a Run. A
+    hyperlink itself contains runs, which is where the visible text of the hyperlink is
+    stored.
+    """
+
+    def __init__(self, hyperlink: CT_Hyperlink, parent: t.StoryChild):
+        super().__init__(parent)
+        self._parent = parent
+        self._hyperlink = self._element = hyperlink

src/docx/text/paragraph.py

@@ -12,6 +12,7 @@
 from docx.oxml.text.paragraph import CT_P
 from docx.shared import Parented
 from docx.styles.style import CharacterStyle, ParagraphStyle
+from docx.text.hyperlink import Hyperlink
 from docx.text.parfmt import ParagraphFormat
 from docx.text.run import Run
 
@@ -69,6 +70,11 @@ def contains_page_break(self) -> bool:
         """`True` when one or more rendered page-breaks occur in this paragraph."""
         return bool(self._p.lastRenderedPageBreaks)
 
+    @property
+    def hyperlinks(self) -> List[Hyperlink]:
+        """A |Hyperlink| instance for each hyperlink in this paragraph."""
+        return [Hyperlink(hyperlink, self) for hyperlink in self._p.hyperlink_lst]
+
     def insert_paragraph_before(
         self, text: str | None = None, style: str | ParagraphStyle | None = None
     ) -> Self:

tests/text/test_paragraph.py

@@ -38,6 +38,29 @@ def it_knows_whether_it_contains_a_page_break(
 
         assert paragraph.contains_page_break == expected_value
 
+    @pytest.mark.parametrize(
+        ("p_cxml", "count"),
+        [
+            ("w:p", 0),
+            ("w:p/w:r", 0),
+            ("w:p/w:hyperlink", 1),
+            ("w:p/(w:r,w:hyperlink,w:r)", 1),
+            ("w:p/(w:r,w:hyperlink,w:r,w:hyperlink)", 2),
+            ("w:p/(w:hyperlink,w:r,w:hyperlink,w:r)", 2),
+        ],
+    )
+    def it_provides_access_to_the_hyperlinks_it_contains(
+        self, p_cxml: str, count: int, fake_parent: t.StoryChild
+    ):
+        p = cast(CT_P, element(p_cxml))
+        paragraph = Paragraph(p, fake_parent)
+
+        hyperlinks = paragraph.hyperlinks
+
+        actual = [type(item).__name__ for item in hyperlinks]
+        expected = ["Hyperlink" for _ in range(count)]
+        assert actual == expected, f"expected: {expected}, got: {actual}"
+
     def it_knows_its_paragraph_style(self, style_get_fixture):
         paragraph, style_id_, style_ = style_get_fixture
         style = paragraph.style