Skip to content

Add bookmark creation and lookup - #1615

Draft
pseudosavant wants to merge 1 commit into
python-openxml:masterfrom
pseudosavant:codex/bookmarks-upstream
Draft

pseudosavant wants to merge 1 commit into
python-openxml:masterfrom
pseudosavant:codex/bookmarks-upstream

Conversation

@pseudosavant

Copy link
Copy Markdown

Problem and behavior

Document generators need public bookmark creation and lookup without replacing existing targets. This adds Document.bookmarks with add(name, paragraph=...), add(name, runs=...), and case-insensitive get(name). Bookmark proxies expose the stored name and their starting main-story paragraph.

Paragraph targets are collapsed ranges at the start of a paragraph. Run ranges cover consecutive direct runs of one paragraph. Body paragraphs and table cells are supported for creation. Invalid names, duplicate names, reversed or nonconsecutive ranges, detached paragraphs, and cross-document or other-story targets are rejected before mutation.

New names use a documented portable subset of Word's 40-character limit. Existing names are preserved. IDs and names in related Word stories are reserved, including unparsed note parts. Lookup includes those names and returns no paragraph proxy for unsupported stories. No rename or deletion behavior is introduced.

Validation

  • New unit and acceptance coverage for paragraph targets, run ranges, invalid ranges, duplicates, related-story collisions, saved-package preservation, and a Word-authored fixture.
  • Word navigation was checked with two identically named heading paragraphs and distinct targets.
  • Full upstream tests and acceptance scenarios pass on this branch.

Scope and design

This is a draft for API feedback and relates to #445. It is based directly on upstream master and excludes fork packaging and other fork features.

My fork separately extends the hyperlink authoring API proposed in #1611 with an anchor argument. That integration is kept in a separate commit so this bookmark API can be reviewed independently. Markdown heading slugs and unresolved-link diagnostics remain in the downstream converter. Names and API conventions can change to follow upstream feedback.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant