Add public external hyperlink authoring - #1611
Draft
pseudosavant wants to merge 12 commits into
Draft
pseudosavant wants to merge 12 commits into
pseudosavant wants to merge 12 commits into
Conversation
Author
|
@scanny I’ve prepared this draft with acceptance tests, unit tests, and documentation. Before marking it ready for review, I’d appreciate your feedback on the proposed API and scope. Would you prefer internal hyperlink support included here or handled in a follow-up PR? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Callers can read hyperlinks today but must construct XML to create them. This draft adds
Paragraph.add_hyperlink(),Hyperlink.add_run(), and a read/writeHyperlink.tooltipproperty. Together they create external links with formatted labels and optional hover text through public APIs.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.rstexplains 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:
addressand preserve the complete external destination, including escapes and URI fragments. Defer a separatefragmentargument and URL encoding.add_run(text, style)to matchParagraph.add_run(). Defer the broaderinsert_runproposal.Noneas 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:
containerreference remains in the comments guide.