ft2font: Convert flag properties to enums

QuLogic · QuLogic · commit 2096a3a6e9a0 · 2024-10-11T20:17:10.000-04:00
diff --git a/doc/api/next_api_changes/deprecations/28842-ES.rst b/doc/api/next_api_changes/deprecations/28842-ES.rst
@@ -34,3 +34,22 @@ prefix):
 - ``LOAD_TARGET_MONO``
 - ``LOAD_TARGET_LCD``
 - ``LOAD_TARGET_LCD_V``
+
+The following constants are now part of `.ft2font.FaceFlags`:
+
+- ``EXTERNAL_STREAM``
+- ``FAST_GLYPHS``
+- ``FIXED_SIZES``
+- ``FIXED_WIDTH``
+- ``GLYPH_NAMES``
+- ``HORIZONTAL``
+- ``KERNING``
+- ``MULTIPLE_MASTERS``
+- ``SCALABLE``
+- ``SFNT``
+- ``VERTICAL``
+
+The following constants are now part of `.ft2font.StyleFlags`:
+
+- ``ITALIC``
+- ``BOLD``
diff --git a/galleries/examples/misc/ftface_props.py b/galleries/examples/misc/ftface_props.py
@@ -46,18 +46,10 @@
     # vertical thickness of the underline
     print('Underline thickness:', font.underline_thickness)
 
-for style in ('Italic',
-              'Bold',
-              'Scalable',
-              'Fixed sizes',
-              'Fixed width',
-              'SFNT',
-              'Horizontal',
-              'Vertical',
-              'Kerning',
-              'Fast glyphs',
-              'Multiple masters',
-              'Glyph names',
-              'External stream'):
-    bitpos = getattr(ft, style.replace(' ', '_').upper()) - 1
-    print(f"{style+':':17}", bool(font.style_flags & (1 << bitpos)))
+for flag in ft.StyleFlags:
+    name = flag.name.replace('_', ' ').title() + ':'
+    print(f"{name:17}", flag in font.style_flags)
+
+for flag in ft.FaceFlags:
+    name = flag.name.replace('_', ' ').title() + ':'
+    print(f"{name:17}", flag in font.face_flags)
diff --git a/lib/matplotlib/backends/backend_pdf.py b/lib/matplotlib/backends/backend_pdf.py
@@ -35,7 +35,7 @@
 from matplotlib.figure import Figure
 from matplotlib.font_manager import get_font, fontManager as _fontManager
 from matplotlib._afm import AFM
-from matplotlib.ft2font import FIXED_WIDTH, ITALIC, FT2Font, Kerning, LoadFlags
+from matplotlib.ft2font import FT2Font, FaceFlags, Kerning, LoadFlags, StyleFlags
 from matplotlib.transforms import Affine2D, BboxBase
 from matplotlib.path import Path
 from matplotlib.dates import UTC
@@ -1416,15 +1416,15 @@ def embedTTFType42(font, characters, descriptor):
 
         flags = 0
         symbolic = False  # ps_name.name in ('Cmsy10', 'Cmmi10', 'Cmex10')
-        if ff & FIXED_WIDTH:
+        if FaceFlags.FIXED_WIDTH in ff:
             flags |= 1 << 0
         if 0:  # TODO: serif
             flags |= 1 << 1
         if symbolic:
             flags |= 1 << 2
         else:
             flags |= 1 << 5
-        if sf & ITALIC:
+        if StyleFlags.ITALIC in sf:
             flags |= 1 << 6
         if 0:  # TODO: all caps
             flags |= 1 << 16
diff --git a/lib/matplotlib/font_manager.py b/lib/matplotlib/font_manager.py
@@ -379,7 +379,7 @@ def ttfFontProperty(font):
         style = 'italic'
     elif sfnt2.find('regular') >= 0:
         style = 'normal'
-    elif font.style_flags & ft2font.ITALIC:
+    elif ft2font.StyleFlags.ITALIC in font.style_flags:
         style = 'italic'
     else:
         style = 'normal'
@@ -428,7 +428,7 @@ def get_weight():  # From fontconfig's FcFreeTypeQueryFaceInternal.
             for regex, weight in _weight_regexes:
                 if re.search(regex, style, re.I):
                     return weight
-        if font.style_flags & ft2font.BOLD:
+        if ft2font.StyleFlags.BOLD in font.style_flags:
             return 700  # "bold"
         return 500  # "medium", not "regular"!
 
diff --git a/lib/matplotlib/ft2font.pyi b/lib/matplotlib/ft2font.pyi
@@ -8,19 +8,27 @@ from numpy.typing import NDArray
 
 __freetype_build_type__: str
 __freetype_version__: str
-BOLD: int
-EXTERNAL_STREAM: int
-FAST_GLYPHS: int
-FIXED_SIZES: int
-FIXED_WIDTH: int
-GLYPH_NAMES: int
-HORIZONTAL: int
-ITALIC: int
-KERNING: int
-MULTIPLE_MASTERS: int
-SCALABLE: int
-SFNT: int
-VERTICAL: int
+
+class FaceFlags(Flag):
+    SCALABLE: int
+    FIXED_SIZES: int
+    FIXED_WIDTH: int
+    SFNT: int
+    HORIZONTAL: int
+    VERTICAL: int
+    KERNING: int
+    FAST_GLYPHS: int
+    MULTIPLE_MASTERS: int
+    GLYPH_NAMES: int
+    EXTERNAL_STREAM: int
+    HINTER: int
+    CID_KEYED: int
+    TRICKY: int
+    COLOR: int
+    # VARIATION: int  # FT 2.9
+    # SVG: int  # FT 2.12
+    # SBIX: int  # FT 2.12
+    # SBIX_OVERLAY: int  # FT 2.12
 
 class Kerning(Enum):
     DEFAULT: int
@@ -54,6 +62,11 @@ class LoadFlags(Flag):
     TARGET_LCD: int
     TARGET_LCD_V: int
 
+class StyleFlags(Flag):
+    NORMAL: int
+    ITALIC: int
+    BOLD: int
+
 class _SfntHeadDict(TypedDict):
     version: tuple[int, int]
     fontRevision: tuple[int, int]
@@ -232,7 +245,7 @@ class FT2Font(Buffer):
     @property
     def descender(self) -> int: ...
     @property
-    def face_flags(self) -> int: ...
+    def face_flags(self) -> FaceFlags: ...
     @property
     def family_name(self) -> str: ...
     @property
@@ -256,7 +269,7 @@ class FT2Font(Buffer):
     @property
     def scalable(self) -> bool: ...
     @property
-    def style_flags(self) -> int: ...
+    def style_flags(self) -> StyleFlags: ...
     @property
     def style_name(self) -> str: ...
     @property
diff --git a/lib/matplotlib/tests/test_ft2font.py b/lib/matplotlib/tests/test_ft2font.py
@@ -44,10 +44,11 @@ def test_ft2font_dejavu_attrs():
     assert font.num_fixed_sizes == 0  # All glyphs are scalable.
     assert font.num_charmaps == 5
     # Other internal flags are set, so only check the ones we're allowed to test.
-    expected_flags = (ft2font.SCALABLE | ft2font.SFNT | ft2font.HORIZONTAL |
-                      ft2font.KERNING | ft2font.GLYPH_NAMES)
-    assert (font.face_flags & expected_flags) == expected_flags
-    assert font.style_flags == 0  # Not italic or bold.
+    expected_flags = (ft2font.FaceFlags.SCALABLE | ft2font.FaceFlags.SFNT |
+                      ft2font.FaceFlags.HORIZONTAL | ft2font.FaceFlags.KERNING |
+                      ft2font.FaceFlags.GLYPH_NAMES)
+    assert expected_flags in font.face_flags
+    assert font.style_flags == ft2font.StyleFlags.NORMAL
     assert font.scalable
     # From FontForge: Font Information → General tab → entry name below.
     assert font.units_per_EM == 2048  # Em Size.
@@ -76,10 +77,10 @@ def test_ft2font_cm_attrs():
     assert font.num_fixed_sizes == 0  # All glyphs are scalable.
     assert font.num_charmaps == 2
     # Other internal flags are set, so only check the ones we're allowed to test.
-    expected_flags = (ft2font.SCALABLE | ft2font.SFNT | ft2font.HORIZONTAL |
-                      ft2font.GLYPH_NAMES)
-    assert (font.face_flags & expected_flags) == expected_flags, font.face_flags
-    assert font.style_flags == 0  # Not italic or bold.
+    expected_flags = (ft2font.FaceFlags.SCALABLE | ft2font.FaceFlags.SFNT |
+                      ft2font.FaceFlags.HORIZONTAL | ft2font.FaceFlags.GLYPH_NAMES)
+    assert expected_flags in font.face_flags
+    assert font.style_flags == ft2font.StyleFlags.NORMAL
     assert font.scalable
     # From FontForge: Font Information → General tab → entry name below.
     assert font.units_per_EM == 2048  # Em Size.
@@ -108,10 +109,10 @@ def test_ft2font_stix_bold_attrs():
     assert font.num_fixed_sizes == 0  # All glyphs are scalable.
     assert font.num_charmaps == 3
     # Other internal flags are set, so only check the ones we're allowed to test.
-    expected_flags = (ft2font.SCALABLE | ft2font.SFNT | ft2font.HORIZONTAL |
-                      ft2font.GLYPH_NAMES)
-    assert (font.face_flags & expected_flags) == expected_flags, font.face_flags
-    assert font.style_flags == ft2font.BOLD
+    expected_flags = (ft2font.FaceFlags.SCALABLE | ft2font.FaceFlags.SFNT |
+                      ft2font.FaceFlags.HORIZONTAL | ft2font.FaceFlags.GLYPH_NAMES)
+    assert expected_flags in font.face_flags
+    assert font.style_flags == ft2font.StyleFlags.BOLD
     assert font.scalable
     # From FontForge: Font Information → General tab → entry name below.
     assert font.units_per_EM == 1000  # Em Size.
diff --git a/src/ft2font_wrapper.cpp b/src/ft2font_wrapper.cpp
@@ -33,6 +33,74 @@ P11X_DECLARE_ENUM(
     {"UNSCALED", FT_KERNING_UNSCALED},
 );
 
