Merge commit '56308afb3b0cfc0952148ade8fa918846a3f2419' into text-overhaul-figures-per-commit

Author: QuLogic

doc/api/next_api_changes/behavior/30318-ES.rst

@@ -0,0 +1,9 @@
+FT2Font no longer sets a default size
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the interest of handling non-scalable fonts and reducing font initialization, the
+`.FT2Font` constructor no longer sets a default size. Non-scalable fonts are sometimes
+used for bitmap-backed emoji fonts.
+
+If metrics are important (i.e., if you are loading character glyphs, or setting a text
+string), then explicitly call `.FT2Font.set_size` beforehand.

doc/api/next_api_changes/deprecations/30322-ES.rst

@@ -0,0 +1,7 @@
+Font kerning factor is deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Due to internal changes to support complex text rendering, the kerning factor on fonts is
+no longer used. Setting the ``text.kerning_factor`` rcParam (which existed only for
+backwards-compatibility) to any value other than None is deprecated, and the rcParam will
+be removed in the future.

doc/api/next_api_changes/deprecations/30329-ES.rst

@@ -0,0 +1,4 @@
+``font_manager.is_opentype_cff_font`` is deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is no replacement.

doc/api/next_api_changes/development/30143-ES.rst

@@ -0,0 +1,7 @@
+Glyph indices now typed distinctly from character codes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Previously, character codes and glyph indices were both typed as `int`, which means you
+could mix and match them erroneously. While the character code can't be made a distinct
+type (because it's used for `chr`/`ord`), typing glyph indices as a distinct type means
+these can't be fully swapped.

doc/users/prev_whats_new/whats_new_3.2.0.rst

@@ -52,26 +52,15 @@ triangle meshes.
 
 Kerning adjustments now use correct values
 ------------------------------------------
-Due to an error in how kerning adjustments were applied, previous versions of
-Matplotlib would under-correct kerning. This version will now correctly apply
-kerning (for fonts supported by FreeType). To restore the old behavior (e.g.,
-for test images), you may set :rc:`text.kerning_factor` to 6 (instead of 0).
-Other values have undefined behavior.
-
-.. plot::
-
-   import matplotlib.pyplot as plt
-
-   # Use old kerning values:
-   plt.rcParams['text.kerning_factor'] = 6
-   fig, ax = plt.subplots()
-   ax.text(0.0, 0.05, 'BRAVO\nAWKWARD\nVAT\nW.Test', fontsize=56)
-   ax.set_title('Before (text.kerning_factor = 6)')
-
-Note how the spacing between characters is uniform between their bounding boxes
-(above). With corrected kerning (below), slanted characters (e.g., AV or VA)
-will be spaced closer together, as well as various other character pairs,
-depending on font support (e.g., T and e, or the period after the W).
+Due to an error in how kerning adjustments were applied, previous versions of Matplotlib
+would under-correct kerning. This version will now correctly apply kerning (for fonts
+supported by FreeType). To restore the old behavior (e.g., for test images), you may set
+the ``text.kerning_factor`` rcParam to 6 (instead of 0). Other values have undefined
+behavior.
+
+With corrected kerning (below), slanted characters (e.g., AV or VA) will be spaced closer
+together, as well as various other character pairs, depending on font support (e.g., T
+and e, or the period after the W).
 
 .. plot::
 

lib/matplotlib/__init__.py

@@ -751,6 +751,8 @@ def __setitem__(self, key, val):
                 f"a list of valid parameters)") from err
         except ValueError as ve:
             raise ValueError(f"Key {key}: {ve}") from None
+        if key == "text.kerning_factor" and cval is not None:
+           _api.warn_deprecated("3.11", name="text.kerning_factor", obj_type="rcParam")
         self._set(key, cval)
 
     def __getitem__(self, key):

lib/matplotlib/_afm.py

@@ -30,9 +30,10 @@
 import inspect
 import logging
 import re
-from typing import BinaryIO, NamedTuple, TypedDict
+from typing import BinaryIO, NamedTuple, TypedDict, cast
 
 from ._mathtext_data import uni2type1
+from .ft2font import CharacterCodeType, GlyphIndexType
 
 
 _log = logging.getLogger(__name__)
@@ -197,7 +198,7 @@ class CharMetrics(NamedTuple):
     The bbox of the character (B) as a tuple (*llx*, *lly*, *urx*, *ury*)."""
 
 
-def _parse_char_metrics(fh: BinaryIO) -> tuple[dict[int, CharMetrics],
+def _parse_char_metrics(fh: BinaryIO) -> tuple[dict[CharacterCodeType, CharMetrics],
                                                dict[str, CharMetrics]]:
     """
     Parse the given filehandle for character metrics information.
