Implment loading of any font in a collection

For backwards-compatibility, the path+index is passed around in a
lightweight subclass of `str`.

Author: QuLogic

lib/matplotlib/font_manager.py

@@ -310,6 +310,19 @@ def findSystemFonts(fontpaths=None, fontext='ttf'):
     return [fname for fname in fontfiles if os.path.exists(fname)]
 
 
+class FontPath(str):
+    __match_args__ = ('path', 'face_index')
+
+    def __new__(cls, path, face_index):
+        ret = super().__new__(cls, path)
+        ret.face_index = face_index
+        return ret
+
+    @property
+    def path(self):
+        return str(self)
+
+
 @dataclasses.dataclass(frozen=True)
 class FontEntry:
     """
@@ -1542,7 +1555,7 @@ def _findfont_cached(self, prop, fontext, directory, fallback_to_default,
                 # actually raised.
                 return cbook._ExceptionInfo(ValueError, "No valid font could be found")
 
-        return _cached_realpath(result)
+        return FontPath(_cached_realpath(result), best_font.index)
 
 
 @_api.deprecated("3.11")
@@ -1618,8 +1631,9 @@ def get_font(font_filepaths, hinting_factor=None):
 
     Parameters
     ----------
-    font_filepaths : Iterable[str, Path, bytes, tuple[str | Path | bytes, int]], \
-str, Path, bytes, tuple[str | Path | bytes, int]
+    font_filepaths : Iterable[str, Path, bytes, FontPath, \
+tuple[str | Path | bytes, int, FontPath]], \
+str, Path, bytes, FontPath, tuple[str | Path | bytes, int]
         Relative or absolute paths to the font files to be used.
 
         If a single string, bytes, or `pathlib.Path`, then it will be treated
@@ -1635,14 +1649,17 @@ def get_font(font_filepaths, hinting_factor=None):
 
     """
     match font_filepaths:
+        case FontPath(path, index):
+            paths = ((_cached_realpath(path), index), )
         case str() | Path() | bytes() as path:
             paths = ((_cached_realpath(path), 0), )
         case (str() | Path() | bytes() as path, int() as index):
             paths = ((_cached_realpath(path), index), )
         case _:
             paths = tuple(
                 (_cached_realpath(fname[0]), fname[1]) if isinstance(fname, tuple)
-                else (_cached_realpath(fname), 0)
+                else (_cached_realpath(fname.path), fname.face_index)
+                if isinstance(fname, FontPath) else (_cached_realpath(fname), 0)
                 for fname in font_filepaths)
 
     hinting_factor = mpl._val_or_rc(hinting_factor, 'text.hinting_factor')

lib/matplotlib/font_manager.pyi

@@ -28,6 +28,13 @@ def _get_fontconfig_fonts() -> list[Path]: ...
 def findSystemFonts(
     fontpaths: Iterable[str | os.PathLike | Path] | None = ..., fontext: str = ...
 ) -> list[str]: ...
+
+class FontPath(str):
+    face_index: int
+    def __new__(cls: type[str], path: str, face_index: int) -> FontPath: ...
+    @property
+    def path(self) -> str: ...
+
 @dataclass
 class FontEntry:
     fname: str = ...
@@ -117,12 +124,12 @@ class FontManager:
         directory: str | None = ...,
         fallback_to_default: bool = ...,
         rebuild_if_missing: bool = ...,
-    ) -> str: ...
+    ) -> FontPath: ...
     def get_font_names(self) -> list[str]: ...
 
 def is_opentype_cff_font(filename: str) -> bool: ...
 def get_font(
-    font_filepaths: Iterable[str | Path | bytes | FontFace] | str | Path | bytes | FontFace,
+    font_filepaths: Iterable[str | Path | bytes | FontFace | FontPath] | str | Path | bytes | FontFace | FontPath,
     hinting_factor: int | None = ...,
 ) -> ft2font.FT2Font: ...
 

lib/matplotlib/tests/test_font_manager.py

@@ -122,8 +122,12 @@ def test_find_ttc():
         pytest.skip("Font wqy-zenhei.ttc may be missing")
     # All fonts from this collection should have loaded as well.
     for name in ["WenQuanYi Zen Hei Mono", "WenQuanYi Zen Hei Sharp"]:
-        assert findfont(FontProperties(family=[name]),
-                        fallback_to_default=False) == fontpath
+        subfontpath = findfont(FontProperties(family=[name]), fallback_to_default=False)
+        assert subfontpath.path == fontpath.path
+        assert subfontpath.face_index != fontpath.face_index
+        subfont = get_font(subfontpath)
+        assert subfont.fname == subfontpath.path
+        assert subfont.face_index == subfontpath.face_index
     fig, ax = plt.subplots()
     ax.text(.5, .5, "\N{KANGXI RADICAL DRAGON}", fontproperties=fp)
     for fmt in ["raw", "svg", "pdf", "ps"]: