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

anntzer · anntzer · commit 8059bdf0ec6b · 2020-02-05T14:04:57.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
@@ -184,3 +184,8 @@ Debian 8 (2015, EOL 06/2020) and Ubuntu 14.04 (EOL 04/2019) were the
 last versions of Debian and Ubuntu to ship avconv.  It remains possible
 to force the use of avconv by using the ffmpeg-based writers with
 :rc:`animation.ffmpeg_path` set to "avconv".
+
+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,8 +507,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']
@@ -521,6 +522,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(
@@ -543,18 +545,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.
@@ -611,6 +607,7 @@ def gen_candidates():
 _deprecated_remain_as_none = {
     'animation.avconv_path': ('3.3',),
     'animation.avconv_args': ('3.3',),
+    'datapath': ('3.3',),
 }
 
 
@@ -848,8 +845,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/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                                                                   *
