Skip to content

ENH: Add Figure.set_alt_text with accessible SVG output - #32557

Closed
scks1 wants to merge 2 commits into
matplotlib:mainfrom
scks1:figure-alt-text
Closed

scks1 wants to merge 2 commits into
matplotlib:mainfrom
scks1:figure-alt-text

Conversation

@scks1

@scks1 scks1 commented Oct 29, 2026

Copy link
Copy Markdown

Summary

Alt text can currently only reach output files as free-form metadata={'Description': ...}, where no assistive technology looks for it. This adds a figure-level alt-text API and makes the SVG backend emit it semantically:

  • Figure.set_alt_text() / Figure.get_alt_text() hold one alt-text string on the figure (default ""; None clears; non-str raises TypeError). There is deliberately no savefig parameter: savefig parameters are per-save overrides in this codebase, while persistent figure state uses setters. A per-save override could layer on later.
  • The SVG backend writes the root <svg> element with role="img" and the alt text as its first-child <title>, which is the element's accessible name. No <desc> is emitted: duplicating one string as both name and description double-announces in some screen readers; a long description belongs to a future, separate API. If a Title entry is also present in the SVG metadata, no second <title> element is emitted.
  • For backends that accept a Description metadata entry (eps, pdf, pgf, png, ps, svg, svgz), print_figure passes the alt text through as that metadata unless the caller supplied their own. Formats that reject unknown metadata keys are excluded.

Default output is unchanged when no alt text is set: the SVG root element gains neither role nor <title>.

Relation to existing work

Honest limits

PDF output is not tagged by this change; the alt text reaches PDF only as document metadata. The docstring and the What's New entry say so explicitly.

Tests

Five new tests across test_backend_svg.py (alt text present in the SVG with role="img" + <title>, absent by default, metadata Title coexistence) and test_figure.py (setter/getter round trip, None clears, TypeError on non-str). test_backend_svg.py + test_figure.py: 202 passed, 15 skipped. test_backend_pdf.py + test_backend_ps.py + test_backend_pgf.py: 72 passed, 48 skipped.

Matplotlib had no way to attach alternative text to a figure in a
form assistive technology can reach: the savefig 'Description'
metadata lands in file metadata only, and the SVG root element had
no accessible name. (Related: matplotlib#15971 asks for alt text for figures
in _repr_html_; PR matplotlib#21328 proposes storing WAI-ARIA annotations on
artists but nothing consumes them yet.)

Add a figure-level alt text:

* Figure.set_alt_text / Figure.get_alt_text store the text on the
  figure (default "", None clears). Following the maintainer
  feedback on matplotlib#21328 to start with the smallest surface, this is a
  single-purpose string rather than a general ARIA dict.
* The SVG backend gives the root <svg> element role="img" and
  writes the alt text as its <title> child - its accessible name.
  If a 'Title' metadata entry is also given, it no longer produces
  a second <title> element; it is still recorded as dc:title.
  Without alt text, SVG output is byte-for-byte unchanged.
* FigureCanvasBase.print_figure passes the alt text to the other
  metadata-accepting formats (eps, pdf, pgf, png, ps, svg, svgz)
  as the 'Description' metadata entry, unless the caller supplied
  one explicitly. That is file metadata only - in particular PDF
  output does not become a tagged PDF - and formats that reject
  metadata entirely (jpeg, tiff, ...) are left untouched.

Tests: setter/getter round-trip and TypeError, PNG Description
pass-through with explicit-Description precedence, SVG role/title
emission, alt-text precedence over the metadata Title, and
unchanged default SVG output. test_backend_svg + test_figure:
202 passed, 15 skipped; backend_pdf/ps/pgf: 72 passed, 48 skipped.
@github-actions

Copy link
Copy Markdown

Thank you for opening your first PR into Matplotlib!

If you have not heard from us in a week or so, please leave a new comment below and that should bring it to our attention. Most of our reviewers are volunteers and sometimes things fall through the cracks. We also ask that you please finish addressing any review comments on this PR and wait for it to be merged (or closed) before opening a new one, as it can be a valuable learning experience to go through the review process.

You can also join us on discourse chat for real-time discussion.

For details on testing, writing docs, and our review process, please see the developer guide.
Please let us know if (and how) you use AI, it will help us give you better feedback on your PR.

We strive to be a welcoming and open project. Please follow our Code of Conduct.

@iccir iccir added the AgentScan: mixed AgentScan detected an account with mixed automation signals. label Oct 29, 2026
stubtest (CI) flags public runtime members missing from the stub:
Figure.get_alt_text and Figure.set_alt_text were added to figure.py
without corresponding declarations in figure.pyi.
@iccir

iccir commented Oct 29, 2026

Copy link
Copy Markdown
Contributor

I am closing this pull request in accordance with our Policy on Generative AI. The account in question appears to be automating pull requests across multiple repositories.

AgentScan has detected automation signals from the account. The AgentScan result was "mixed" when I first checked but has now been updated to "automated".

Additionally, the PR body text appears to be AI-generated and our template was not filled out.

If this is not the case, and this pull request was authored by a human in while following our AI policy, please let me or another maintainer know.

@iccir iccir closed this Oct 29, 2026
@scks1

scks1 commented Oct 29, 2026

Copy link
Copy Markdown
Author

You're right on the process facts, and I won't dispute the closure. This pull request was written by an AI assistant working under my direction: I set the acceptance criteria and verified the results, but I did not check your generative-AI policy or complete the template's AI Disclosure section before it was filed, and the number of repositories filed to that day is also mine to own. I have since adopted a standing disclosure line on every contribution I direct. If a change resubmitted by me personally, in the template format with a full AI disclosure, would be considered on its merits, I will do that work; if the policy closes that door as well, I understand.

@timhoffm

Copy link
Copy Markdown
Member

@scks1 Thanks for the reply.

A resubmitted PR is welcome if you are personally interested in getting this fixed or if you plan to get more involved in the project - and that does not mean primarily creating more strongly AI-backed PRs, but rather triaging, reviewing and discussing project direction, architecture etc.
Otherwise, please refrain from resubmitting. As stated in our AI policy simultaneously contributing to several projects is not a good investment of your and the maintainers' time. You'd learn more and ease maintainer life if you go into the depth in one or two projects only. Maintainers can orchestrate agents too, and often more efficiently because they know the projects context and direction. Therefore, reviewing a third-party PR can often be more work than writing a PR and reviewing it within the core dev team.

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants