Allow directly passing explicit font paths.

anntzer · anntzer · commit 3b2894e3506f · 2020-02-03T15:59:17.000+01:00
This allows one to use `text(..., font=Path("/path/to/font.ttf"))`
rather than the more cumbersome
`fontproperties=FontProperties(fname="/path/to/font.ttf")`.

Note that we do not allow `font="/path/to/font.ttf"` and instead only
support Path objects because we also already support `font="DejaVu Sans"`
and I would rather not guess whether we have been passed a path or a
family (if there is really demand for that we can always add it later
anyways).
diff --git a/doc/users/next_whats_new/2020-02-03-fontpath.rst b/doc/users/next_whats_new/2020-02-03-fontpath.rst
@@ -0,0 +1,5 @@
+Simple syntax to select fonts by absolute path
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Fonts can now be selected by passing an absolute `pathlib.Path` to the *font*
+kwarg of `.Text`.
diff --git a/examples/text_labels_and_annotations/font_file.py b/examples/text_labels_and_annotations/font_file.py
@@ -1,11 +1,12 @@
-"""
+r"""
 ===================================
 Using a ttf font file in Matplotlib
 ===================================
 
 Although it is usually not a good idea to explicitly point to a single ttf file
-for a font instance, you can do so using the `.font_manager.FontProperties`
-*fname* argument.
+for a font instance, you can do so by passing a `pathlib.Path` instance as the
+*font* parameter.  Note that passing paths as `str`\s is intentionally not
+supported, but you can simply wrap `str`\s in `pathlib.Path`\s as needed.
 
 Here, we use the Computer Modern roman font (``cmr10``) shipped with
 Matplotlib.
@@ -18,14 +19,12 @@
 from pathlib import Path
 
 import matplotlib as mpl
-from matplotlib import font_manager as fm
 import matplotlib.pyplot as plt
 
 fig, ax = plt.subplots()
 
 fpath = Path(mpl.get_data_path(), "fonts/ttf/cmr10.ttf")
-prop = fm.FontProperties(fname=fpath)
-ax.set_title(f'This is a special font: {fpath.name}', fontproperties=prop)
+ax.set_title(f'This is a special font: {fpath.name}', font=fpath)
 ax.set_xlabel('This is the default font')
 
 plt.show()
@@ -42,5 +41,4 @@
 # in this example:
 
 import matplotlib
-matplotlib.font_manager.FontProperties
 matplotlib.axes.Axes.set_title
