Feature Request: Add Hyperlinks With Multiple Runs

[ptoshkov]

I need to be able to add hyperlinks with multiple runs to paragraphs. Right now I am able to achieve this like so:

from docx.oxml.shared import OxmlElement, qn
from docx.opc.constants import RELATIONSHIP_TYPE
from docx import Document
from docx.text.run import Run
from docx.shared import RGBColor

def add_hyperlink(paragraph, address, runs):
    # Access the document.xml.rels file and get a new relationship type ID
    part = paragraph.part
    r_id = part.relate_to(address, RELATIONSHIP_TYPE.HYPERLINK, is_external=True)

    # Create the w:hyperlink tag and add needed properties
    HYPERLINK_TAG = 'w:hyperlink'
    RELATIONSHIP_TYPE_ID_PROPERTY = 'r:id'
    hyperlink = OxmlElement(HYPERLINK_TAG)
    hyperlink.set(qn(RELATIONSHIP_TYPE_ID_PROPERTY), r_id)

    for run in runs:
        hyperlink.append(run)

    paragraph._p.append(hyperlink)
    return hyperlink

RUN_TAG = 'w:r'
PROPERTIES_TAG = 'w:rPr'
document = Document()
paragraph = document.add_paragraph()

r1 = OxmlElement(RUN_TAG)
rPr1 = OxmlElement(PROPERTIES_TAG)
r1.append(rPr1)
r1.text = 'Google '
run1 = Run(r1, paragraph)
run1.underline = True
run1.bold = True
run1.font.color.rgb = RGBColor(255, 0, 0)

r2 = OxmlElement(RUN_TAG)
rPr2 = OxmlElement(PROPERTIES_TAG)
r2.append(rPr2)
r2.text = 'dot com'
run2 = Run(r2, paragraph)
run2.underline = True
run2.italic = True
run2.font.color.rgb = RGBColor(0, 255, 0)

add_hyperlink(paragraph, 'https://google.com', [run1._r, run2._r])
document.save('new.docx')

and this produces a hyperlink that looks like this:

Would it be possible to extend the API to support adding hyperlinks with different runs? Since hyperlinks are containers for runs, similar to paragraphs, I would imagine the API would look similar to the API for paragraphs. I.e. you can add a hyperlink with text directly:

hyperlink = paragraph.add_hyperlink('https://google.com', 'Google dot com')

You can change the text and address post-factum:

hyperlink.text = 'Google.com'
hyperlink.address = 'https://www.google.com'

Or you can fill the hyperlink incrementally with runs:

hyperlink = paragraph.add_hyperlink('https://google.com')
hyperlink.add_run('Google ').bold = True
hyperlink.add_run('dot com').italic= True

It would be nice to have this functionality in the API by default. I can try to add it if you tell me what you'd like the API to look like. Thanks in advance!