Deprecate the examples.directory rcParam.

anntzer · anntzer · commit f9ed276614c8 · 2018-05-13T17:39:15.000-07:00
It is always found in the sample_data subdirectory relative to what the
``datapath`` rcParam indicates now.  The latter should already provide
enough flexibility for downstream packagers that want to tear the
package apart...
diff --git a/doc/api/next_api_changes/2018-02-15-AL-deprecations.rst b/doc/api/next_api_changes/2018-02-15-AL-deprecations.rst
@@ -36,4 +36,5 @@ The following classes, methods, functions, and attributes are deprecated:
 - ``text.Annotation.arrow``,
 
 The following rcParams are deprecated:
+- ``examples.directory`` (use ``datapath`` instead),
 - ``pgf.debug`` (the pgf backend relies on logging),
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -877,6 +877,10 @@ def __setitem__(self, key, val):
                 warnings.warn(self.msg_obsolete % (key, ),
                               mplDeprecation)
                 return
+            elif key == 'examples.directory':
+                cbook.warn_deprecated(
+                    "3.0", "{} is deprecated; examples are found relative to "
+                    "the 'datapath' directory.".format(key))
             try:
                 cval = self.validate[key](val)
             except ValueError as ve:
@@ -906,6 +910,11 @@ def __getitem__(self, key):
                           mplDeprecation)
             return None
 
+        elif key == 'examples.directory':
+            cbook.warn_deprecated(
+                "3.0", "{} is deprecated; examples are found relative to the "
+                "'datapath' directory.".format(key))
+
         val = dict.__getitem__(self, key)
         if inverse_alt is not None:
             return inverse_alt(val)
@@ -1111,7 +1120,8 @@ def rc_params_from_file(fname, fail_on_error=False, use_default_template=True):
 # this is the instance used by the matplotlib classes
 rcParams = rc_params()
 
-if rcParams['examples.directory']:
+# Don't trigger deprecation warning when just fetching.
+if dict.__getitem__(rcParams, 'examples.directory'):
     # paths that are intended to be relative to matplotlib_fname()
     # are allowed for the examples.directory parameter.
     # However, we will need to fully qualify the path because
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -524,7 +524,8 @@ def get_sample_data(fname, asfileobj=True):
 
     If the filename ends in .gz, the file is implicitly ungzipped.
     """
-    if matplotlib.rcParams['examples.directory']:
+    # Don't trigger deprecation warning when just fetching.
+    if dict.__getitem__(matplotlib.rcParams, 'examples.directory'):
         root = matplotlib.rcParams['examples.directory']
     else:
         root = os.path.join(matplotlib._get_data_path(), 'sample_data')
diff --git a/lib/matplotlib/tests/test_rcparams.py b/lib/matplotlib/tests/test_rcparams.py
@@ -476,7 +476,7 @@ def test_if_rctemplate_is_up_to_date():
             continue
         if k in deprecated:
             continue
-        if "verbose" in k:
+        if k.startswith(("verbose.", "examples.directory")):
             continue
         found = False
         for line in rclines:
diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -594,9 +594,6 @@ backend      : $TEMPLATE_BACKEND
 #keymap.all_axes : a                 ## enable all axes
 #keymap.copy : ctrl+c, cmd+c         ## Copy figure to clipboard
 
-## Control location of examples data files
-#examples.directory :              ## directory to look in for custom installation
-
 ###ANIMATION settings
 #animation.html :  none            ## How to display the animation as HTML in
                                    ## the IPython notebook. 'html5' uses