diff --git a/examples/text_labels_and_annotations/font_table.py b/examples/text_labels_and_annotations/font_table.py
@@ -15,6 +15,7 @@
 """
 
 import os
+from pathlib import Path
 import unicodedata
 
 import matplotlib.font_manager as fm
@@ -101,7 +102,7 @@ def draw_font_table(path):
     for key, cell in table.get_celld().items():
         row, col = key
         if row > 0 and col > -1:  # Beware of table's idiosyncratic indexing...
-            cell.set_text_props(fontproperties=fm.FontProperties(fname=path))
+            cell.set_text_props(font=Path(path))
 
     fig.tight_layout()
     plt.show()
diff --git a/lib/matplotlib/font_manager.py b/lib/matplotlib/font_manager.py
@@ -598,8 +598,10 @@ class FontProperties:
 
       sans-serif, normal, normal, normal, normal, scalable.
 
-    Alternatively, a font may be specified using an absolute path to a
-    .ttf file, by using the *fname* kwarg.
+    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
+    *font* kwarg of the `.Text` object.
 
     The preferred usage of font sizes is to use the relative values,
     e.g.,  'large', instead of absolute font sizes, e.g., 12.  This
@@ -657,6 +659,17 @@ def __init__(self,
         self.set_file(fname)
         self.set_size(size)
 
+    @classmethod
+    def _from_any(cls, arg):
+        if isinstance(arg, cls):
+            return arg
+        elif isinstance(arg, os.PathLike):
+            return cls(fname=arg)
+        elif isinstance(arg, str):
+            return cls(arg)
+        else:
+            return cls(**arg)
+
     def __hash__(self):
         l = (tuple(self.get_family()),
              self.get_slant(),
@@ -1230,8 +1243,7 @@ def findfont(self, prop, fontext='ttf', directory=None,
     def _findfont_cached(self, prop, fontext, directory, fallback_to_default,
                          rebuild_if_missing, rc_params):
 
-        if not isinstance(prop, FontProperties):
-            prop = FontProperties(prop)
+        prop = FontProperties._from_any(prop)
 
         fname = prop.get_file()
         if fname is not None:
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -364,12 +364,10 @@ def __init__(self, parent, handles, labels,
                 self.prop = FontProperties(size=fontsize)
             else:
                 self.prop = FontProperties(size=rcParams["legend.fontsize"])
-        elif isinstance(prop, dict):
-            self.prop = FontProperties(**prop)
-            if "size" not in prop:
-                self.prop.set_size(rcParams["legend.fontsize"])
         else:
-            self.prop = prop
+            self.prop = FontProperties._from_any(prop)
+            if isinstance(prop, dict) and "size" not in prop:
+                self.prop.set_size(rcParams["legend.fontsize"])
 
         self._fontsize = self.prop.get_size_in_points()
 
@@ -876,8 +874,6 @@ def set_title(self, title, prop=None):
             self._legend_title_box.set_visible(False)
 
         if prop is not None:
-            if isinstance(prop, dict):
-                prop = FontProperties(**prop)
             self._legend_title_box._text.set_fontproperties(prop)
 
         self.stale = True
diff --git a/lib/matplotlib/offsetbox.py b/lib/matplotlib/offsetbox.py
@@ -1101,12 +1101,10 @@ def __init__(self, loc,
 
         if prop is None:
             self.prop = FontProperties(size=rcParams["legend.fontsize"])
-        elif isinstance(prop, dict):
-            self.prop = FontProperties(**prop)
-            if "size" not in prop:
-                self.prop.set_size(rcParams["legend.fontsize"])
         else:
-            self.prop = prop
+            self.prop = FontProperties._from_any(prop)
+            if isinstance(prop, dict) and "size" not in prop:
+                self.prop.set_size(rcParams["legend.fontsize"])
 
         self.patch = FancyBboxPatch(
             xy=(0.0, 0.0), width=1., height=1.,
diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py
@@ -282,10 +282,10 @@ def on_dpi_change(fig):
         _fp = self.fontproperties
         # boxprops = dict(facecolor='red')
         self.text = mtext.Text(
-                        text=label,  # bbox=boxprops,
-                        horizontalalignment=self.halign[self.labelpos],
-                        verticalalignment=self.valign[self.labelpos],
-                        fontproperties=font_manager.FontProperties(**_fp))
+            text=label,  # bbox=boxprops,
+            horizontalalignment=self.halign[self.labelpos],
+            verticalalignment=self.valign[self.labelpos],
+            fontproperties=font_manager.FontProperties._from_any(_fp))
 
         if self.labelcolor is not None:
             self.text.set_color(self.labelcolor)
diff --git a/lib/matplotlib/tests/test_ttconv.py b/lib/matplotlib/tests/test_ttconv.py
@@ -1,7 +1,6 @@
 from pathlib import Path
 
 import matplotlib
-from matplotlib.font_manager import FontProperties
 from matplotlib.testing.decorators import image_comparison
 import matplotlib.pyplot as plt
 
@@ -10,10 +9,9 @@
 # mpltest.ttf does not have "l"/"p" glyphs so we get a warning when trying to
 # get the font extents.
 def test_truetype_conversion(recwarn):
-    fontprop = FontProperties(
-        fname=str(Path(__file__).with_name('mpltest.ttf').resolve()), size=80)
     matplotlib.rcParams['pdf.fonttype'] = 3
     fig, ax = plt.subplots()
-    ax.text(0, 0, "ABCDE", fontproperties=fontprop)
+    ax.text(0, 0, "ABCDE",
+            font=Path(__file__).with_name("mpltest.ttf"), fontsize=80)
     ax.set_xticks([])
     ax.set_yticks([])
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -105,7 +105,7 @@ def _get_textbox(text, renderer):
 @cbook._define_aliases({
     "color": ["c"],
     "fontfamily": ["family"],
-    "fontproperties": ["font_properties"],
+    "fontproperties": ["font", "font_properties"],
     "horizontalalignment": ["ha"],
     "multialignment": ["ma"],
     "fontname": ["name"],
@@ -1221,11 +1221,12 @@ def set_fontproperties(self, fp):
 
         Parameters
         ----------
-        fp : `.font_manager.FontProperties`
+        fp : `.font_manager.FontProperties` or `str` or `pathlib.Path`
+            If a `str`, it is interpreted as a fontconfig pattern parsed by
+            `.FontProperties`.  If a `pathlib.Path`, it is interpreted as the
+            absolute path to a font file.
         """
-        if isinstance(fp, str):
-            fp = FontProperties(fp)
-        self._fontproperties = fp.copy()
+        self._fontproperties = FontProperties._from_any(fp).copy()
         self.stale = True
 
     def set_usetex(self, usetex):
diff --git a/lib/matplotlib/textpath.py b/lib/matplotlib/textpath.py
@@ -400,6 +400,8 @@ def __init__(self, xy, s, size=None, prop=None,
 
         if prop is None:
             prop = FontProperties()
+        else:
+            prop = FontProperties._from_any(prop)
         if size is None:
             size = prop.get_size_in_points()
 
diff --git a/tools/make_icons.py b/tools/make_icons.py
@@ -15,7 +15,6 @@
 
 import matplotlib as mpl
 import matplotlib.pyplot as plt
-from matplotlib.font_manager import FontProperties
 import numpy as np
 
 
@@ -45,13 +44,10 @@ def save_icon(fig, dest_dir, name):
 
 
 def make_icon(font_path, ccode):
-    prop = FontProperties(fname=font_path, size=68)
-
     fig = plt.figure(figsize=(1, 1))
     fig.patch.set_alpha(0.0)
     text = fig.text(0.5, 0.48, chr(ccode), ha='center', va='center',
-                    fontproperties=prop)
-
+                    font=font_path, fontsize=68)
     return fig
 
 
