feature: Paragraph.add_hyperlink()

[scanny]

Protocol might be something like this:

>>> hyperlink = paragraph.add_hyperlink(text='foobar', url='http://github.com')
>>> hyperlink
<docx.text.Hyperlink instance at 0xdeadbeef1>
>>> hyperlink.url
'http://github.com'
>>> hyperlink.text
'foobar'

XML specimen:

<w:p>
  <w:r>
    <w:t xml:space="preserve">This sentence has a </w:t>
  </w:r>
  <w:hyperlink r:id="rId5" w:history="1">
    <w:r>
      <w:rPr>
        <w:rStyle w:val="Hyperlink"/>
      </w:rPr>
      <w:t>hyperlink</w:t>
    </w:r>
  </w:hyperlink>
  <w:r>
    <w:t xml:space="preserve"> in it.</w:t>
  </w:r>
</w:p>

[robertdodd]

I'm trying to get this working maybe you can help:

robertdodd@a616e81#diff-d41d8cd98f00b204e9800998ecf8427e

XML works just like above, but I'm not sure how to add a URL to the docs References and get the refId.

Could someone point me in the right direction?

[scanny]

This method in the test code might be a help:
https://github.com/python-openxml/python-docx/blob/master/tests/opc/test_package.py#L328

The critical call will be something like:

rId = part.relate_to(url, reltype, is_external=True)

Then the value of rId will replace your 'rId5' above.

For the main document, you can get a reference to the document part using: document._document_part.

reltype can vary, but a regular hyperlink uses docx.opc.contants.RELATIONSHIP_TYPE.HYPERLINK. I usually use this to get those references:

from docx.opc.constants import RELATIONSHIP_TYPE as RT

foo = RT.HYPERLINK

You can check an example document using opc-diag to see what relationship type URI it uses in your particular case if you think it might be different.

[robertdodd]

Thank you for the fast reply -- I'll try it out and get back to you soon...

[robertdodd]

I got it working, thanks so much! Could you please give me some quick feedback?

robertdodd@1aa3860

I passed the document to paragraph.add_hyperlink so the relationship could be created. Is there a way to use the document without passing it around?

hyperlink = p.add_hyperlink(document, text='Google', url='http://google.com')

I also want to update the URL manually -- but you need a reference to the document to do that and I'm not sure where to put it.

hyperlink.text = 'Google'
hyperlink.url = 'http://google.com'

[taliastocks]

@robertdodd Any progress on this feature? I see you went back and forth and got some feedback from @scanny.

[robertdodd]

Hey @collinstocks -- If you want to use this now I got it working roughly over here. There are also internal hyperlinks over here thanks to Anton.

I got great feedback from @scanny and Anton but I've been a bit caught up recently and haven't finished implementing it yet. I should get some time soon -- and hopefully we'll see it merged!

[AKimZ]

@robertdodd: Same question as @collinstocks and a note. I'm using your implementation and it works quite well. However, the hyperlinks are generated without any styling associated. (Looks like plain text) Maybe address that before releasing this feature?

[tanyunshi]

@robertdodd, @AKimZ: I continue @robertdodd's work and adding styles and multiple runs for the same link are possible now. See tanyunshi@6b9d40b

[johnzupancic]

@tanyunshi Thank you! This is awesome. I wonder if you'll be able to merge what you have with the most recent version of python_docx (since we can adjust the color of text to be blue).

[tanyunshi]

@johnzupancic, hihi, merge done here tanyunshi@90237e8

[gordeychuk]

Hi guys,

Looks like adding hyperlinks now possible, but what about reading them from paragraph?
I have a problem that after reading text from paragraph I missed hyperlinks.
Can I do this using changes which done in this thread?

[MuhammetDilmac]

Hi @scanny
When this feature implementation on main repo?