Deprecate rcParams["datapath"] in favor of mpl.get_data_path().

anntzer · anntzer · commit 26ab43ed3a80 · 2020-03-10T22:03:05.000+01:00
The rcParam cannot be meaningfully set by the end user from their
matplotlibrc or Python code.

(This is a manual backport to 3.2.x.)
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,8 @@ 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.)  This was deprecated only in 3.2.1.
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -619,8 +619,9 @@ 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():
+    """Return the path to Matplotlib data."""
 
     if 'MATPLOTLIBDATA' in os.environ:
         path = os.environ['MATPLOTLIBDATA']
@@ -633,6 +634,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 +657,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())
@@ -736,6 +732,7 @@ def gen_candidates():
     'savefig.frameon': ('3.1',),
     'verbose.fileo': ('3.1',),
     'verbose.level': ('3.1',),
+    'datapath': ('3.2.1',),
 }
 
 
@@ -973,8 +970,9 @@ 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()
 
     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                                                                   *
