Class Hyperlink

src/docx/text/hyperlink.py:20–121

Proxy object wrapping a ` ` 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.

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.ProvidesStoryPart):
        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. When this hyperlink is an internal "jump" to for example a
        heading from the table-of-contents (TOC), the address is blank. The bookmark
        reference (like "_Toc147925734") is stored in the `.fragment` property.
        """
        rId = self._hyperlink.rId
        return self._parent.part.rels[rId].target_ref if rId else ""

    @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)

    @property
    def fragment(self) -> str:
        """Reference like `#glossary` at end of URL that refers to a sub-resource.

        Note that this value does not include the fragment-separator character ("#").

        This value is known as a "named anchor" in an HTML context and "anchor" in the
        MS API, but an "anchor" element (`<a>`) represents a full hyperlink in HTML so
        we avoid confusion by using the more precise RFC 3986 naming "URI fragment".

        These are also used to refer to bookmarks within the same document, in which
        case the `.address` value with be blank ("") and this property will hold a
        value like "_Toc147925734".

        To reliably get an entire web URL you will need to concatenate this with the
        `.address` value, separated by "#" when both are present. Consider using the
        `.url` property for that purpose.

        Word sometimes stores a fragment in this property (an XML attribute) and
        sometimes with the address, depending on how the URL is inserted, so don&#x27;t