Add font feature API to FontProperties and Text

Font features allow font designers to provide alternate glyphs or
shaping within a single font. These features may be accessed via special
tags corresponding to internal tables of glyphs.

The mplcairo backend supports font features via an elaborate re-use of
the font file path [1]. This commit adds the API to make this officially
supported in the main user API.

At this time, nothing in Matplotlib itself uses these settings, but
they will have an effect with libraqm.

[1] https://github.com/matplotlib/mplcairo/blob/v0.6.1/README.rst#font-formats-and-features

Author: QuLogic

Diff for: doc/users/next_whats_new/font_features.rst

@@ -0,0 +1,42 @@
+Specifying font feature tags
+----------------------------
+
+OpenType fonts may support feature tags that specify alternate glyph shapes or
+substitutions to be made optionally. The text API now supports setting a list of feature
+tags to be used with the associated font. Feature tags can be set/get with:
+
+- `matplotlib.text.Text.set_fontfeatures` / `matplotlib.text.Text.get_fontfeatures`
+- `matplotlib.font_manager.FontProperties.set_features` /
+  `matplotlib.font_manager.FontProperties.get_features`
+- Any API that creates a `.Text` object by passing the *fontfeatures* argument (e.g.,
+  ``plt.xlabel(..., fontfeatures=...)``)
+
+Font feature strings are eventually passed to HarfBuzz, and so all `string formats
+supported by hb_feature_from_string()
+<https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-feature-from-string>`__ are
+supported.
+
+For example, the default font ``DejaVu Sans`` enables Standard Ligatures (the ``'liga'``
+tag) by default, and also provides optional Discretionary Ligatures (the ``dlig`` tag.)
+These may be toggled with ``+`` or ``-``.
+
+.. plot::
+    :include-source:
+
+    fig = plt.figure(figsize=(7, 3))
+
+    fig.text(0.5, 0.85, 'Ligatures', fontsize=40, horizontalalignment='center')
+
+    # Default has Standard Ligatures (liga).
+    fig.text(0, 0.6, 'Default: fi ffi fl st', fontsize=40)
+
+    # Disable Standard Ligatures with -liga.
+    fig.text(0, 0.35, 'Disabled: fi ffi fl st', fontsize=40,
+             fontfeatures=['-liga'])
+
+    # Enable Discretionary Ligatures with dlig.
+    fig.text(0, 0.1, 'Discretionary: fi ffi fl st', fontsize=40,
+             fontfeatures=['dlig'])
+
+Available font feature tags may be found at
+https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist

Diff for: lib/matplotlib/backends/_backend_pdf_ps.py

@@ -181,6 +181,7 @@ def _get_font_ttf(self, prop):
             font = font_manager.get_font(fnames)
             font.clear()
             font.set_size(prop.get_size_in_points(), 72)
