_wip_: implement hyperlink

yunshi · yunshi · commit 9b71461f6211 · 2016-03-30T21:51:29.000+02:00
diff --git a/docx/oxml/__init__.py b/docx/oxml/__init__.py
@@ -181,6 +181,9 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 from .text.paragraph import CT_P
 register_element_cls('w:p', CT_P)
 
+from .text.hyperlink import CT_Hyperlink
+register_element_cls('w:hyperlink', CT_Hyperlink)
+
 from .text.parfmt import CT_Ind, CT_Jc, CT_PPr, CT_Spacing
 register_element_cls('w:ind',             CT_Ind)
 register_element_cls('w:jc',              CT_Jc)
diff --git a/docx/oxml/text/hyperlink.py b/docx/oxml/text/hyperlink.py
@@ -0,0 +1,40 @@
+# encoding: utf-8
+
+"""
+Custom element classes related to hyperlinks (CT_Hyperlink).
+"""
+
+from ..ns import qn
+from ..simpletypes import ST_String, ST_RelationshipId
+from ..xmlchemy import (
+    BaseOxmlElement, OptionalAttribute, ZeroOrMore
+)
+
+
+class CT_Hyperlink(BaseOxmlElement):
+    """
+    ``<w:hyperlink>`` element, containing the properties and text for a external hyperlink.
+    """
+    r = ZeroOrMore('w:r')
+    rid = OptionalAttribute('r:id', ST_RelationshipId)
+    anchor = OptionalAttribute('w:anchor', ST_String)
+
+    @property
+    def relationship(self):
+        """
+        String contained in ``r:id`` attribute of <w:hyperlink>. It should
+        point to a URL in the document's relationships.
+        """
+        val = self.get(qn('r:id'))
+        return val
+
+    @relationship.setter
+    def relationship(self, rId):
+        self.set(qn('r:id'), rId)
+
+    def clear_content(self):
+        """
+        Remove all child elements.
+        """
+        for child in self[:]:
+            self.remove(child)
diff --git a/docx/oxml/text/paragraph.py b/docx/oxml/text/paragraph.py
@@ -14,6 +14,7 @@ class CT_P(BaseOxmlElement):
     """
     pPr = ZeroOrOne('w:pPr')
     r = ZeroOrMore('w:r')
+    hyperlink = ZeroOrMore('w:hyperlink')
 
     def _insert_pPr(self, pPr):
         self.insert(0, pPr)
diff --git a/docx/text/hyperlink.py b/docx/text/hyperlink.py
@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+"""
+Hyperlink proxy objects.
+"""
+
+from __future__ import (
+    absolute_import, division, print_function, unicode_literals
+)
+
+from ..opc.constants import RELATIONSHIP_TYPE as RT
+from ..shared import Parented
+from .run import Run
+
+
+class Hyperlink(Parented):
+    """
+    Proxy object wrapping ``<w:hyperlink>`` element.
+    """
+    def __init__(self, hyperlink, parent):
+        super(Hyperlink, self).__init__(parent)
+        self._hyperlink = self.element = hyperlink
+
+    @property
+    def address(self):
+        rId = self._hyperlink.relationship
+        return self.part.target_ref(rId) if rId else None
+
+    @address.setter
+    def address(self, url):
+        rId = self.part.relate_to(url, RT.HYPERLINK, is_external=True)
+        self._hyperlink.relationship = rId
+
+    @property
+    def anchor(self):
+        return self._hyperlink.anchor
+
+    @anchor.setter
+    def anchor(self, anchor):
+        self._hyperlink.anchor = anchor
+
+    def iter_runs(self):
+        return [Run(r, self) for r in self._hyperlink.r_lst]
+
+    def insert_run(self, text, style=None):
+        _r = self._hyperlink.add_r()
+        run = Run(_r, self)
+        run.text = text
+        if style:
+            run.style = style
+        return run
+
+    @property
+    def text(self):
+        return ''.join([run.text for run in self.iter_runs()])
+
+    @text.setter
+    def text(self, text):
+        self._hyperlink.clear_content()
+        self.insert_run(text)
diff --git a/docx/text/paragraph.py b/docx/text/paragraph.py
@@ -9,9 +9,10 @@
 )
 
 from ..enum.style import WD_STYLE_TYPE
+from ..shared import Parented
+from .hyperlink import Hyperlink
 from .parfmt import ParagraphFormat
 from .run import Run
-from ..shared import Parented
 
 
 class Paragraph(Parented):
@@ -22,6 +23,24 @@ def __init__(self, p, parent):
         super(Paragraph, self).__init__(parent)
         self._p = self._element = p
 
+    def add_hyperlink(self, text, address=None, anchor=None, style=None):
+
+        _h = self._p.add_hyperlink()
+        _r = _h.add_r()
+        hyperlink = Hyperlink(_h, self)
+        run = Run(_r, hyperlink)
+
+        run.text = text
+        if style:
+            run.style = style
+
+        if address:
+            hyperlink.address = address
+        if anchor:
+            hyperlink.anchor = anchor
+
+        return hyperlink
+
     def add_run(self, text=None, style=None):
         """
         Append a run to this paragraph containing *text* and having character
