Add language parameter to Text objects

Author: QuLogic

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=None, kern_mode=Kerning.DEFAULT):
     """
     Render *string* with *font*.
 
@@ -56,6 +56,9 @@ def layout(string, font, *, kern_mode=Kerning.DEFAULT):
         The string to be rendered.
     font : FT2Font
         The font.
+    language : str or list of tuples of (str, int, int), optional
+        The language of the text in a format accepted by libraqm, namely `a BCP47
+        language code <https://www.w3.org/International/articles/language-tags/>`_.
     kern_mode : Kerning
         A FreeType kerning mode.
 
@@ -65,7 +68,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.
     base_font = font
     for char in string:
         # This has done the fallback logic

lib/matplotlib/backends/backend_agg.py

@@ -189,7 +189,8 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
         font = self._prepare_font(prop)
         # We pass '0' for angle here, since it will be rotated (in raster
         # space) in the following call to draw_text_image).
-        font.set_text(s, 0, flags=get_hinting_flag())
+        font.set_text(s, 0, flags=get_hinting_flag(),
+                      language=mtext.get_language() if mtext is not None else None)
         font.draw_glyphs_to_bitmap(
             antialiased=gc.get_antialiased())
         d = font.get_descent() / 64.0

lib/matplotlib/backends/backend_pdf.py

@@ -2338,6 +2338,7 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
             return self.draw_mathtext(gc, x, y, s, prop, angle)
 
         fontsize = prop.get_size_in_points()
+        language = mtext.get_language() if mtext is not None else None
 
         if mpl.rcParams['pdf.use14corefonts']:
             font = self._get_font_afm(prop)
@@ -2348,7 +2349,7 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
             fonttype = mpl.rcParams['pdf.fonttype']
 
         if gc.get_url() is not None:
-            font.set_text(s)
+            font.set_text(s, language=language)
             width, height = font.get_width_height()
             self.file._annotations[-1][1].append(_get_link_annotation(
                 gc, x, y, width / 64, height / 64, angle))
@@ -2382,7 +2383,8 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
             multibyte_glyphs = []
             prev_was_multibyte = True
             prev_font = font
-            for item in _text_helpers.layout(s, font, kern_mode=Kerning.UNFITTED):
+            for item in _text_helpers.layout(s, font, language=language,
+                                             kern_mode=Kerning.UNFITTED):
                 if _font_supports_glyph(fonttype, ord(item.char)):
                     if prev_was_multibyte or item.ft_object != prev_font:
                         singlebyte_chunks.append((item.ft_object, item.x, []))

lib/matplotlib/backends/backend_ps.py

@@ -795,9 +795,10 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
                 thisx += width * scale
 
         else:
+            language = mtext.get_language() if mtext is not None else None
             font = self._get_font_ttf(prop)
             self._character_tracker.track(font, s)
-            for item in _text_helpers.layout(s, font):
+            for item in _text_helpers.layout(s, font, language=language):
                 ps_name = (item.ft_object.postscript_name
                            .encode("ascii", "replace").decode("ascii"))
                 glyph_name = item.ft_object.get_glyph_name(item.glyph_idx)

lib/matplotlib/ft2font.pyi

@@ -236,7 +236,12 @@ class FT2Font(Buffer):
     def set_charmap(self, i: int) -> None: ...
     def set_size(self, ptsize: float, dpi: float) -> None: ...
     def set_text(
-        self, string: str, angle: float = ..., flags: LoadFlags = ...
+        self,
+        string: str,
+        angle: float = ...,
+        flags: LoadFlags = ...,
+        *,
+        language: str | list[tuple[str, int, int]] | None = ...,
     ) -> NDArray[np.float64]: ...
     @property
     def ascender(self) -> int: ...

lib/matplotlib/mpl-data/matplotlibrc

@@ -292,6 +292,11 @@
 ## for more information on text properties
 #text.color: black
 
+## The language of the text in a format accepted by libraqm, namely `a BCP47 # language
+## code <https://www.w3.org/International/articles/language-tags/>`_. If none, then no
+## particular language will be implied, and default font settings will be used.
+#text.language: none
+
 ## FreeType hinting flag ("foo" corresponds to FT_LOAD_FOO); may be one of the
 ## following (Proprietary Matplotlib-specific synonyms are given in parentheses,
 ## but their use is discouraged):

lib/matplotlib/rcsetup.py

@@ -1058,6 +1058,7 @@ def _convert_validator_spec(key, conv):
     "text.kerning_factor": validate_int,
     "text.antialiased":    validate_bool,
     "text.parse_math":     validate_bool,
+    "text.language":       validate_string_or_None,
 
     "mathtext.cal":            validate_font_properties,
     "mathtext.rm":             validate_font_properties,

lib/matplotlib/tests/test_ft2font.py

@@ -774,6 +774,27 @@ def test_ft2font_set_text():
     assert font.get_bitmap_offset() == (6, 0)
 
 
+def test_ft2font_language_invalid():
+    file = fm.findfont('DejaVu Sans')
+    font = ft2font.FT2Font(file, hinting_factor=1, _kerning_factor=0)
+    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')])
+
+
+def test_ft2font_language():
+    file = fm.findfont('DejaVu Sans')
+    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)])
+
+
 def test_ft2font_loading():
     file = fm.findfont('DejaVu Sans')
     font = ft2font.FT2Font(file, hinting_factor=1, _kerning_factor=0)

lib/matplotlib/tests/test_text.py

@@ -1190,3 +1190,19 @@ def test_ytick_rotation_mode():
         tick.set_rotation(angle)
 
     plt.subplots_adjust(left=0.4, right=0.6, top=.99, bottom=.01)
+
+
+def test_text_language_invalid():
+    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')])
+
+
+def test_text_language():
+    Text(0, 0, 'foo', language='en')
+    Text(0, 0, 'foo', language=[('en', 1, 2)])

lib/matplotlib/text.py

@@ -136,6 +136,7 @@ def __init__(self,
         super().__init__()
         self._x, self._y = x, y
         self._text = ''
+        self._language = None
         self._reset_visual_defaults(
             text=text,
             color=color,
@@ -1422,6 +1423,41 @@ def _va_for_angle(self, angle):
             return 'baseline' if anchor_at_left else 'top'
         return 'top' if anchor_at_left else 'baseline'
 
+    def get_language(self):
+        """Return the language this Text is in."""
+        return self._language
+
+    def set_language(self, language):
+        """
+        Set the language of the text.
+
+        Parameters
+        ----------
+        language : str or list[tuple[str, int, int]] or None
+            The language of the text in a format accepted by libraqm, namely `a BCP47
+            language code <https://www.w3.org/International/articles/language-tags/>`_.
+
+            If None, then defaults to :rc:`text.language`.
+        """
+        _api.check_isinstance((list, str, None), language=language)
+        language = mpl._val_or_rc(language, 'text.language')
+
+        if isinstance(language, list):
+            for val in language:
+                if not isinstance(val, tuple) or len(val) != 3:
+                    raise TypeError('language must be list of tuple, not {language!r}')
+                sublang, start, end = val
+                if not isinstance(sublang, str):
+                    raise TypeError(
+                        'sub-language specification must be str, not {sublang!r}')
+                if not isinstance(start, int):
+                    raise TypeError('start location must be int, not {start!r}')
+                if not isinstance(end, int):
+                    raise TypeError('end location must be int, not {end!r}')
+
+        self._language = language
+        self.stale = True
+
 
 class OffsetFrom:
     """Callable helper class for working with `Annotation`."""