@@ -218,7 +219,7 @@ def _parse_char_metrics(fh: BinaryIO) -> tuple[dict[int, CharMetrics],
     """
     required_keys = {'C', 'WX', 'N', 'B'}
 
-    ascii_d: dict[int, CharMetrics] = {}
+    ascii_d: dict[CharacterCodeType, CharMetrics] = {}
     name_d: dict[str, CharMetrics] = {}
     for bline in fh:
         # We are defensively letting values be utf8. The spec requires
@@ -409,19 +410,21 @@ def get_str_bbox_and_descent(self, s: str) -> tuple[int, int, float, int, int]:
 
         return left, miny, total_width, maxy - miny, -miny
 
-    def get_glyph_name(self, glyph_ind: int) -> str:  # For consistency with FT2Font.
+    def get_glyph_name(self,  # For consistency with FT2Font.
+                       glyph_ind: GlyphIndexType) -> str:
         """Get the name of the glyph, i.e., ord(';') is 'semicolon'."""
-        return self._metrics[glyph_ind].name
+        return self._metrics[cast(CharacterCodeType, glyph_ind)].name
 
-    def get_char_index(self, c: int) -> int:  # For consistency with FT2Font.
+    def get_char_index(self,  # For consistency with FT2Font.
+                       c: CharacterCodeType) -> GlyphIndexType:
         """
         Return the glyph index corresponding to a character code point.
 
         Note, for AFM fonts, we treat the glyph index the same as the codepoint.
         """
-        return c
+        return cast(GlyphIndexType, c)
 
-    def get_width_char(self, c: int) -> float:
+    def get_width_char(self, c: CharacterCodeType) -> float:
         """Get the width of the character code from the character metric WX field."""
         return self._metrics[c].width
 

lib/matplotlib/_mathtext.py

@@ -37,7 +37,8 @@
 
 if T.TYPE_CHECKING:
     from collections.abc import Iterable
-    from .ft2font import Glyph
+    from .ft2font import CharacterCodeType, Glyph
+
 
 ParserElement.enable_packrat()
 _log = logging.getLogger("matplotlib.mathtext")
@@ -47,7 +48,7 @@
 # FONTS
 
 
-def get_unicode_index(symbol: str) -> int:  # Publicly exported.
+def get_unicode_index(symbol: str) -> CharacterCodeType:  # Publicly exported.
     r"""
     Return the integer index (from the Unicode table) of *symbol*.
 
@@ -85,7 +86,7 @@ class VectorParse(NamedTuple):
     width: float
     height: float
     depth: float
-    glyphs: list[tuple[FT2Font, float, int, float, float]]
+    glyphs: list[tuple[FT2Font, float, CharacterCodeType, float, float]]
     rects: list[tuple[float, float, float, float]]
 
 VectorParse.__module__ = "matplotlib.mathtext"
@@ -212,7 +213,7 @@ class FontInfo(NamedTuple):
     fontsize: float
     postscript_name: str
     metrics: FontMetrics
-    num: int
+    num: CharacterCodeType
     glyph: Glyph
     offset: float
 
@@ -365,7 +366,7 @@ def _get_offset(self, font: FT2Font, glyph: Glyph, fontsize: float,
         return 0.
 
     def _get_glyph(self, fontname: str, font_class: str,
-                   sym: str) -> tuple[FT2Font, int, bool]:
+                   sym: str) -> tuple[FT2Font, CharacterCodeType, bool]:
         raise NotImplementedError
 
     # The return value of _get_info is cached per-instance.
@@ -425,7 +426,9 @@ def get_kern(self, font1: str, fontclass1: str, sym1: str, fontsize1: float,
             info1 = self._get_info(font1, fontclass1, sym1, fontsize1, dpi)
             info2 = self._get_info(font2, fontclass2, sym2, fontsize2, dpi)
             font = info1.font
-            return font.get_kerning(info1.num, info2.num, Kerning.DEFAULT) / 64
+            return font.get_kerning(font.get_char_index(info1.num),
+                                    font.get_char_index(info2.num),
+                                    Kerning.DEFAULT) / 64
         return super().get_kern(font1, fontclass1, sym1, fontsize1,
                                 font2, fontclass2, sym2, fontsize2, dpi)
 
@@ -459,7 +462,7 @@ def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlag
     _slanted_symbols = set(r"\int \oint".split())
 
     def _get_glyph(self, fontname: str, font_class: str,
-                   sym: str) -> tuple[FT2Font, int, bool]:
+                   sym: str) -> tuple[FT2Font, CharacterCodeType, bool]:
         font = None
         if fontname in self.fontmap and sym in latex_to_bakoma:
             basename, num = latex_to_bakoma[sym]
@@ -551,7 +554,7 @@ class UnicodeFonts(TruetypeFonts):
     # Some glyphs are not present in the `cmr10` font, and must be brought in
     # from `cmsy10`. Map the Unicode indices of those glyphs to the indices at
     # which they are found in `cmsy10`.
-    _cmr10_substitutions = {
+    _cmr10_substitutions: dict[CharacterCodeType, CharacterCodeType] = {
         0x00D7: 0x00A3,  # Multiplication sign.
         0x2212: 0x00A1,  # Minus sign.
     }
@@ -594,11 +597,11 @@ def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlag
     _slanted_symbols = set(r"\int \oint".split())
 
     def _map_virtual_font(self, fontname: str, font_class: str,
-                          uniindex: int) -> tuple[str, int]:
+                          uniindex: CharacterCodeType) -> tuple[str, CharacterCodeType]:
         return fontname, uniindex
 
     def _get_glyph(self, fontname: str, font_class: str,
-                   sym: str) -> tuple[FT2Font, int, bool]:
+                   sym: str) -> tuple[FT2Font, CharacterCodeType, bool]:
         try:
             uniindex = get_unicode_index(sym)
             found_symbol = True
