Add language parameter to Text objects by QuLogic · Pull Request #29794 · matplotlib/matplotlib · GitHub

PR summary

Along with #29695, this language parameter is an additional setting that may affect text layout. As with the other PR, this is not complete, but rather something to get the API decided upon (and likely will be rebased on raqm PR after it's done.)

There are two parts to the API:

the language parameter attached to Text, and any other API that wraps it (i.e., Axes.text or Axes.annotate)
the language parameter in backend's Renderer.draw_text

At the moment, for both, I have set these to str | list[tuple[str, int, int]] where the latter denotes a list of (language, start, end)-tuples. However, this was before I found out about the font feature machinery, and it is possible that we may wish to use that syntax instead, at least for API part 1. For part 2, it's a little nicer to have the explicit types, just for passing to the FT2Font extension, but this may not be relevant to other implementations.

PR checklist

[n/a] "closes #0000" 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

re: adding language to draw_text: the general discussion about extensibility of renderer API applies, i.e.

if you're going to add language as a parameter to draw_text then it should be at least keyword-only.
it's likely that the more maintainable API would likely to just embed language as part of fontproperties (it's not really different from e.g. font features, I'd think) and tell the backend to read that info.
for draw_text we have actually more or less given up on having a "clean" renderer API because we pass the whole Text instance to draw_text (per Propagate mpl.text.Text instances to the backends and fix documentation #1081) anyways so perhaps backends that care could also just read that info off the Text instance. It feels a bit dirty, but heh... ("dirty" because we as well may just have a renderer API that's renderer.draw_text(textobj) to start with...)

Side point regarding allowing list[tuple[str, int, int]] as language setting: this may be a problem if one uses somelanguage[idx:] to set the language from an index up to the end of the string (whose length could technically be modified later, even though it's not clear this necessarily makes much practical sense). Likely you need list[tuple[str, int, int | None]] (and then you may possibly support None (=0) for the start as well).

In the call a couple weeks ago, we decided to drop the new language parameter to draw_text, because that already had a mtext parameter which contained the whole Text object. This would avoid any signature introspection.

However, one followup is that Renderer.get_text_width_height_descent would also depend on font features/language settings, and really should get these passed through somehow as well.

These params should be kwonly? (throughout most of the PR, I think)

This function actually takes a length, not an end location; I'm not sure which one we should accept (Harfbuzz feature tags use start/end, so maybe that?), but I'll have to update this to the correct naming (the test is setup to match what libraqm says, but the docs say the opposite.)

start-stop looks normal as API to me?

I agree and have made that change.

Also extended the tests a bit to ensure that the results are as expected and fixed the fallback to the rcParam as well.

The test image is extracted to a separate commit as it should not be merged yet.

Super picky change to match the example ordering to the text ordering:

Suggested change

      
                fig.text(0, 0.1, f'English: {char}', fontsize=40, language='en')
          
                fig.text(1, 0.1, f'Inari Sámi: {char}', fontsize=40, language='smn',
          
                fig.text(0, 0.1, f'Inari Sámi: {char}', fontsize=40, language='smn')
          
                fig.text(1, 0.1, f'English: {char}', fontsize=40, language='en',

It looks like the appveyor tests hung.

OK, I fixed the doc note, and moved the test image to the text-overhaul-figures branch in preparation for merging.

Add language parameter to Text objects

This includes images changes for the following pull requests / commits: * [Fix center of rotation with rotation_mode='anchor'](matplotlib#29199) (c44db77) * [Remove ttconv backwards-compatibility code](matplotlib#30145) (8caff88) * [Remove kerning_factor from tests](matplotlib#29816) (7b4d725) * [Set text hinting to defaults](matplotlib#29816) (8255ae2) * [Update FreeType to 2.13.3](matplotlib#29816) (89c054d) * [Implement text shaping with libraqm](matplotlib#30000) (b0ded3a, 9813523) * [Add language parameter to Text objects](matplotlib#29794) (7ce8eae) * [Fix auto-sized glyphs with BaKoMa fonts](matplotlib#29936) (3ba2c13) * [pdf: Improve text with characters outside embedded font limits](matplotlib#30512) (b70fb88, 6cedcf7) * [Prepare `CharacterTracker` for advanced font features](matplotlib#30608) (8274e17, 70dc388, df670cf, ed5e074) * [Add font feature API to Text](matplotlib#29695) (972a688) * [Fix spacing in r"$\max f$"](matplotlib#30715) (4a99a83) * [Implement libraqm for vector outputs](matplotlib#30607) (bd17cd4) * [Drop the FT2Font intermediate buffer](matplotlib#30059) (9d7d7b4) * [Rasterize dvi files without dvipng](matplotlib#30039) (7627118) * [Update bundled FreeType and HarfBuzz libraries](matplotlib#30938) (a161658, 9619bcc) * [Fix positioning of wide mathtext accents](matplotlib#31069) (c2fa7ba) * [Refactor RendererAgg.draw_{mathtext,text,tex} to use same base algorithm](matplotlib#31085) (931bcf3) * [Implement TeX's fraction and script alignment](matplotlib#31046) (94ff452, 4bfa0f9, 1cd8510) * [Fix confusion between text height and ascent in metrics calculations](matplotlib#31107) (60f2310) * [mathtext: Fetch quad width & axis height from font metrics](matplotlib#31110) (692df3f, 383028b) * [mathtext: add mathnormal and distinguish between normal and italic family](matplotlib#31121) (a6913f3) * [ENH: Ignore empty text for tightbbox](matplotlib#31285) (d772043) * [Drop axis_artist tickdir image compat, due to text-overhaul merge](matplotlib#31281) (2057583) * [text: Use font metrics to determine line heights](matplotlib#31291) (3ab6a27, d961462, 97f4943) * [ps/pdf: Override font height metrics to support AFM files](matplotlib#31371) (e0913d4) * [TST: Cleanup back-compat code in tests touched by text overhaul](matplotlib#31295) (7c33379) * [TST: Set tests touched by text overhaul to mpl20 style](matplotlib#31300) (41c4d8d)

QuLogic added the topic: text label Mar 22, 2025

QuLogic added this to the v3.11.0 milestone Mar 22, 2025

github-actions Bot added backend: pgf backend: agg backend: ps backend: pdf backend: svg backend: cairo topic: text/fonts topic: canvas and figure manager labels Mar 22, 2025

QuLogic force-pushed the text-language branch from ffd43e9 to b3cfa4d Compare March 22, 2025 09:35

anntzer mentioned this pull request Mar 22, 2025

Add font feature API to Text #29695

Merged

4 of 5 tasks

QuLogic mentioned this pull request Apr 16, 2025

Fix signature of disabled draw methods #29923

Merged

1 task done

QuLogic force-pushed the text-language branch from b3cfa4d to 161e393 Compare April 17, 2025 08:40

github-actions Bot removed backend: pgf backend: svg backend: cairo topic: canvas and figure manager labels Apr 17, 2025

QuLogic force-pushed the text-language branch from 161e393 to f240057 Compare April 17, 2025 08:45

QuLogic mentioned this pull request May 2, 2025

Implement text shaping with libraqm #30000

Merged

3 of 5 tasks

QuLogic commented May 7, 2025

View reviewed changes

Comment thread lib/matplotlib/_text_helpers.py

QuLogic force-pushed the text-language branch from f240057 to 736bb64 Compare May 7, 2025 06:29

anntzer reviewed May 10, 2025

View reviewed changes

Comment thread src/ft2font_wrapper.cpp Outdated

QuLogic force-pushed the text-language branch 2 times, most recently from 3c188df to 931423b Compare May 13, 2025 03:28

QuLogic force-pushed the text-language branch from 931423b to 46c6239 Compare May 22, 2025 20:31

QuLogic commented Aug 27, 2025

View reviewed changes

github-actions Bot added status: needs rebase and removed status: needs rebase labels Aug 27, 2025

QuLogic force-pushed the text-language branch from 1858a56 to 6d35c9a Compare September 3, 2025 03:06

github-actions Bot removed topic: mplot3d status: needs rebase labels Sep 3, 2025

QuLogic moved this from Waiting for other PR to Ready for Review in Font and text overhaul Sep 3, 2025

QuLogic force-pushed the text-language branch 3 times, most recently from 6fc2dee to 6ef55ed Compare September 3, 2025 03:22

github-actions Bot added the status: needs rebase label Sep 16, 2025

QuLogic force-pushed the text-language branch 2 times, most recently from d8051c2 to 886bf64 Compare September 19, 2025 05:55

github-actions Bot removed the status: needs rebase label Sep 19, 2025

QuLogic force-pushed the text-language branch 2 times, most recently from 0485aee to 3ffce36 Compare September 19, 2025 06:33

tacaswell reviewed Sep 19, 2025

View reviewed changes

tacaswell approved these changes Sep 19, 2025

View reviewed changes

Add language parameter to Text objects

7ce8eae

QuLogic force-pushed the text-language branch from 3ffce36 to 7ce8eae Compare September 20, 2025 03:05

QuLogic merged commit 44c17bc into matplotlib:text-overhaul Sep 20, 2025
46 of 47 checks passed

QuLogic deleted the text-language branch September 20, 2025 04:13

github-project-automation Bot moved this from Ready for Review to Done in Font and text overhaul Sep 20, 2025

QuLogic mentioned this pull request Sep 27, 2025

Prepare CharacterTracker for advanced font features #30608

Merged

1 task done

wavebyrd pushed a commit to wavebyrd/matplotlib that referenced this pull request Mar 13, 2026

Merge pull request matplotlib#29794 from QuLogic/text-language

aab8a80

Add language parameter to Text objects

QuLogic mentioned this pull request Apr 10, 2026

Font and text overhaul #30161

Merged

4 tasks done



		def layout(string, font, *, kern_mode=Kerning.DEFAULT):
		def layout(string, font, language, *, kern_mode=Kerning.DEFAULT):

+                  if (languages.has_value()) {
+                      for (auto & [lang_str, start, end] : languages.value()) {
+                          if (!raqm_set_language(rq, lang_str.c_str(), start, end)) {

		fig.text(0, 0.1, f'English: {char}', fontsize=40, language='en')
		fig.text(1, 0.1, f'Inari Sámi: {char}', fontsize=40, language='smn',

Add language parameter to Text objects by QuLogic · Pull Request #29794 · matplotlib/matplotlib · GitHub

Repository navigation

Add language parameter to Text objects - #29794

Add language parameter to Text objects#29794QuLogic merged 1 commit intomatplotlib:text-overhaulmatplotlib/matplotlib:text-overhaulfrom QuLogic:text-languageQuLogic/matplotlib:text-languageCopy head branch name to clipboard

Conversation

QuLogic commented Mar 22, 2025

PR summary

PR checklist

Uh oh!

anntzer commented Mar 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anntzer commented Mar 28, 2025

Uh oh!

QuLogic commented Apr 16, 2025

Uh oh!

Uh oh!

anntzer May 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

QuLogic Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anntzer Aug 27, 2025

Choose a reason for hiding this comment

Uh oh!

QuLogic Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

QuLogic commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tacaswell Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tacaswell commented Sep 19, 2025

Uh oh!

QuLogic commented Sep 20, 2025

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Add language parameter to Text objects#29794
QuLogic merged 1 commit into
matplotlib:text-overhaulfrom
QuLogic:text-language

anntzer commented Mar 22, 2025 •
edited
Loading

QuLogic Aug 27, 2025 •
edited
Loading

QuLogic commented Sep 3, 2025 •
edited
Loading

tacaswell Sep 19, 2025 •
edited
Loading