diff --git a/galleries/users_explain/text/fonts.py b/galleries/users_explain/text/fonts.py index eed783a7aa38..232e25983a67 100644 --- a/galleries/users_explain/text/fonts.py +++ b/galleries/users_explain/text/fonts.py @@ -196,6 +196,33 @@ Each glyph of the string is rendered using the first font in the list that contains that glyph. +Loading new fonts +----------------- + +All fonts that are installed in your system will become available to the +`.FontManager`, as well as the default fonts that ship with Matplotlib. The latter +fonts are located in the directory ``'matplotlib\mpl-data\fonts\ttf'``. +It is also possible to add fonts to this directory, or to `allocate a custom +directory +`_ +that contains any fonts you wish to add to the `.FontManager`. + +In either case, the `.FontManager` will only find the new fonts after the font cache +has been rebuilt following their addition . You may need to rebuild the cache +yourself if your new fonts cannot be found by Matplotlib. +The cache can be rebuilt by using :func:`matplotlib.font_manager.load_fontmanager`:: + import matplotlib as mpl + mpl.font_manager.load_fontmanager(try_read_cache=False) + +Alternatively, you can expose the location of your font cache using +:func:`matplotlib.get_cachedir`:: + import matplotlib as mpl + mpl.get_cachedir() + '/home/darren/.cache/matplotlib' + +You can then manually delete the cache file ``'fontlist.json'``. The new fonts +will be available the next time the script is run. + A majority of this work was done by Aitik Gupta supported by Google Summer of Code 2021. """ diff --git a/lib/matplotlib/font_manager.py b/lib/matplotlib/font_manager.py index e7be2203bc12..13d3735aa77a 100644 --- a/lib/matplotlib/font_manager.py +++ b/lib/matplotlib/font_manager.py @@ -1456,10 +1456,10 @@ def _findfont_cached(self, prop, fontext, directory, fallback_to_default, if rebuild_if_missing: _log.info( 'findfont: Found a missing font file. Rebuilding cache.') - new_fm = _load_fontmanager(try_read_cache=False) + new_fm = load_fontmanager(try_read_cache=False) # Replace self by the new fontmanager, because users may have # a reference to this specific instance. - # TODO: _load_fontmanager should really be (used by) a method + # TODO: load_fontmanager should really be (used by) a method # modifying the instance in place. vars(self).update(vars(new_fm)) return self.findfont( @@ -1558,7 +1558,10 @@ def get_font(font_filepaths, hinting_factor=None): ) -def _load_fontmanager(*, try_read_cache=True): +def load_fontmanager(*, try_read_cache=True): + """ + Re-loads the font cache by generating a new `.FontManager` instance. + """ fm_path = Path( mpl.get_cachedir(), f"fontlist-v{FontManager.__version__}.json") if try_read_cache: @@ -1576,6 +1579,6 @@ def _load_fontmanager(*, try_read_cache=True): return fm -fontManager = _load_fontmanager() +fontManager = load_fontmanager() findfont = fontManager.findfont get_font_names = fontManager.get_font_names diff --git a/lib/matplotlib/font_manager.pyi b/lib/matplotlib/font_manager.pyi index 92b78ae2212d..96d33fecfc0e 100644 --- a/lib/matplotlib/font_manager.pyi +++ b/lib/matplotlib/font_manager.pyi @@ -129,3 +129,4 @@ def findfont( rebuild_if_missing: bool = ..., ) -> str: ... def get_font_names() -> list[str]: ... +def load_fontmanager(try_read_cache: bool = ...) -> FontManager: ...