diff --git a/lib/matplotlib/font_manager.py b/lib/matplotlib/font_manager.py index f5b094e54de0..4f65f612359f 100644 --- a/lib/matplotlib/font_manager.py +++ b/lib/matplotlib/font_manager.py @@ -7,6 +7,8 @@ system font path that matches the specified `FontProperties` instance. The `FontManager` also handles Adobe Font Metrics (AFM) font files for use by the PostScript backend. +The `FontManager.addfont` function adds a custom font from a file without +installing it into your operating system. The design is based on the `W3C Cascading Style Sheet, Level 1 (CSS1) font specification `_. @@ -980,6 +982,27 @@ class FontManager: method does a nearest neighbor search to find the font that most closely matches the specification. If no good enough match is found, the default font is returned. + + Fonts added with the `FontManager.addfont` method will not persist in the + cache; therefore, `addfont` will need to be called every time Matplotlib is + imported. This method should only be used if and when a font cannot be + installed on your operating system by other means. + + Notes + ----- + The `FontManager.addfont` method must be called on the global `FontManager` + instance. + + Example usage:: + + import matplotlib.pyplot as plt + from matplotlib import font_manager + + font_dirs = ["/resources/fonts"] # The path to the custom font file. + font_files = font_manager.findSystemFonts(fontpaths=font_dirs) + + for font_file in font_files: + font_manager.fontManager.addfont(font_file) """ # Increment this version number whenever the font cache data # format or behavior has changed and requires an existing font @@ -1030,6 +1053,12 @@ def addfont(self, path): Parameters ---------- path : str or path-like + + Notes + ----- + This method is useful for adding a custom font without installing it in + your operating system. See the `FontManager` singleton instance for + usage and caveats about this function. """ # Convert to string in case of a path as # afmFontProperty and FT2Font expect this