From 404ff5dd353b8e3580ba6991b7e0fbd43f644a43 Mon Sep 17 00:00:00 2001
From: Antony Lee <anntzer.lee@gmail.com>
Date: Sun, 13 May 2018 16:20:52 -0700
Subject: [PATCH] Deprecate the MATPLOTLIBDATA environment variable.

The MATPLOTLIBDATA environment variable is only relevant to non-standard
installs (e.g., debian) that move the mpl-data directory to a separate
location (in debian's case, /usr/share/matplotlib/mpl-data); but for
whoever is already patching Matplotlib to achieve this, they may as well
also patch `get_data_path` to always return the new correct path (which
debian already does in their `20_matplotlibrc_path_search_fix.patch`),
reproduced here:

    diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
    index 9339707..563b0a8 100644
    --- a/lib/matplotlib/__init__.py
    +++ b/lib/matplotlib/__init__.py
    @@ -738,10 +738,12 @@ def _get_data_path():
            return path

        _file = _decode_filesystem_path(__file__)
    -    path = os.sep.join([os.path.dirname(_file), 'mpl-data'])
    +    path = '/usr/share/matplotlib/mpl-data'
        if os.path.isdir(path):
            return path

    +    raise RuntimeError('Could not find the matplotlib data files')
    +
        # setuptools' namespace_packages may highjack this init file
        # so need to try something known to be in matplotlib, not basemap
        import matplotlib.afm
    @@ -836,7 +838,7 @@ def matplotlib_fname():
                yield matplotlibrc
                yield os.path.join(matplotlibrc, 'matplotlibrc')
            yield os.path.join(_get_configdir(), 'matplotlibrc')
    -        yield os.path.join(get_data_path(), 'matplotlibrc')
    +        yield '/etc/matplotlibrc'

        for fname in gen_candidates():
            if os.path.exists(fname):
---
 doc/api/next_api_changes/2018-08-17-AL-deprecations.rst | 3 +++
 lib/matplotlib/__init__.py                              | 2 ++
 2 files changed, 5 insertions(+)

diff --git a/doc/api/next_api_changes/2018-08-17-AL-deprecations.rst b/doc/api/next_api_changes/2018-08-17-AL-deprecations.rst
index 4097437b3c08..f03163baff33 100644
--- a/doc/api/next_api_changes/2018-08-17-AL-deprecations.rst
+++ b/doc/api/next_api_changes/2018-08-17-AL-deprecations.rst
@@ -7,3 +7,6 @@ The following API elements are deprecated:
 - ``backend_ps.PsBackendHelper``, ``backend_ps.ps_backend_helper``,
 - ``cbook.iterable``,
 - ``mlab.demean``,
+
+The following environment variables are deprecated:
+- ``MATPLOTLIBDATA``,
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
index d5cf4d3d99fe..e339b7c8aa4e 100644
--- a/lib/matplotlib/__init__.py
+++ b/lib/matplotlib/__init__.py
@@ -652,6 +652,8 @@ def _get_data_path():
         if not os.path.isdir(path):
             raise RuntimeError('Path in environment MATPLOTLIBDATA not a '
                                'directory')
+        cbook.warn_deprecated(
+            "3.1", name="MATPLOTLIBDATA", obj_type="environment variable")
         return path
 
     def get_candidate_paths():