ENH: Allow fonts to be addressed by any of their SFNT family names

[Cemonix]

PR summary

Closes #4822

A TTF/OTF font file can advertise its family name in multiple places in the
OpenType name table. FreeType exposes one name (typically from the
Macintosh-platform Name ID 1 slot), but other entries carry equally valid names
that users reasonably expect to work:

• Name ID 1, other platform — some fonts store different names on the Mac
  and Microsoft platforms. For example, Ubuntu Light stores "Ubuntu" in the
  Mac slot and "Ubuntu Light" in the Microsoft slot.
• Name ID 16 — Typographic/Preferred Family: groups more than the
  traditional four styles (Regular, Bold, Italic, Bold Italic) under one name.
• Name ID 21 — WWS Family: an even narrower grouping (weight/width/slope
  only).

Previously, only the FreeType-derived name was registered, so users had to use
an unintuitive weight-based workaround:

# Before
matplotlib.rcParams['font.family'] = 'Ubuntu'
matplotlib.rcParams['font.weight'] = 300

This PR adds _get_font_alt_names() and calls it from FontManager.addfont()
to register a separate FontEntry for each alternative name found. Each
alternate entry derives its weight from the corresponding subfamily string
(ID 2/17/22) on the same platform, so that the font's role within its named
family is reflected correctly (e.g. Ubuntu Light is weight 400/"Regular" within
the "Ubuntu Light" family, even though its absolute typographic weight is 300).

After this change:

matplotlib.rcParams['font.family'] = 'Ubuntu Light'

PR checklist

• closes Light font variants cannot be accessed by common name #4822 is in the body of the PR description to link the related issue
• new and changed code is tested
• Plotting related features are demonstrated in an example
• New Features and API Changes are noted with a directive and release note
• Documentation complies with general and docstring guidelines

[github-actions]

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.

You can also join us on gitter 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.

[tacaswell]

This seems reasonable on a quick read to me, but @QuLogic needs to review this.

[QuLogic]

It probably makes sense to add more names where available, but I'm uncertain whether, e.g., Ubuntu Light should be regular weight, or a Light suffix should trigger a lower weight instead.

IIRC, @anntzer last looked at the algorithm here, and is probably best suited to deciding.

[anntzer]

• I agree that there's something not so clear about whether family = "Ubuntu Light" should match with weight = "Regular" (in that it's the "Regular" "Ubuntu Light" font). Maybe we need FontProperties attributes to have an "unset" value (differing from "Regular")? How does e.g. CSS matching (which is very well specified) work in that case?
• How does the name detection compare with fontconfig's algorithm (at https://cgit.freedesktop.org/fontconfig/tree/src/fcfreetype.c#n1384)?

[Cemonix]

Thanks for the questions! I reviewed fontconfig's FcFreeTypeQueryFaceInternal and the CSS font matching spec to understand this better.

Re: fontconfig comparison:

The approach is very similar - both iterate over name IDs (1/16/21 for family, 2/17/22 for subfamily) on Mac and Microsoft platforms, then parse the subfamily string for weight keywords.

The main difference: fontconfig uses -1 as "unset" and defaults to FC_WEIGHT_MEDIUM if no weight is found, while my code defaults to 400 immediately when no keyword matches.

Re: "unset" vs 400:

I chose 400 to match matplotlib's existing behavior and CSS semantics. In CSS, an unspecified weight always resolves to a numeric value (typically 400/"normal") before font matching begins. So when a user requests family='Ubuntu Light' without specifying weight, they get the "Regular" variant of that family.

However, I'm open to using a sentinel value (like None) if you think that better represents these alternate families. The tradeoff is it would require changes to the scoring function to handle unset weights.

Re: CSS matching:

CSS Fonts Level 4 spec defines normal = 400, and the matching algorithm searches outward from the requested weight when exact matches aren't available. There's no concept of "unset weight" in the matching algorithm - it always works with numeric values.

Let me know if you'd prefer a different approach for handling the weights.

[QuLogic]

Since you are changing the FontEntrys, I think you would need to bump the FontManager.__version__ to ensure the cache is regenerated.

I also think you may want to target the text-overhaul branch, as I suspect there will be some conflicts that would need resolving.

[Cemonix]

Done, also fixed the face-loop conflict in addfont and the set append in the test while rebasing onto text-overhaul.

[QuLogic]

Looking at https://learn.microsoft.com/en-us/typography/opentype/spec/name, it makes sense to me to look at IDs 1/2, 16/17, and 21/22. Maybe that'll be too many, but we'll see if people complain.

And I can see the argument that "Ubuntu Light" -> (name="Ubuntu", weight=100) with a separate entry of (name="Ubuntu Light", weight=400).

[ksunden]

Merged over known test failures that are resolved by other PRs

[QuLogic]

Thanks @Cemonix! Congratulations on your first PR to Matplotlib 🎉 We hope to hear from you again.