From ec7a7310cf4b5908ae2575ad7b4a1714b03c48de Mon Sep 17 00:00:00 2001
From: Antony Lee <anntzer.lee@gmail.com>
Date: Sun, 15 Dec 2019 19:32:41 +0100
Subject: [PATCH] Deprecate the TTFPATH & AFMPATH environment variables.

These undocumented environment variables allow one to selectively add
paths to the font cache... but only if the font cache doesn't exist yet
(they don't force cache regen).  The font-cache regen API (_rebuild())
is also private (even though one can trigger it "publically" e.g. by
calling `findfont` with a nonexisting font...).

Instead, we now expose `addfont()` which is a documented API for
registering fonts with the font manager.
---
 doc/api/next_api_changes/deprecations.rst | 6 ++++++
 lib/matplotlib/font_manager.py            | 3 +++
 2 files changed, 9 insertions(+)

diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
index 4719e944aedf..98b556bf3fa4 100644
--- a/doc/api/next_api_changes/deprecations.rst
+++ b/doc/api/next_api_changes/deprecations.rst
@@ -163,3 +163,9 @@ This ticker is deprecated.
 *required*, *forbidden* and *allowed* parameters of `.cbook.normalize_kwargs`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 These parameters are deprecated.
+
+The ``TTFPATH`` and ``AFMPATH`` environment variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Support for the (undocumented) ``TTFPATH`` and ``AFMPATH`` environment
+variables is deprecated.  Additional fonts may be registered using
+``matplotlib.font_manager.fontManager.addfont()``.
diff --git a/lib/matplotlib/font_manager.py b/lib/matplotlib/font_manager.py
index 5033fe550592..bea02d5856c3 100644
--- a/lib/matplotlib/font_manager.py
+++ b/lib/matplotlib/font_manager.py
@@ -971,6 +971,9 @@ def __init__(self, size=None, weight='normal'):
                     paths.extend(ttfpath.split(':'))
                 else:
                     paths.append(ttfpath)
+                cbook.warn_deprecated(
+                    "3.3", name=pathname, obj_type="environment variable",
+                    alternative="FontManager.addfont()")
         _log.debug('font search path %s', str(paths))
         #  Load TrueType fonts and create font dictionary.