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

anntzer · anntzer · commit a4a0925f932c · 2020-03-10T22:06:33.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
@@ -282,3 +282,8 @@ is deprecated, set the offset to 0 instead.
 ``RendererCairo.fontweights``, ``RendererCairo.fontangles``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ... 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
@@ -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.
@@ -600,6 +596,7 @@ def gen_candidates():
 # listed in the rcParams (not included in _all_deprecated).
 # Values are tuples of (version,)
 _deprecated_remain_as_none = {
+    'datapath': ('3.2.1',),
     'animation.avconv_path': ('3.3',),
     'animation.avconv_args': ('3.3',),
     'mathtext.fallback_to_cm': ('3.3',),
@@ -841,8 +838,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
@@ -474,7 +474,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                                                                   *
