René's URL Explorer Experiment


Title: Add public external hyperlink authoring by pseudosavant · Pull Request #1611 · python-openxml/python-docx · GitHub

Open Graph Title: Add public external hyperlink authoring by pseudosavant · Pull Request #1611 · python-openxml/python-docx

X Title: Add public external hyperlink authoring by pseudosavant · Pull Request #1611 · python-openxml/python-docx

Description: Callers can read hyperlinks today but must construct XML to create them. This draft adds Paragraph.add_hyperlink(), Hyperlink.add_run(), and a read/write Hyperlink.tooltip property. Together they create external links with formatted labels and optional hover text through public APIs. paragraph = document.add_paragraph("Read ") link = paragraph.add_hyperlink( address="https://example.com/docs?lang=en#intro", tooltip="Project documentation", ) link.add_run("the ") link.add_run("documentation").bold = True paragraph.add_run(" for details.") The implementation extends the current Hyperlink proxy. Relationships belong to the containing story part, including headers and footers. Returned runs use existing formatting, style, and picture APIs. Invalid inputs are checked before attaching a hyperlink or registering its relationship. This implements the external hyperlink creation described in #74, using the API proposed below. The issue discussion also covers internal links and other operations. Internal links and bookmarks, address mutation, removal, arbitrary run insertion, and visited-state management are outside this draft. The "External authoring proposal" section in docs/dev/analysis/features/text/hyperlink.rst explains the API choices and the relationship to #278 and #784. This draft builds on the current reader instead of importing either older implementation. Following the acceptance-test guidance, the branch starts with an API proposal, then introduces acceptance specifications tagged @wip, followed by small implementation commits with isolated unit tests. Each tag is removed when its scenarios pass. The sequence was rebuilt from a local prototype, with the failing and passing stages rerun. API decisions for review: Require keyword-only address and preserve the complete external destination, including escapes and URI fragments. Defer a separate fragment argument and URL encoding. Use append-only add_run(text, style) to match Paragraph.add_run(). Defer the broader insert_run proposal. Leave character styling to the caller. No Hyperlink style is created or applied automatically. The user guide supplies a public-API recipe for themed styling. Treat tooltip None as absent and "" as explicitly empty. Permit both creation-time assignment and later edits. These choices need maintainer agreement. In particular, feedback on the narrow append-only API and the styling default would help settle the draft. I plan to follow this with internal links and bookmark authoring. I can bring internal hyperlink creation into this PR if you prefer to review external and internal destinations together. Bookmark creation could remain a separate contribution, or be included here after we agree on its API and scope. Validation on Windows with Python 3.13: 1,677 unit and saved-document tests pass, including 68 new cases. 672 acceptance scenarios pass, including 22 new scenarios. Ruff lint and formatting checks pass. No new Pyright diagnostics. The diagnostic multiset matches the upstream baseline of 7,577 existing diagnostics. A clean HTML documentation build succeeds using Sphinx 9.1 with the legacy intersphinx mapping disabled in memory. One existing unresolved container reference remains in the comments guide. The unchanged public API was previously exercised in Word. The sample opened without repair and rendered formatted labels, a linked picture, and links in body, table, header, and footer content. Word displayed the custom tooltip and exact destination. External navigation has not been exercised.

Open Graph Description: Callers can read hyperlinks today but must construct XML to create them. This draft adds Paragraph.add_hyperlink(), Hyperlink.add_run(), and a read/write Hyperlink.tooltip property. Together they c...

X Description: Callers can read hyperlinks today but must construct XML to create them. This draft adds Paragraph.add_hyperlink(), Hyperlink.add_run(), and a read/write Hyperlink.tooltip property. Together they c...

Opengraph URL: https://github.com/python-openxml/python-docx/pull/1611

X: @github

direct link

Domain: github.com

