Skip to content

Add public inline shape description and title properties - #1613

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

pseudosavant wants to merge 1 commit into
python-openxml:masterfrom
pseudosavant:codex/image-alt-text-upstream

Conversation

@pseudosavant

Copy link
Copy Markdown

Summary

Inline pictures currently have no public API for reading or writing their alternative-text description and title. This draft adds InlineShape.description and InlineShape.title, allowing callers to preserve image descriptions without manipulating XML.

picture = document.add_picture("revenue.png")
picture.description = "Quarterly revenue increased by 20 percent."
picture.title = "Quarterly revenue"

The properties map to wp:docPr/@descr and wp:docPr/@title. They apply to each placed shape, so repeated uses of one image can carry different descriptions.

Scope and behavior

  • Add optional XML attributes, public properties, documentation, unit tests, and acceptance scenarios.
  • Preserve existing add_picture() signatures. Callers set metadata on the returned shape.
  • Return None for an absent attribute. Assigning None removes it. An empty string remains explicit.
  • Preserve image bytes, relationships, dimensions, IDs, object names, and unrelated metadata.
  • Leave nested pic:cNvPr metadata unchanged and do not use it as a fallback.
  • Leave decorative-image flags and floating-shape authoring outside this proposal.

Related work and API feedback

Related to #1530, #227, and #317. In particular, this follows the properties-only scope discussed as an option in #1530. That proposal uses alt_text and alt_title, while this draft uses description and title. Naming and missing/empty-value conventions are open for discussion.

This implementation is used in a separately published fork by the Markdown converter markdown-docx. That is currently the fork's only consumer. We can update both projects to follow the conventions agreed here, so the fork's published names do not need to constrain the upstream API.

This branch is based directly on upstream master and contains one feature commit. Fork packaging, release configuration, theme-font changes, and hyperlink changes are excluded.

Validation

  • 1,631 unit tests passed against the upstream-based branch.
  • 652 acceptance scenarios passed against the upstream-based branch.
  • Tests cover Unicode, empty and cleared values, invalid assignments, repeated image instances, and pictures in body paragraphs, table cells, headers, and footers.
  • Saved-package checks verify unrelated parts and drawing metadata are preserved.
  • Microsoft Word read both properties correctly through its object model. After Word saved the document, both values were verified on reopening with python-docx.

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