+const char *FaceFlags__doc__ = R"""(
+    Flags returned by `FT2Font.face_flags`.
+
+    For more information, see `the FreeType documentation
+    <https://freetype.org/freetype2/docs/reference/ft2-face_creation.html#ft_face_flag_xxx>`_.
+
+    .. versionadded:: 3.10
+)""";
+
+enum class FaceFlags : FT_Long {
+#define DECLARE_FLAG(name) name = FT_FACE_FLAG_##name
+    DECLARE_FLAG(SCALABLE),
+    DECLARE_FLAG(FIXED_SIZES),
+    DECLARE_FLAG(FIXED_WIDTH),
+    DECLARE_FLAG(SFNT),
+    DECLARE_FLAG(HORIZONTAL),
+    DECLARE_FLAG(VERTICAL),
+    DECLARE_FLAG(KERNING),
+    DECLARE_FLAG(FAST_GLYPHS),
+    DECLARE_FLAG(MULTIPLE_MASTERS),
+    DECLARE_FLAG(GLYPH_NAMES),
+    DECLARE_FLAG(EXTERNAL_STREAM),
+    DECLARE_FLAG(HINTER),
+    DECLARE_FLAG(CID_KEYED),
+    DECLARE_FLAG(TRICKY),
+    DECLARE_FLAG(COLOR),
+#ifdef FT_FACE_FLAG_VARIATION  // backcompat: ft 2.9.0.
+    DECLARE_FLAG(VARIATION),
+#endif
+#ifdef FT_FACE_FLAG_SVG  // backcompat: ft 2.12.0.
+    DECLARE_FLAG(SVG),
+#endif
+#ifdef FT_FACE_FLAG_SBIX  // backcompat: ft 2.12.0.
+    DECLARE_FLAG(SBIX),
+#endif
+#ifdef FT_FACE_FLAG_SBIX_OVERLAY  // backcompat: ft 2.12.0.
+    DECLARE_FLAG(SBIX_OVERLAY),
+#endif
+#undef DECLARE_FLAG
+};
+
+P11X_DECLARE_ENUM(
+    "FaceFlags", "Flag",
+    {"SCALABLE", FaceFlags::SCALABLE},
+    {"FIXED_SIZES", FaceFlags::FIXED_SIZES},
+    {"FIXED_WIDTH", FaceFlags::FIXED_WIDTH},
+    {"SFNT", FaceFlags::SFNT},
+    {"HORIZONTAL", FaceFlags::HORIZONTAL},
+    {"VERTICAL", FaceFlags::VERTICAL},
+    {"KERNING", FaceFlags::KERNING},
+    {"FAST_GLYPHS", FaceFlags::FAST_GLYPHS},
+    {"MULTIPLE_MASTERS", FaceFlags::MULTIPLE_MASTERS},
+    {"GLYPH_NAMES", FaceFlags::GLYPH_NAMES},
+    {"EXTERNAL_STREAM", FaceFlags::EXTERNAL_STREAM},
+    {"HINTER", FaceFlags::HINTER},
+    {"CID_KEYED", FaceFlags::CID_KEYED},
+    {"TRICKY", FaceFlags::TRICKY},
+    {"COLOR", FaceFlags::COLOR},
+    // backcompat: ft 2.9.0.
+    // {"VARIATION", FaceFlags::VARIATION},
+    // backcompat: ft 2.12.0.
+    // {"SVG", FaceFlags::SVG},
+    // backcompat: ft 2.12.0.
+    // {"SBIX", FaceFlags::SBIX},
+    // backcompat: ft 2.12.0.
+    // {"SBIX_OVERLAY", FaceFlags::SBIX_OVERLAY},
+);
+
 const char *LoadFlags__doc__ = R"""(
     Flags for `FT2Font.load_char`, `FT2Font.load_glyph`, and `FT2Font.set_text`.
 
@@ -110,6 +178,30 @@ P11X_DECLARE_ENUM(
     {"TARGET_LCD_V", LoadFlags::TARGET_LCD_V},
 );
 
+const char *StyleFlags__doc__ = R"""(
+    Flags returned by `FT2Font.style_flags`.
+
+    For more information, see `the FreeType documentation
+    <https://freetype.org/freetype2/docs/reference/ft2-face_creation.html#ft_style_flag_xxx>`_.
+
+    .. versionadded:: 3.10
+)""";
+
+enum class StyleFlags : FT_Long {
+#define DECLARE_FLAG(name) name = FT_STYLE_FLAG_##name
+    NORMAL = 0,
+    DECLARE_FLAG(ITALIC),
+    DECLARE_FLAG(BOLD),
+#undef DECLARE_FLAG
+};
+
+P11X_DECLARE_ENUM(
+    "StyleFlags", "Flag",
+    {"NORMAL", StyleFlags::NORMAL},
+    {"ITALIC", StyleFlags::ITALIC},
+    {"BOLD", StyleFlags::BOLD},
+);
+
 /**********************************************************************
  * FT2Image
  * */
@@ -1339,16 +1431,16 @@ PyFT2Font_style_name(PyFT2Font *self)
     return name;
 }
 
-static FT_Long
+static FaceFlags
 PyFT2Font_face_flags(PyFT2Font *self)
 {
-    return self->x->get_face()->face_flags;
+    return static_cast<FaceFlags>(self->x->get_face()->face_flags);
 }
 
-static FT_Long
+static StyleFlags
 PyFT2Font_style_flags(PyFT2Font *self)
 {
-    return self->x->get_face()->style_flags;
+    return static_cast<StyleFlags>(self->x->get_face()->style_flags);
 }
 
 static FT_Long
@@ -1495,6 +1587,20 @@ ft2font__getattr__(std::string name) {
     DEPRECATE_ATTR_FROM_FLAG(LOAD_TARGET_LCD, LoadFlags, TARGET_LCD);
     DEPRECATE_ATTR_FROM_FLAG(LOAD_TARGET_LCD_V, LoadFlags, TARGET_LCD_V);
 
+    DEPRECATE_ATTR_FROM_FLAG(SCALABLE, FaceFlags, SCALABLE);
+    DEPRECATE_ATTR_FROM_FLAG(FIXED_SIZES, FaceFlags, FIXED_SIZES);
+    DEPRECATE_ATTR_FROM_FLAG(FIXED_WIDTH, FaceFlags, FIXED_WIDTH);
+    DEPRECATE_ATTR_FROM_FLAG(SFNT, FaceFlags, SFNT);
+    DEPRECATE_ATTR_FROM_FLAG(HORIZONTAL, FaceFlags, HORIZONTAL);
+    DEPRECATE_ATTR_FROM_FLAG(VERTICAL, FaceFlags, VERTICAL);
+    DEPRECATE_ATTR_FROM_FLAG(KERNING, FaceFlags, KERNING);
+    DEPRECATE_ATTR_FROM_FLAG(FAST_GLYPHS, FaceFlags, FAST_GLYPHS);
+    DEPRECATE_ATTR_FROM_FLAG(MULTIPLE_MASTERS, FaceFlags, MULTIPLE_MASTERS);
+    DEPRECATE_ATTR_FROM_FLAG(GLYPH_NAMES, FaceFlags, GLYPH_NAMES);
+    DEPRECATE_ATTR_FROM_FLAG(EXTERNAL_STREAM, FaceFlags, EXTERNAL_STREAM);
+
+    DEPRECATE_ATTR_FROM_FLAG(ITALIC, StyleFlags, ITALIC);
+    DEPRECATE_ATTR_FROM_FLAG(BOLD, StyleFlags, BOLD);
 #undef DEPRECATE_ATTR_FROM_FLAG
 
     throw py::attribute_error(
@@ -1514,6 +1620,8 @@ PYBIND11_MODULE(ft2font, m)
     p11x::bind_enums(m);
     p11x::enums["Kerning"].attr("__doc__") = Kerning__doc__;
     p11x::enums["LoadFlags"].attr("__doc__") = LoadFlags__doc__;
+    p11x::enums["FaceFlags"].attr("__doc__") = FaceFlags__doc__;
+    p11x::enums["StyleFlags"].attr("__doc__") = StyleFlags__doc__;
 
     py::class_<FT2Image>(m, "FT2Image", py::is_final(), py::buffer_protocol(),
                          PyFT2Image__doc__)
@@ -1613,9 +1721,9 @@ PYBIND11_MODULE(ft2font, m)
         .def_property_readonly("style_name", &PyFT2Font_style_name,
                                "Style name.")
         .def_property_readonly("face_flags", &PyFT2Font_face_flags,
-                               "Face flags; see the ft2font constants.")
+                               "Face flags; see `.FaceFlags`.")
         .def_property_readonly("style_flags", &PyFT2Font_style_flags,
-                               "Style flags; see the ft2font constants.")
+                               "Style flags; see `.StyleFlags`.")
         .def_property_readonly("num_glyphs", &PyFT2Font_num_glyphs,
                                "Number of glyphs in the face.")
         .def_property_readonly("num_fixed_sizes", &PyFT2Font_num_fixed_sizes,
@@ -1657,17 +1765,4 @@ PYBIND11_MODULE(ft2font, m)
     m.attr("__freetype_version__") = version_string;
     m.attr("__freetype_build_type__") = FREETYPE_BUILD_TYPE;
     m.def("__getattr__", ft2font__getattr__);
-    m.attr("SCALABLE") = FT_FACE_FLAG_SCALABLE;
-    m.attr("FIXED_SIZES") = FT_FACE_FLAG_FIXED_SIZES;
-    m.attr("FIXED_WIDTH") = FT_FACE_FLAG_FIXED_WIDTH;
-    m.attr("SFNT") = FT_FACE_FLAG_SFNT;
-    m.attr("HORIZONTAL") = FT_FACE_FLAG_HORIZONTAL;
-    m.attr("VERTICAL") = FT_FACE_FLAG_VERTICAL;
-    m.attr("KERNING") = FT_FACE_FLAG_KERNING;
-    m.attr("FAST_GLYPHS") = FT_FACE_FLAG_FAST_GLYPHS;
-    m.attr("MULTIPLE_MASTERS") = FT_FACE_FLAG_MULTIPLE_MASTERS;
-    m.attr("GLYPH_NAMES") = FT_FACE_FLAG_GLYPH_NAMES;
-    m.attr("EXTERNAL_STREAM") = FT_FACE_FLAG_EXTERNAL_STREAM;
-    m.attr("ITALIC") = FT_STYLE_FLAG_ITALIC;
-    m.attr("BOLD") = FT_STYLE_FLAG_BOLD;
 }