react-profiling0
react-import-mapreact,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322
route-pattern/:user_id/:repository/pull/:id/files(.:format)
route-controllerpull_requests
route-actionfiles
fetch-noncev2:81d8fb18-bf70-bbcc-9801-5bb520a4df78
current-catalog-service-hashae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b
request-idD528:36BC9B:496764:61D4CF:6AFF6C0C
html-safe-nonce98da5f3535ad119466ba5d7854601e04015bd1f2bc497c730779082abf468204
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJENTI4OjM2QkM5Qjo0OTY3NjQ6NjFENENGOjZBRkY2QzBDIiwidmlzaXRvcl9pZCI6IjUzNTc3MjAyNDYxMDQ4NDUzMjQiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ==
visitor-hmac4b5367823ac43cd50e4c51901859c701a170a70eae82c101a6db9d156046c389
hovercard-subject-tagpull_request:4550610546
github-keyboard-shortcutsrepository,pull-request-list,pull-request-conversation,pull-request-files-changed,copilot
google-site-verificationApib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I
octolytics-urlhttps://collector.github.com/github/collect
analytics-location///pull_requests/show/files
fb:app_id1401488693436528
apple-itunes-appapp-id=1477376905, app-argument=https://github.com/python-openxml/python-docx/pull/1611/files
twitter:imagehttps://avatars.githubusercontent.com/u/455424?s=400&v=4
twitter:cardsummary_large_image
og:imagehttps://avatars.githubusercontent.com/u/455424?s=400&v=4
og:image:altCallers can read hyperlinks today but must construct XML to create them. This draft adds Paragraph.add_hyperlink(), Hyperlink.add_run(), and a read/write Hyperlink.tooltip property. Together they c...
og:site_nameGitHub
og:typeobject
hostnamegithub.com
expected-hostnamegithub.com
None6d580fc7098c193d7866bf290c4c2b4859a153e87379f44161f35a4495e6b730
turbo-cache-controlno-preview
diff-viewunified
go-importgithub.com/python-openxml/python-docx git https://github.com/python-openxml/python-docx.git
octolytics-dimension-user_id3403760
octolytics-dimension-user_loginpython-openxml
octolytics-dimension-repository_id13592924
octolytics-dimension-repository_nwopython-openxml/python-docx
octolytics-dimension-repository_publictrue
octolytics-dimension-repository_is_forkfalse
octolytics-dimension-repository_network_root_id13592924
octolytics-dimension-repository_network_root_nwopython-openxml/python-docx
turbo-body-classeslogged-out env-production page-responsive full-width
disable-turbotrue
browser-stats-urlhttps://api.github.com/_private/browser/stats
browser-errors-urlhttps://api.github.com/_private/browser/errors
releaseec5dd94a369dad6e9ce618a1705cbe3b618a2863
ui-targetfull
theme-color#1e2327
color-schemelight dark

Links:

Skip to contenthttps://github.com/python-openxml/python-docx/pull/1611/files#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fpython-openxml%2Fpython-docx%2Fpull%2F1611%2Ffiles
GitHubRepository hosting, code review, and collaborationhttps://github.com/platform
CopilotAI coding agent for tasks, projects, and automated workhttps://github.com/features/copilot
ActionsCI/CD and automationhttps://github.com/features/actions
Code QualityQuality analysis, fixes, and enforcementhttps://github.com/features/code-quality
CodespacesCloud development environmentshttps://github.com/features/codespaces
Code SecurityVulnerability detection and remediationhttps://github.com/security/advanced-security/code-security
Secret ProtectionSecret scanning and leak preventionhttps://github.com/security/advanced-security/secret-protection
All Featureshttps://github.com/features
Documentationhttps://docs.github.com/en
Traininghttps://learn.github.com/skills
Certificationshttps://learn.github.com/credentials
Build with Copilothttps://github.com/features/ai
Customize Copilothttps://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview
Integrationshttps://github.com/marketplace
Trending reposhttps://github.com/trending
GitHub Sponsorshttps://github.com/open-source/sponsors
Developer articleshttps://github.com/resources/articles
ChangelogYour source for the latest features, improvements, and fixes across GitHub products, all in one place.https://github.blog/changelog/
Enterpriseshttps://github.com/enterprise
Teamhttps://github.com/team
Startupshttps://github.com/enterprise/startups
Nonprofitshttps://github.com/solutions/industry/nonprofits
Healthcarehttps://github.com/solutions/industry/healthcare
Financial serviceshttps://github.com/solutions/industry/financial-services
Manufacturinghttps://github.com/solutions/industry/manufacturing
Governmenthttps://github.com/solutions/industry/government
See all industrieshttps://github.com/solutions/industry
Why GitHubhttps://github.com/why-github
Customer Storieshttps://github.com/customer-stories
Business insightshttps://github.com/solutions/executive-insights
Trust Centerhttps://github.com/trust-center
GitHub Advanced SecurityEnterprise-grade code securityhttps://github.com/security/advanced-security
Copilot for businessEnterprise-grade AI featureshttps://github.com/features/copilot/copilot-business
Premium SupportEnterprise-grade 24/7 supporthttps://github.com/enterprise/premium-support
Documentationhttps://docs.github.com/en
Resource centerhttps://github.com/resources
Bloghttps://github.blog/
Events & webinarshttps://github.com/resources/events
Community Forumhttps://github.com/orgs/community/discussions
Customer Storieshttps://github.com/customer-stories
Integrationshttps://github.com/marketplace
Customer supporthttps://help.github.com/
Traininghttps://learn.github.com/skills
GitHub Statushttps://www.githubstatus.com/
Abouthttps://github.com/about
Partnershttps://github.com/partners
Changeloghttps://github.blog/changelog/
GitHub UniverseThe event for developers, by developers — talks, workshops, and what’s next for GitHub.https://githubuniverse.com/
Pricinghttps://github.com/pricing
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fpython-openxml%2Fpython-docx%2Fpull%2F1611%2Ffiles
Sign uphttps://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fpull_requests%2Fshow%2Ffiles&source=header-repo&source_repo=python-openxml%2Fpython-docx
Reloadhttps://github.com/python-openxml/python-docx/pull/1611/files
Reloadhttps://github.com/python-openxml/python-docx/pull/1611/files
Reloadhttps://github.com/python-openxml/python-docx/pull/1611/files
python-openxmlhttps://github.com/python-openxml
python-docxhttps://github.com/python-openxml/python-docx
Codehttps://github.com/python-openxml/python-docx
Issues387 (387)https://github.com/python-openxml/python-docx/issues
Pull requests167 (167)https://github.com/python-openxml/python-docx/pulls
Actionshttps://github.com/python-openxml/python-docx/actions
Projectshttps://github.com/python-openxml/python-docx/projects
Wikihttps://github.com/python-openxml/python-docx/wiki
Security and qualityhttps://github.com/python-openxml/python-docx/security
Insightshttps://github.com/python-openxml/python-docx/insights
Sign up for GitHub https://github.com/signup?return_to=%2Fpython-openxml%2Fpython-docx%2Fissues%2Fnew%2Fchoose
terms of servicehttps://docs.github.com/terms
privacy statementhttps://docs.github.com/privacy
Sign inhttps://github.com/login?return_to=%2Fpython-openxml%2Fpython-docx%2Fissues%2Fnew%2Fchoose
pseudosavanthttps://github.com/pseudosavant
python-openxml:masterhttps://github.com/python-openxml/python-docx/tree/master
pseudosavant:codex/hyperlink-authoringhttps://github.com/pseudosavant/python-docx/tree/codex/hyperlink-authoring
Conversation 1 https://github.com/python-openxml/python-docx/pull/1611
Commits 12 https://github.com/python-openxml/python-docx/pull/1611/commits
Checks 0 https://github.com/python-openxml/python-docx/pull/1611/checks
Files changed https://github.com/python-openxml/python-docx/pull/1611/files
Please reload this pagehttps://github.com/python-openxml/python-docx/pull/1611/files
Add public external hyperlink authoring https://github.com/python-openxml/python-docx/pull/1611/files#top
Show all changes 12 commits https://github.com/python-openxml/python-docx/pull/1611/files
edef91a docs: propose external hyperlink authoring protocol pseudosavant Sep 16, 2026 https://github.com/python-openxml/python-docx/pull/1611/commits/edef91a110effc2672a4511da8685632841cceaa
e923b26 acpt: specify Hyperlink.add_run() pseudosavant Sep 16, 2026 https://github.com/python-openxml/python-docx/pull/1611/commits/e923b26abcd7efc823b0b3cc436b137f8203663d
530ed3c hyperlink: add Hyperlink.add_run() pseudosavant Sep 16, 2026 https://github.com/python-openxml/python-docx/pull/1611/commits/530ed3c58900dfd2137509ec4158533f6b1d51b9
48dfcd9 acpt: specify Paragraph.add_hyperlink() pseudosavant Sep 16, 2026 https://github.com/python-openxml/python-docx/pull/1611/commits/48dfcd984286046a3e664666d1ab4e89d8605bf5
ef2d7bb hyperlink: add CT_Hyperlink.new() pseudosavant Sep 16, 2026 https://github.com/python-openxml/python-docx/pull/1611/commits/ef2d7bbb179cc927f4dba4088ea765518a6589e7
15c8ff3 hyperlink: add Paragraph.add_hyperlink() pseudosavant Sep 16, 2026 https://github.com/python-openxml/python-docx/pull/1611/commits/15c8ff3fa3f15167e2e709f1ac6f56a0a3df51d8
df89d3c acpt: specify Hyperlink.tooltip pseudosavant Sep 16, 2026 https://github.com/python-openxml/python-docx/pull/1611/commits/df89d3ca511f97217a07b426e7328fa3ec85c3c3
4e97ec1 hyperlink: add CT_Hyperlink.tooltip pseudosavant Sep 16, 2026 https://github.com/python-openxml/python-docx/pull/1611/commits/4e97ec124fd8c06cdfbced69bbead91838397e52
8cae0ff hyperlink: add Hyperlink.tooltip pseudosavant Sep 16, 2026 https://github.com/python-openxml/python-docx/pull/1611/commits/8cae0ff0866897bea63f089b22a1ece85bec1520
fcb5290 acpt: specify tooltip on hyperlink creation pseudosavant Sep 16, 2026 https://github.com/python-openxml/python-docx/pull/1611/commits/fcb5290797e7aee89f5076fddd0f9583a2f76235
a561453 hyperlink: accept tooltip on hyperlink creation pseudosavant Sep 16, 2026 https://github.com/python-openxml/python-docx/pull/1611/commits/a56145321c3d8f4670b3cf8e277c3db42bab09fd
4604c6b docs: document external hyperlink authoring pseudosavant Sep 16, 2026 https://github.com/python-openxml/python-docx/pull/1611/commits/4604c6be6dc2f01c803b47c9efc029584abdbb6a
Clear filters https://github.com/python-openxml/python-docx/pull/1611/files
Please reload this pagehttps://github.com/python-openxml/python-docx/pull/1611/files
Please reload this pagehttps://github.com/python-openxml/python-docx/pull/1611/files
HISTORY.rst https://github.com/python-openxml/python-docx/pull/1611/files#diff-e2de3cbc57ab9b097fca7d7c444c094ba3c1d4ee92b36d972d0d9d49669436cc
hyperlink.rst https://github.com/python-openxml/python-docx/pull/1611/files#diff-a4227e541b216e5d6f8d4c9517991c586ec3649ca073b3a47d24b8c99de15fec
text.rst https://github.com/python-openxml/python-docx/pull/1611/files#diff-85105836de9f444626219392e235d247bbadcbef44d0d290d1b6c3a3ff499999
hlk-add-run.feature https://github.com/python-openxml/python-docx/pull/1611/files#diff-6f648df6ef54505513e5276b62c78887c60adf5eed2296307416b17bd51f60a5
hlk-tooltip.feature https://github.com/python-openxml/python-docx/pull/1611/files#diff-884cc669447cdeba2e21170c01c93d1d0d02c050989de7ed0bf6b4433be58afa
par-add-hyperlink.feature https://github.com/python-openxml/python-docx/pull/1611/files#diff-b774a6c4d34f036e9372042badce4ea7f19f5fc2a488fae8cab019463a6b5600
hyperlink_authoring.py https://github.com/python-openxml/python-docx/pull/1611/files#diff-441bfa5d6d8271fda4610ce01513c165b4582940a119a62429f8849fa77f3459
hyperlink.py https://github.com/python-openxml/python-docx/pull/1611/files#diff-ab3de2abda99c2ee0560636be0f0019df0f41959f6ac8e36aaee5f84d12c0f17
hyperlink.py https://github.com/python-openxml/python-docx/pull/1611/files#diff-f2a426c6ef6e8d06b5341dc2347d4e570c31d5f296374d59026a5d9c24494b54
paragraph.py https://github.com/python-openxml/python-docx/pull/1611/files#diff-97eceaeb4ca0c9bd77aa456168dff469c3196b2dd4891f694d9f66c2c8fe4da0
test_hyperlink.py https://github.com/python-openxml/python-docx/pull/1611/files#diff-bd543add274a970fbb2de4175b5c4d66d9439b102022a1dfbc9856533bd74924
test_hyperlink.py https://github.com/python-openxml/python-docx/pull/1611/files#diff-c48b59ca41f3ada8af618f8f148e94f83d6b2d46a5d41f592778dd0b222deb5a
test_hyperlink_roundtrip.py https://github.com/python-openxml/python-docx/pull/1611/files#diff-5e86edb7ec5d7381a524fd89e298068d18568450aa302649fa61aaa77e490374
test_paragraph.py https://github.com/python-openxml/python-docx/pull/1611/files#diff-e9a03c4eb41c734107ef5073b6657104cccdf9eede0e18cca01fe0885670b7d3
HISTORY.rsthttps://github.com/python-openxml/python-docx/pull/1611/files#diff-e2de3cbc57ab9b097fca7d7c444c094ba3c1d4ee92b36d972d0d9d49669436cc
View file https://github.com/python-openxml/python-docx/blob/4604c6be6dc2f01c803b47c9efc029584abdbb6a/HISTORY.rst
Open in desktop https://desktop.github.com
https://github.co/hiddenchars
https://github.com/python-openxml/python-docx/pull/1611/{{ revealButtonHref }}
https://github.com/python-openxml/python-docx/pull/1611/files#diff-e2de3cbc57ab9b097fca7d7c444c094ba3c1d4ee92b36d972d0d9d49669436cc
https://github.com/python-openxml/python-docx/pull/1611/files#diff-e2de3cbc57ab9b097fca7d7c444c094ba3c1d4ee92b36d972d0d9d49669436cc
docs/dev/analysis/features/text/hyperlink.rsthttps://github.com/python-openxml/python-docx/pull/1611/files#diff-a4227e541b216e5d6f8d4c9517991c586ec3649ca073b3a47d24b8c99de15fec
View file https://github.com/python-openxml/python-docx/blob/4604c6be6dc2f01c803b47c9efc029584abdbb6a/docs/dev/analysis/features/text/hyperlink.rst
Open in desktop https://desktop.github.com
https://github.co/hiddenchars
https://github.com/python-openxml/python-docx/pull/1611/{{ revealButtonHref }}
https://github.com/python-openxml/python-docx/pull/1611/files#diff-a4227e541b216e5d6f8d4c9517991c586ec3649ca073b3a47d24b8c99de15fec
https://github.com/python-openxml/python-docx/pull/1611/files#diff-a4227e541b216e5d6f8d4c9517991c586ec3649ca073b3a47d24b8c99de15fec
https://github.com/python-openxml/python-docx/pull/1611/files#diff-a4227e541b216e5d6f8d4c9517991c586ec3649ca073b3a47d24b8c99de15fec
https://github.com/python-openxml/python-docx/pull/1611/files#diff-a4227e541b216e5d6f8d4c9517991c586ec3649ca073b3a47d24b8c99de15fec
docs/user/text.rsthttps://github.com/python-openxml/python-docx/pull/1611/files#diff-85105836de9f444626219392e235d247bbadcbef44d0d290d1b6c3a3ff499999
View file https://github.com/python-openxml/python-docx/blob/4604c6be6dc2f01c803b47c9efc029584abdbb6a/docs/user/text.rst
Open in desktop https://desktop.github.com
https://github.co/hiddenchars
https://github.com/python-openxml/python-docx/pull/1611/{{ revealButtonHref }}
https://github.com/python-openxml/python-docx/pull/1611/files#diff-85105836de9f444626219392e235d247bbadcbef44d0d290d1b6c3a3ff499999
https://github.com/python-openxml/python-docx/pull/1611/files#diff-85105836de9f444626219392e235d247bbadcbef44d0d290d1b6c3a3ff499999
features/hlk-add-run.featurehttps://github.com/python-openxml/python-docx/pull/1611/files#diff-6f648df6ef54505513e5276b62c78887c60adf5eed2296307416b17bd51f60a5
View file https://github.com/python-openxml/python-docx/blob/4604c6be6dc2f01c803b47c9efc029584abdbb6a/features/hlk-add-run.feature
Open in desktop https://desktop.github.com
https://github.co/hiddenchars
https://github.com/python-openxml/python-docx/pull/1611/{{ revealButtonHref }}
features/hlk-tooltip.featurehttps://github.com/python-openxml/python-docx/pull/1611/files#diff-884cc669447cdeba2e21170c01c93d1d0d02c050989de7ed0bf6b4433be58afa
View file https://github.com/python-openxml/python-docx/blob/4604c6be6dc2f01c803b47c9efc029584abdbb6a/features/hlk-tooltip.feature
Open in desktop https://desktop.github.com
https://github.co/hiddenchars
https://github.com/python-openxml/python-docx/pull/1611/{{ revealButtonHref }}
features/par-add-hyperlink.featurehttps://github.com/python-openxml/python-docx/pull/1611/files#diff-b774a6c4d34f036e9372042badce4ea7f19f5fc2a488fae8cab019463a6b5600
View file https://github.com/python-openxml/python-docx/blob/4604c6be6dc2f01c803b47c9efc029584abdbb6a/features/par-add-hyperlink.feature
Open in desktop https://desktop.github.com
https://github.co/hiddenchars
https://github.com/python-openxml/python-docx/pull/1611/{{ revealButtonHref }}
Please reload this pagehttps://github.com/python-openxml/python-docx/pull/1611/files
https://github.com
Termshttps://docs.github.com/site-policy/github-terms/github-terms-of-service
Privacyhttps://docs.github.com/site-policy/privacy-policies/github-privacy-statement
Securityhttps://github.com/security
Statushttps://www.githubstatus.com/
Communityhttps://github.community/
Docshttps://docs.github.com/
Contacthttps://support.github.com?tags=dotcom-footer

Viewport: width=device-width


URLs of crawlers that visited me.