+            font.set_features(prop.get_features())
             return font
         except RuntimeError:
             logging.getLogger(__name__).warning(

Diff for: lib/matplotlib/backends/backend_agg.py

@@ -253,6 +253,7 @@ def _prepare_font(self, font_prop):
         font.clear()
         size = font_prop.get_size_in_points()
         font.set_size(size, self.dpi)
+        font.set_features(font_prop.get_features())
         return font
 
     def points_to_pixels(self, points):

Diff for: lib/matplotlib/font_manager.py

@@ -536,7 +536,7 @@ def afmFontProperty(fontpath, font):
 
 def _cleanup_fontproperties_init(init_method):
     """
-    A decorator to limit the call signature to single a positional argument
+    A decorator to limit the call signature to a single positional argument
     or alternatively only keyword arguments.
 
     We still accept but deprecate all other call signatures.
@@ -624,6 +624,13 @@ class FontProperties:
       Supported values are: 'dejavusans', 'dejavuserif', 'cm',
       'stix', 'stixsans' and 'custom'. Default: :rc:`mathtext.fontset`
 
+    - features: A list of advanced font feature tags to enable. Font features are a
+      component of OpenType fonts that allows picking from multiple stylistic variations
+      within a single font. This may include small caps, ligatures, alternate forms of
+      commonly-confused glyphs (e.g., capital I vs. lower-case l), and various other
+      options. A `list of feature tags may be found here
+      <https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist>`__.
+
     Alternatively, a font may be specified using the absolute path to a font
     file, by using the *fname* kwarg.  However, in this case, it is typically
     simpler to just pass the path (as a `pathlib.Path`, not a `str`) to the
@@ -657,7 +664,8 @@ class FontProperties:
     def __init__(self, family=None, style=None, variant=None, weight=None,
                  stretch=None, size=None,
                  fname=None,  # if set, it's a hardcoded filename to use
-                 math_fontfamily=None):
+                 math_fontfamily=None,
+                 features=None):
         self.set_family(family)
         self.set_style(style)
         self.set_variant(variant)
@@ -666,6 +674,7 @@ def __init__(self, family=None, style=None, variant=None, weight=None,
         self.set_file(fname)
         self.set_size(size)
         self.set_math_fontfamily(math_fontfamily)
+        self.set_features(features)
         # Treat family as a fontconfig pattern if it is the only parameter
         # provided.  Even in that case, call the other setters first to set
         # attributes not specified by the pattern to the rcParams defaults.
@@ -705,7 +714,8 @@ def __hash__(self):
              self.get_stretch(),
              self.get_size(),
              self.get_file(),
-             self.get_math_fontfamily())
+             self.get_math_fontfamily(),
+             self.get_features())
         return hash(l)
 
     def __eq__(self, other):
@@ -952,6 +962,41 @@ def set_math_fontfamily(self, fontfamily):
             _api.check_in_list(valid_fonts, math_fontfamily=fontfamily)
         self._math_fontfamily = fontfamily
 
+    def get_features(self):
+        """Return a tuple of font feature tags to enable."""
+        return self._features
+
+    def set_features(self, features):
+        """
+        Set the font feature tags to enable on this font.
+
+        Parameters
+        ----------
+        features : list[str]
+            A list of feature tags to be used with the associated font. These strings
+            are eventually passed to HarfBuzz, and so all `string formats supported by
+            hb_feature_from_string()
+            <https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-feature-from-string>`__
+            are supported.
+
+            For example, if your desired font includes Stylistic Sets which enable
+            various typographic alternates including one that you do not wish to use
+            (e.g., Contextual Ligatures), then you can pass the following to enable one
+            and not the other::
+
+                fp.set_features([
+                    'ss01',  # Use Stylistic Set 1.
+                    '-clig',  # But disable Contextural Ligatures.
+                ])
+
+            Available font feature tags may be found at
+            https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist
+        """
+        _api.check_isinstance((list, tuple, None), features=features)
+        if features is not None:
+            features = tuple(features)
+        self._features = features
+
     def copy(self):
         """Return a copy of self."""
         return copy.copy(self)

Diff for: lib/matplotlib/font_manager.pyi

@@ -52,6 +52,7 @@ class FontProperties:
         size: float | str | None = ...,
         fname: str | os.PathLike | Path | None = ...,
         math_fontfamily: str | None = ...,
+        features: list[str] | None = ...,
     ) -> None: ...
     def __hash__(self) -> int: ...
     def __eq__(self, other: object) -> bool: ...
@@ -76,6 +77,8 @@ class FontProperties:
     def set_fontconfig_pattern(self, pattern: str) -> None: ...
     def get_math_fontfamily(self) -> str: ...
     def set_math_fontfamily(self, fontfamily: str | None) -> None: ...
+    def get_features(self) -> tuple[str, ...]: ...
+    def set_features(self, features: list[str] | tuple[str, ...] | None) -> None: ...
     def copy(self) -> FontProperties: ...
     # Aliases
     set_name = set_family

Diff for: lib/matplotlib/ft2font.pyi

@@ -234,6 +234,7 @@ class FT2Font(Buffer):
     def load_glyph(self, glyphindex: int, flags: LoadFlags = ...) -> Glyph: ...
     def select_charmap(self, i: int) -> None: ...
     def set_charmap(self, i: int) -> None: ...
+    def set_features(self, features: tuple[str, ...]) -> None: ...
     def set_size(self, ptsize: float, dpi: float) -> None: ...
     def set_text(
         self, string: str, angle: float = ..., flags: LoadFlags = ...

Diff for: lib/matplotlib/tests/test_ft2font.py

@@ -198,6 +198,19 @@ def test_ft2font_set_size():
     assert font.get_width_height() == tuple(pytest.approx(2 * x, 1e-1) for x in orig)
 
 
+def test_ft2font_features():
+    # Smoke test that these are accepted as intended.
+    file = fm.findfont('DejaVu Sans')
+    font = ft2font.FT2Font(file)
+    font.set_features(None)  # unset
+    font.set_features(['calt', 'dlig'])  # list
+    font.set_features(('calt', 'dlig'))  # tuple
+    with pytest.raises(TypeError):
+        font.set_features(123)
+    with pytest.raises(TypeError):
+        font.set_features([123, 456])
+
+
 def test_ft2font_charmaps():
     def enc(name):
         # We don't expose the encoding enum from FreeType, but can generate it here.

Diff for: lib/matplotlib/text.py

@@ -847,6 +847,16 @@ def get_fontfamily(self):
         """
         return self._fontproperties.get_family()
 
+    def get_fontfeatures(self):
+        """
+        Return a tuple of font feature tags to enable.
+
+        See Also
+        --------
+        .font_manager.FontProperties.get_features
+        """
+        return self._fontproperties.get_features()
+
     def get_fontname(self):
         """
         Return the font name as a string.
@@ -1094,6 +1104,39 @@ def set_fontfamily(self, fontname):
         self._fontproperties.set_family(fontname)
         self.stale = True
 
+    def set_fontfeatures(self, features):
+        """
+        Set the feature tags to enable on the font.
+
+        Parameters
+        ----------
+        features : list[str]
+            A list of feature tags to be used with the associated font. These strings
+            are eventually passed to HarfBuzz, and so all `string formats supported by
+            hb_feature_from_string()
+            <https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-feature-from-string>`__
+            are supported.
+
+            For example, if your desired font includes Stylistic Sets which enable
+            various typographic alternates including one that you do not wish to use
+            (e.g., Contextual Ligatures), then you can pass the following to enable one
+            and not the other::
+
+                fp.set_features([
+                    'ss01',  # Use Stylistic Set 1.
+                    '-clig',  # But disable Contextural Ligatures.
+                ])
+
+            Available font feature tags may be found at
+            https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist
+
+        See Also
+        --------
+        .font_manager.FontProperties.set_features
+        """
+        self._fontproperties.set_features(features)
+        self.stale = True
+
     def set_fontvariant(self, variant):
         """
         Set the font variant.

Diff for: lib/matplotlib/text.pyi

@@ -56,6 +56,7 @@ class Text(Artist):
     def get_color(self) -> ColorType: ...
     def get_fontproperties(self) -> FontProperties: ...
     def get_fontfamily(self) -> list[str]: ...
+    def get_fontfeatures(self) -> tuple[str, ...] | None: ...
     def get_fontname(self) -> str: ...
     def get_fontstyle(self) -> Literal["normal", "italic", "oblique"]: ...
     def get_fontsize(self) -> float | str: ...
@@ -80,6 +81,7 @@ class Text(Artist):
     def set_multialignment(self, align: Literal["left", "center", "right"]) -> None: ...
     def set_linespacing(self, spacing: float) -> None: ...
     def set_fontfamily(self, fontname: str | Iterable[str]) -> None: ...
+    def set_fontfeatures(self, features: list[str] | tuple[str, ...] | None) -> None: ...
     def set_fontvariant(self, variant: Literal["normal", "small-caps"]) -> None: ...
     def set_fontstyle(
         self, fontstyle: Literal["normal", "italic", "oblique"]

Diff for: lib/matplotlib/textpath.py

@@ -34,6 +34,7 @@ def _get_font(self, prop):
         filenames = _fontManager._find_fonts_by_props(prop)
         font = get_font(filenames)
         font.set_size(self.FONT_SCALE, self.DPI)
+        font.set_features(prop.get_features())
         return font
 
     def _get_hinting_flag(self):

Diff for: src/ft2font.cpp

@@ -336,6 +336,11 @@ void FT2Font::set_size(double ptsize, double dpi)
     }
 }
 
+void FT2Font::set_features(std::vector<std::string> features)
+{
+    feature_tags = std::move(features);
+}
+
 void FT2Font::set_charmap(int i)
 {
     if (i >= face->num_charmaps) {

Diff for: src/ft2font.h

@@ -75,6 +75,7 @@ class FT2Font
     virtual ~FT2Font();
     void clear();
     void set_size(double ptsize, double dpi);
+    void set_features(std::vector<std::string> features);
     void set_charmap(int i);
     void select_charmap(unsigned long i);
     void set_text(std::u32string_view codepoints, double angle, FT_Int32 flags,
@@ -150,6 +151,7 @@ class FT2Font
     FT_Pos advance;
     long hinting_factor;
     int kerning_factor;
+    std::vector<std::string> feature_tags;
 
     // prevent copying
     FT2Font(const FT2Font &);

Diff for: src/ft2font_wrapper.cpp

@@ -534,6 +534,31 @@ PyFT2Font_set_size(PyFT2Font *self, double ptsize, double dpi)
     self->x->set_size(ptsize, dpi);
 }
 
+const char *PyFT2Font_set_features__doc__ = R"""(
+    Set the font feature tags used for the font.
+
+    Parameters
+    ----------
+    features : tuple[str, ...]
+        The font feature tags to use for the font.
+
+        Available font feature tags may be found at
+        https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist
+)""";
+
+static void
+PyFT2Font_set_features(PyFT2Font *self, py::object features_obj)
+{
+    std::vector<std::string> features;
+    if (!features_obj.is_none()) {
+        auto features_list = py::cast<py::tuple>(features_obj);
+        for (auto &feature : features_list) {
+            features.push_back(feature.cast<std::string>());
+        }
+    }
+    self->x->set_features(std::move(features));
+}
+
 const char *PyFT2Font_set_charmap__doc__ = R"""(
     Make the i-th charmap current.
 
@@ -1744,6 +1769,8 @@ PYBIND11_MODULE(ft2font, m, py::mod_gil_not_used())
         .def("clear", &PyFT2Font_clear, PyFT2Font_clear__doc__)
         .def("set_size", &PyFT2Font_set_size, "ptsize"_a, "dpi"_a,
              PyFT2Font_set_size__doc__)
+        .def("set_features", &PyFT2Font_set_features, "features"_a,
+             PyFT2Font_set_features__doc__)
         .def("set_charmap", &PyFT2Font_set_charmap, "i"_a,
              PyFT2Font_set_charmap__doc__)
         .def("select_charmap", &PyFT2Font_select_charmap, "i"_a,