Merge pull request #16722 from anntzer/deprecate-rcdatapath-32

tacaswell · web-flow · commit 4897c4d964dc · 2020-03-17T14:59:54.000-04:00
API: Deprecate rcParams["datapath"] in favor of mpl.get_data_path().
diff --git a/doc/api/matplotlib_configuration_api.rst b/doc/api/matplotlib_configuration_api.rst
@@ -43,6 +43,8 @@ Default values and styling
 
 .. autofunction:: matplotlib_fname
 
+.. autofunction:: get_data_path
+
 Logging
 =======
 
diff --git a/doc/api/prev_api_changes/api_changes_3.2.0/deprecations.rst b/doc/api/prev_api_changes/api_changes_3.2.0/deprecations.rst
@@ -290,3 +290,10 @@ from the public API in future versions.
 
 ``style.core.is_style_file`` and ``style.core.iter_style_files``
 are deprecated.
+
+The ``datapath`` rcParam
+~~~~~~~~~~~~~~~~~~~~~~~~
+Use `.get_data_path` instead.  (The rcParam is deprecated because it cannot be
+meaningfully set by an end user.)  The rcParam had no effect from 3.2.0, but
+was deprecated only in 3.2.1.  In 3.2.1+ if ``'datapath'`` is set in a
+``matplotlibrc`` file it will be respected, but this behavior will be removed in 3.3.
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -132,6 +132,7 @@
 import shutil
 import subprocess
 import tempfile
+import warnings
 
 # cbook must import matplotlib only within function
 # definitions, so it is safe to import from it here.
@@ -269,10 +270,10 @@ def func(): ...
     ret = None
 
     @functools.wraps(func)
-    def wrapper():
+    def wrapper(**kwargs):
         nonlocal called, ret
         if not called:
-            ret = func()
+            ret = func(**kwargs)
             called = True
             _log.debug(fmt, ret)
         return ret
@@ -619,9 +620,31 @@ def get_cachedir():
     return _get_config_or_cache_dir(_get_xdg_cache_dir())
 
 
-def _get_data_path():
-    """Return the path to matplotlib data."""
+@_logged_cached('matplotlib data path: %s')
+def get_data_path(*, _from_rc=None):
+    """Return the path to Matplotlib data."""
+    if _from_rc is not None:
+        cbook.warn_deprecated(
+            "3.2",
+            message=("Setting the datapath via matplotlibrc is "
+            "deprecated %(since)s and will be removed in %(removal)s. "
+            ""),
+            removal='3.3')
+        path = Path(_from_rc)
+        if path.is_dir():
+            defaultParams['datapath'][0] = str(path)
+            return str(path)
+        else:
+            warnings.warn(f"You passed datapath: {_from_rc!r} in your "
+                          f"matplotribrc file ({matplotlib_fname()}). "
+                          "However this path does not exist, falling back "
+                          "to standard paths.")
+
+    return _get_data_path()
 
+
+@_logged_cached('(private) matplotlib data path: %s')
+def _get_data_path():
     if 'MATPLOTLIBDATA' in os.environ:
         path = os.environ['MATPLOTLIBDATA']
         if not os.path.isdir(path):
@@ -633,6 +656,7 @@ def _get_data_path():
 
     path = Path(__file__).with_name("mpl-data")
     if path.is_dir():
+        defaultParams['datapath'][0] = str(path)
         return str(path)
 
     cbook.warn_deprecated(
@@ -655,18 +679,12 @@ def get_candidate_paths():
 
     for path in get_candidate_paths():
         if path.is_dir():
+            defaultParams['datapath'][0] = str(path)
             return str(path)
 
     raise RuntimeError('Could not find the matplotlib data files')
 
 
-@_logged_cached('matplotlib data path: %s')
-def get_data_path():
-    if defaultParams['datapath'][0] is None:
-        defaultParams['datapath'][0] = _get_data_path()
-    return defaultParams['datapath'][0]
-
-
 @cbook.deprecated("3.1")
 def get_py2exe_datafiles():
     data_path = Path(get_data_path())
@@ -708,7 +726,7 @@ def gen_candidates():
             yield matplotlibrc
             yield os.path.join(matplotlibrc, 'matplotlibrc')
         yield os.path.join(get_configdir(), 'matplotlibrc')
-        yield os.path.join(get_data_path(), 'matplotlibrc')
+        yield os.path.join(_get_data_path(), 'matplotlibrc')
 
     for fname in gen_candidates():
         if os.path.exists(fname) and not os.path.isdir(fname):
@@ -736,6 +754,7 @@ def gen_candidates():
     'savefig.frameon': ('3.1',),
     'verbose.fileo': ('3.1',),
     'verbose.level': ('3.1',),
+    'datapath': ('3.2.1',),
 }
 
 
@@ -973,8 +992,11 @@ def rc_params_from_file(fname, fail_on_error=False, use_default_template=True):
                            if key not in _all_deprecated])
     config.update(config_from_file)
 
-    if config['datapath'] is None:
-        config['datapath'] = get_data_path()
+    with cbook._suppress_matplotlib_deprecation_warning():
+        if config['datapath'] is None:
+            config['datapath'] = _get_data_path()
+        else:
+            config['datapath'] = get_data_path(_from_rc=config['datapath'])
 
     if "".join(config['text.latex.preamble']):
         _log.info("""
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -439,7 +439,7 @@ def get_sample_data(fname, asfileobj=True):
 
     If the filename ends in .gz, the file is implicitly ungzipped.
     """
-    path = Path(matplotlib._get_data_path(), 'sample_data', fname)
+    path = Path(matplotlib.get_data_path(), 'sample_data', fname)
     if asfileobj:
         suffix = path.suffix.lower()
         if suffix == '.gz':
diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -103,10 +103,6 @@
 #toolbar     : toolbar2  ## {None, toolbar2}
 #timezone    : UTC       ## a pytz timezone string, e.g., US/Central or Europe/Paris
 
-## Where your matplotlib data lives if you installed to a non-default
-## location.  This is where the matplotlib fonts, bitmaps, etc reside
-#datapath : /home/jdhunter/mpldata
-
 
 ## ***************************************************************************
 ## * LINES                                                                   *
