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

anntzer · anntzer · commit 9c5733e67397 · 2020-02-12T00:09:28.000+01:00
The rcParam cannot be meaningfully set by the end user from their
matplotlibrc or Python code.
diff --git a/doc/api/matplotlib_configuration_api.rst b/doc/api/matplotlib_configuration_api.rst
@@ -45,6 +45,8 @@ Default values and styling
 
 .. autofunction:: matplotlib_fname
 
+.. autofunction:: get_data_path
+
 Logging
 =======
 
diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
@@ -211,3 +211,8 @@ The *clear_temp* parameter and attribute of `.FileMovieWriter` is
 deprecated.  In the future, files placed in a temporary directory (using
 ``frame_prefix=None``, the default) will be cleared; files placed elsewhere
 will not.
+
+The ``datapath`` rcParam
+~~~~~~~~~~~~~~~~~~~~~~~~
+Use `.get_data_path` instead.  (The rcParam is deprecated because it cannot be
+meaningfully set by an end user.)
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -507,11 +507,13 @@ 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."""
 
     path = Path(__file__).with_name("mpl-data")
     if path.is_dir():
+        defaultParams['datapath'][0] = str(path)
         return str(path)
 
     cbook.warn_deprecated(
@@ -534,18 +536,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]
-
-
 def matplotlib_fname():
     """
     Get the location of the config file.
@@ -602,6 +598,7 @@ def gen_candidates():
 _deprecated_remain_as_none = {
     'animation.avconv_path': ('3.3',),
     'animation.avconv_args': ('3.3',),
+    'datapath': ('3.3',),
 }
 
 
@@ -839,8 +836,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
@@ -486,7 +486,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
@@ -95,10 +95,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                                                                   *
