hlink: add Hyperlink.address

Author: scanny

features/hlk-props.feature

@@ -4,7 +4,6 @@ Feature: Access hyperlink properties
   I need properties on Hyperlink
 
 
-  @wip
   Scenario: Hyperlink.address has the URL of the hyperlink
     Given a hyperlink
      Then hyperlink.address is the URL of the hyperlink

src/docx/oxml/text/hyperlink.py

@@ -2,8 +2,24 @@
 
 from __future__ import annotations
 
-from docx.oxml.xmlchemy import BaseOxmlElement
+from typing import List
+
+from docx.oxml.simpletypes import ST_OnOff, XsdString
+from docx.oxml.text.run import CT_R
+from docx.oxml.xmlchemy import (
+    BaseOxmlElement,
+    OptionalAttribute,
+    RequiredAttribute,
+    ZeroOrMore,
+)
 
 
 class CT_Hyperlink(BaseOxmlElement):
     """`<w:hyperlink>` element, containing the text and address for a hyperlink."""
+
+    r_lst: List[CT_R]
+
+    rId = RequiredAttribute("r:id", XsdString)
+    history = OptionalAttribute("w:history", ST_OnOff, default=True)
+
+    r = ZeroOrMore("w:r")

src/docx/text/hyperlink.py

@@ -24,3 +24,13 @@ def __init__(self, hyperlink: CT_Hyperlink, parent: t.StoryChild):
         super().__init__(parent)
         self._parent = parent
         self._hyperlink = self._element = hyperlink
+
+    @property
+    def address(self) -> str:
+        """The "URL" of the hyperlink (but not necessarily a web link).
+
+        While commonly a web link like "https://google.com" the hyperlink address can
+        take a variety of forms including "internal links" to bookmarked locations
+        within the document.
+        """
+        return self._parent.part.rels[self._hyperlink.rId].target_ref

tests/oxml/text/test_hyperlink.py

@@ -0,0 +1,47 @@
+"""Test suite for the docx.oxml.text.hyperlink module."""
+
+from typing import cast
+
+import pytest
+
+from docx.oxml.text.hyperlink import CT_Hyperlink
+from docx.oxml.text.run import CT_R
+
+from ...unitutil.cxml import element
+
+
+class DescribeCT_Hyperlink:
+    """Unit-test suite for the CT_Hyperlink (<w:hyperlink>) element."""
+
+    def it_has_a_relationship_that_contains_the_hyperlink_address(self):
+        cxml = 'w:hyperlink{r:id=rId6}/w:r/w:t"post"'
+        hyperlink = cast(CT_Hyperlink, element(cxml))
+
+        rId = hyperlink.rId
+
+        assert rId == "rId6"
+
+    @pytest.mark.parametrize(
+        ("cxml", "expected_value"),
+        [
+            # -- default (when omitted) is True, somewhat surprisingly --
+            ("w:hyperlink{r:id=rId6}", True),
+            ("w:hyperlink{r:id=rId6,w:history=0}", False),
+            ("w:hyperlink{r:id=rId6,w:history=1}", True),
+        ],
+    )
+    def it_knows_whether_it_has_been_clicked_on_aka_visited(
+        self, cxml: str, expected_value: bool
+    ):
+        hyperlink = cast(CT_Hyperlink, element(cxml))
+        assert hyperlink.history is expected_value
+
+    def it_has_zero_or_more_runs_containing_the_hyperlink_text(self):
+        cxml = 'w:hyperlink{r:id=rId6,w:history=1}/(w:r/w:t"blog",w:r/w:t" post")'
+        hyperlink = cast(CT_Hyperlink, element(cxml))
+
+        rs = hyperlink.r_lst
+
+        assert [type(r) for r in rs] == [CT_R, CT_R]
+        assert rs[0].text == "blog"
+        assert rs[1].text == " post"

tests/text/test_hyperlink.py

@@ -0,0 +1,44 @@
+"""Test suite for the docx.text.hyperlink module."""
+
+from typing import cast
+
+import pytest
+
+from docx import types as t
+from docx.opc.rel import _Relationship  # pyright: ignore[reportPrivateUsage]
+from docx.oxml.text.hyperlink import CT_Hyperlink
+from docx.parts.story import StoryPart
+from docx.text.hyperlink import Hyperlink
+
+from ..unitutil.cxml import element
+from ..unitutil.mock import FixtureRequest, Mock, instance_mock
+
+
+class DescribeHyperlink:
+    """Unit-test suite for the docx.text.hyperlink.Hyperlink object."""
+
+    def it_knows_the_hyperlink_URL(self, fake_parent: t.StoryChild):
+        cxml = 'w:hyperlink{r:id=rId6}/w:r/w:t"post"'
+        hlink = cast(CT_Hyperlink, element(cxml))
+        hyperlink = Hyperlink(hlink, fake_parent)
+
+        assert hyperlink.address == "https://google.com/"
+
+    # -- fixtures --------------------------------------------------------------------
+
+    @pytest.fixture
+    def fake_parent(self, story_part: Mock, rel: Mock) -> t.StoryChild:
+        class StoryChild:
+            @property
+            def part(self) -> StoryPart:
+                return story_part
+
+        return StoryChild()
+
+    @pytest.fixture
+    def rel(self, request: FixtureRequest):
+        return instance_mock(request, _Relationship, target_ref="https://google.com/")
+
+    @pytest.fixture
+    def story_part(self, request: FixtureRequest, rel: Mock):
+        return instance_mock(request, StoryPart, rels={"rId6": rel})