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.

QuLogic · 2025-05-07T05:32:35Z

lib/matplotlib/_text_helpers.py

@@ -65,7 +65,7 @@ def layout(string, font, *, kern_mode=Kerning.DEFAULT):
    """
    x = 0
    prev_glyph_idx = None
-    char_to_font = font._get_fontmap(string)
+    char_to_font = font._get_fontmap(string)  # TODO: Pass in language.


Note, this function is getting rewritten with libraqm, so this is just a note for later.

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

lib/matplotlib/_text_helpers.py

@@ -43,7 +43,7 @@ def warn_on_missing_glyph(codepoint, fontnames):
            f"Matplotlib currently does not support {block} natively.")


-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-05-22T20:33:16Z

I've added a text.language rcParam as discussed on the call last week.

QuLogic · 2025-05-23T02:08:04Z

Also added a What's new note, though as with the other PR, it won't show the difference until libraqm is added.

story645 · 2025-06-06T21:17:57Z

doc/users/next_whats_new/text_language.rst

+    fig.text(0.5, 0.3, f'\\U{ord(char):08x}', fontsize=40, horizontalalignment='center')
+    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',
+             horizontalalignment='right')


can you add a (str, int, int) example just to cover all the forms?

I think we're not ready to expose that just yet, so it's not been documented.

story645 · 2025-06-06T21:22:47Z

lib/matplotlib/tests/test_ft2font.py

+    with pytest.raises(TypeError):
+        font.set_text('foo', language=[1, 2, 3])
+    with pytest.raises(TypeError):
+        font.set_text('foo', language=[(1, 2)])
+    with pytest.raises(TypeError):
+        font.set_text('foo', language=[('en', 'foo', 2)])
+    with pytest.raises(TypeError):
+        font.set_text('foo', language=[('en', 1, 'foo')])


can you parameterize so there are labels to make it clear what's wrong with each case?

story645 · 2025-06-06T21:23:52Z

lib/matplotlib/tests/test_ft2font.py

+    font = ft2font.FT2Font(file, hinting_factor=1, _kerning_factor=0)
+    font.set_text('foo')
+    font.set_text('foo', language='en')
+    font.set_text('foo', language=[('en', 1, 2)])


is this just testing it doesn't blow up? is there a .get_language to test that the setting didn't do anything strange?

Yes, smoke testing only; full tests come with libraqm.

story645 · 2025-06-06T21:24:51Z

lib/matplotlib/tests/test_text.py

+    with pytest.raises(TypeError, match='must be list of tuple'):
+        Text(0, 0, 'foo', language=[1, 2, 3])
+    with pytest.raises(TypeError, match='must be list of tuple'):
+        Text(0, 0, 'foo', language=[(1, 2)])
+    with pytest.raises(TypeError, match='start location must be int'):
+        Text(0, 0, 'foo', language=[('en', 'foo', 2)])
+    with pytest.raises(TypeError, match='end location must be int'):
+        Text(0, 0, 'foo', language=[('en', 1, 'foo')])


parameterize on match and language?

story645 · 2025-06-06T21:26:47Z

lib/matplotlib/text.py

+        _api.check_isinstance((list, str, None), language=language)
+        language = mpl._val_or_rc(language, 'text.language')
+
+        if isinstance(language, list):


restricted to list or is any iterable fine?

story645 · 2025-06-06T21:29:55Z

lib/matplotlib/tests/test_text.py

+    with pytest.raises(TypeError, match='must be list of tuple'):
+        Text(0, 0, 'foo', language=[1, 2, 3])
+    with pytest.raises(TypeError, match='must be list of tuple'):
+        Text(0, 0, 'foo', language=[(1, 2)])


this is a list of tuple

Yes, but the tuple is the wrong length (I just didn't write out the whole message in the match.)

story645 · 2025-06-06T21:32:48Z

lib/matplotlib/text.py

+        _api.check_isinstance((list, str, None), language=language)
+        language = mpl._val_or_rc(language, 'text.language')
+
+        if isinstance(language, list):


so does this mean that if language is a list it has to be a list where each element is a 3 tuple? so you can't do language = ['en', 'sr', 'ru']? which what would the list of tuple be used for?

No, that would not make sense, but it's understandable that it's not clear since it's purposely undocumented. If you provide multiple languages, then they would need to specify a range over which they apply.

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 FontProperties and Text #29695

Open

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

Draft

5 tasks

QuLogic commented May 7, 2025

View reviewed changes

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 the topic: rcparams label May 22, 2025

Add language parameter to Text objects

669ba8f

QuLogic force-pushed the text-language branch from 46c6239 to 669ba8f Compare May 23, 2025 00:30

github-actions bot added status: needs rebase and removed status: needs rebase labels May 29, 2025

QuLogic changed the base branch from main to text-overhaul June 5, 2025 01:38

QuLogic added this to Font and text overhaul Jun 5, 2025

QuLogic moved this to Ready for Review in Font and text overhaul Jun 5, 2025

story645 reviewed Jun 6, 2025

View reviewed changes

Uh oh!

Add language parameter to Text objects #29794

Are you sure you want to change the base?

Add language parameter to Text objects #29794

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

QuLogic commented May 22, 2025

Uh oh!

QuLogic commented May 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

QuLogic Jun 7, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

anntzer commented Mar 22, 2025 •

edited

Loading

QuLogic Jun 7, 2025 •

edited

Loading