@@ -607,8 +610,7 @@ def _get_glyph(self, fontname: str, font_class: str,
             found_symbol = False
             _log.warning("No TeX to Unicode mapping for %a.", sym)
 
-        fontname, uniindex = self._map_virtual_font(
-            fontname, font_class, uniindex)
+        fontname, uniindex = self._map_virtual_font(fontname, font_class, uniindex)
 
         new_fontname = fontname
 
@@ -693,7 +695,7 @@ def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlag
             self.fontmap[name] = fullpath
 
     def _get_glyph(self, fontname: str, font_class: str,
-                   sym: str) -> tuple[FT2Font, int, bool]:
+                   sym: str) -> tuple[FT2Font, CharacterCodeType, bool]:
         # Override prime symbol to use Bakoma.
         if sym == r'\prime':
             return self.bakoma._get_glyph(fontname, font_class, sym)
@@ -783,7 +785,7 @@ def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlag
             self.fontmap[name] = fullpath
 
     def _map_virtual_font(self, fontname: str, font_class: str,
-                          uniindex: int) -> tuple[str, int]:
+                          uniindex: CharacterCodeType) -> tuple[str, CharacterCodeType]:
         # Handle these "fonts" that are actually embedded in
         # other fonts.
         font_mapping = stix_virtual_fonts.get(fontname)
@@ -1170,7 +1172,7 @@ def __init__(self, elements: T.Sequence[Node]):
         self.glue_sign    = 0    # 0: normal, -1: shrinking, 1: stretching
         self.glue_order   = 0    # The order of infinity (0 - 3) for the glue
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "{}<w={:.02f} h={:.02f} d={:.02f} s={:.02f}>[{}]".format(
             super().__repr__(),
             self.width, self.height,

lib/matplotlib/_mathtext_data.py

@@ -3,9 +3,12 @@
 """
 
 from __future__ import annotations
-from typing import overload
+from typing import TypeAlias, overload
 
-latex_to_bakoma = {
+from .ft2font import CharacterCodeType
+
+
+latex_to_bakoma: dict[str, tuple[str, CharacterCodeType]] = {
     '\\__sqrt__'                 : ('cmex10', 0x70),
     '\\bigcap'                   : ('cmex10', 0x5c),
     '\\bigcup'                   : ('cmex10', 0x5b),
@@ -241,7 +244,7 @@
 
 # Automatically generated.
 
-type12uni = {
+type12uni: dict[str, CharacterCodeType] = {
     'aring'          : 229,
     'quotedblright'  : 8221,
     'V'              : 86,
@@ -475,7 +478,7 @@
 #  for key in sd:
 #      print("{0:24} : {1: <s},".format("'" + key + "'", sd[key]))
 
-tex2uni = {
+tex2uni: dict[str, CharacterCodeType] = {
     '#'                      : 0x23,
     '$'                      : 0x24,
     '%'                      : 0x25,
@@ -1113,8 +1116,9 @@
 # Each element is a 4-tuple of the form:
 #   src_start, src_end, dst_font, dst_start
 
-_EntryTypeIn = tuple[str, str, str, str | int]
-_EntryTypeOut = tuple[int, int, str, int]
+_EntryTypeIn: TypeAlias = tuple[str, str, str, str | CharacterCodeType]
+_EntryTypeOut: TypeAlias = tuple[CharacterCodeType, CharacterCodeType, str,
+                                 CharacterCodeType]
 
 _stix_virtual_fonts: dict[str, dict[str, list[_EntryTypeIn]] | list[_EntryTypeIn]] = {
     'bb': {
@@ -1735,7 +1739,7 @@ def _normalize_stix_fontcodes(d):
 del _stix_virtual_fonts
 
 # Fix some incorrect glyphs.
-stix_glyph_fixes = {
+stix_glyph_fixes: dict[CharacterCodeType, CharacterCodeType] = {
     # Cap and Cup glyphs are swapped.
     0x22d2: 0x22d3,
     0x22d3: 0x22d2,

lib/matplotlib/_text_helpers.py

@@ -7,14 +7,14 @@
 import dataclasses
 
 from . import _api
-from .ft2font import FT2Font, Kerning, LoadFlags
+from .ft2font import FT2Font, GlyphIndexType, Kerning, LoadFlags
 
 
 @dataclasses.dataclass(frozen=True)
 class LayoutItem:
     ft_object: FT2Font
     char: str
-    glyph_idx: int
+    glyph_idx: GlyphIndexType
     x: float
     prev_kern: float