Add language parameter to Text objects #29794

QuLogic · 2025-03-22T09:26:14Z

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

anntzer · 2025-03-22T12:57:23Z

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...)

anntzer · 2025-03-28T21:02:17Z

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).

QuLogic · 2025-04-16T02:55:50Z

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.

lib/matplotlib/_text_helpers.py

anntzer · 2025-05-10T13:26:49Z

lib/matplotlib/_text_helpers.py



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


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

src/ft2font_wrapper.cpp

QuLogic · 2025-08-27T01:06:25Z

src/ft2font.cpp


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


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.

QuLogic · 2025-09-03T03:22:50Z

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.

tacaswell · 2025-09-19T13:53:11Z

doc/release/next_whats_new/text_language.rst

+    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',


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',

tacaswell · 2025-09-19T13:58:28Z

It looks like the appveyor tests hung.

QuLogic · 2025-09-20T03:27:59Z

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

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

5 tasks

QuLogic mentioned this pull request Apr 16, 2025

Fix signature of disabled draw methods #29923

Merged

1 task

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

5 tasks

QuLogic commented May 7, 2025

View reviewed changes

lib/matplotlib/_text_helpers.py Show resolved Hide resolved

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

src/ft2font_wrapper.cpp Outdated Show resolved Hide resolved

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

github-actions bot added topic: mplot3d status: needs rebase and removed status: needs rebase labels Aug 27, 2025

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



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

		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',

Uh oh!

Add language parameter to Text objects #29794

Add language parameter to Text objects #29794

Uh oh!

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

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

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