Deprecation warning for cmap_d.

greglucas · greglucas · commit d5a8b910643d · 2020-04-24T08:14:48.000-06:00
diff --git a/lib/matplotlib/cm.py b/lib/matplotlib/cm.py
@@ -15,6 +15,7 @@
   normalization.
 """
 
+from collections.abc import MutableMapping
 import functools
 
 import numpy as np
@@ -49,7 +50,7 @@ def revcmap(data):
 LUTSIZE = mpl.rcParams['image.lut']
 
 
-def _gen_cmap_d():
+def _gen_cmap_registry():
     """
     Generate a dict mapping standard colormap names to standard colormaps, as
     well as the reversed colormaps.
@@ -71,10 +72,48 @@ def _gen_cmap_d():
     return cmap_d
 
 
-_cmap_d = _gen_cmap_d()
-locals().update(_cmap_d)
+class _DeprecatedCmapDict(MutableMapping):
+    """Dictionary mapping for deprecated _cmap_d access."""
+
+    def __init__(self, cmap_registry):
+        self._cmap_registry = cmap_registry
+
+    def __delitem__(self, key):
+        self._warn_deprecated()
+        self._cmap_registry.__delitem__(key)
+
+    def __getitem__(self, key):
+        self._warn_deprecated()
+        return self._cmap_registry.__getitem__(key)
+
+    def __iter__(self):
+        return self._cmap_registry.__iter__()
+
+    def __len__(self):
+        return self._cmap_registry.__len__()
+
+    def __setitem__(self, key, val):
+        self._warn_deprecated()
+        self._cmap_registry.__setitem__(key, val)
+
+    def get(self, key, default=None):
+        self._warn_deprecated()
+        return self._cmap_registry.get(key, default)
+
+    def _warn_deprecated(self):
+        cbook.warn_deprecated(
+            "3.3",
+            message="The global colormaps dictionary is no longer "
+                    "considered public API.",
+            alternative="Please use register_cmap() and get_cmap() to "
+                        "access the contents of the dictionary."
+        )
+
+
+_cmap_registry = _gen_cmap_registry()
+locals().update(_cmap_registry)
 # This is no longer considered public API
-cmap_d = _cmap_d
+cmap_d = _DeprecatedCmapDict(_cmap_registry)
 
 
 # Continue with definitions ...
@@ -99,6 +138,13 @@ def register_cmap(name=None, cmap=None, data=None, lut=None):
     and the resulting colormap is registered. Instead of this implicit
     colormap creation, create a `.LinearSegmentedColormap` and use the first
     case: ``register_cmap(cmap=LinearSegmentedColormap(name, data, lut))``.
+
+    Notes
+    -----
+    Registering a colormap stores a reference to the colormap object
+    which can currently be modified and inadvertantly change the global
+    colormap state. This behavior is deprecated and in Matplotlib 3.5
+    the registered colormap will be immutable.
     """
     cbook._check_isinstance((str, None), name=name)
     if name is None:
@@ -109,7 +155,7 @@ def register_cmap(name=None, cmap=None, data=None, lut=None):
                              "Colormap") from err
     if isinstance(cmap, colors.Colormap):
         cmap._global = True
-        _cmap_d[name] = cmap
+        _cmap_registry[name] = cmap
         return
     if lut is not None or data is not None:
         cbook.warn_deprecated(
@@ -123,7 +169,7 @@ def register_cmap(name=None, cmap=None, data=None, lut=None):
         lut = mpl.rcParams['image.lut']
     cmap = colors.LinearSegmentedColormap(name, data, lut)
     cmap._global = True
-    _cmap_d[name] = cmap
+    _cmap_registry[name] = cmap
 
 
 def get_cmap(name=None, lut=None):
@@ -133,15 +179,18 @@ def get_cmap(name=None, lut=None):
     Colormaps added with :func:`register_cmap` take precedence over
     built-in colormaps.
 
+    Notes
+    -----
+    Currently, this returns the global colormap object, which is deprecated.
+    In Matplotlib 3.5, you will no longer be able to modify the global
+    colormaps in-place.
+
     Parameters
     ----------
     name : `matplotlib.colors.Colormap` or str or None, default: None
         If a `.Colormap` instance, it will be returned.
         Otherwise, the name of a colormap known to Matplotlib, which will
-        be resampled by *lut*. Currently, this returns the global colormap
-        object, which is deprecated. In Matplotlib 3.5, you will no longer be
-        able to modify the global colormaps in-place.
-        The default, None, means :rc:`image.cmap`.
+        be resampled by *lut*. The default, None, means :rc:`image.cmap`.
     lut : int or None, default: None
         If *name* is not already a Colormap instance and *lut* is not None, the
         colormap will be resampled to have *lut* entries in the lookup table.
@@ -150,11 +199,11 @@ def get_cmap(name=None, lut=None):
         name = mpl.rcParams['image.cmap']
     if isinstance(name, colors.Colormap):
         return name
-    cbook._check_in_list(sorted(_cmap_d), name=name)
+    cbook._check_in_list(sorted(_cmap_registry), name=name)
     if lut is None:
-        return _cmap_d[name]
+        return _cmap_registry[name]
     else:
-        return _cmap_d[name]._resample(lut)
+        return _cmap_registry[name]._resample(lut)
 
 
 class ScalarMappable:
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -484,8 +484,8 @@ def makeMappingArray(N, data, gamma=1.0):
     return _create_lookup_table(N, data, gamma)
 
 
-def _deprecate_global_cmap(cmap):
-    if hasattr(cmap, '_global') and cmap._global:
+def _warn_if_global_cmap_modified(cmap):
+    if getattr(cmap, '_global', False):
         cbook.warn_deprecated(
             "3.3",
             message="You are modifying the state of a globally registered "
@@ -619,28 +619,28 @@ def __copy__(self):
 
     def set_bad(self, color='k', alpha=None):
         """Set the color for masked values."""
+        _warn_if_global_cmap_modified(self)
         self._rgba_bad = to_rgba(color, alpha)
         if self._isinit:
             self._set_extremes()
-        _deprecate_global_cmap(self)
 
     def set_under(self, color='k', alpha=None):
         """
         Set the color for low out-of-range values when ``norm.clip = False``.
         """
+        _warn_if_global_cmap_modified(self)
         self._rgba_under = to_rgba(color, alpha)
         if self._isinit:
             self._set_extremes()
-        _deprecate_global_cmap(self)
 
     def set_over(self, color='k', alpha=None):
         """
         Set the color for high out-of-range values when ``norm.clip = False``.
         """
+        _warn_if_global_cmap_modified(self)
         self._rgba_over = to_rgba(color, alpha)
         if self._isinit:
             self._set_extremes()
-        _deprecate_global_cmap(self)
 
     def _set_extremes(self):
         if self._rgba_under:
diff --git a/lib/matplotlib/tests/test_colors.py b/lib/matplotlib/tests/test_colors.py
@@ -126,6 +126,17 @@ def test_colormap_global_set_warn():
     plt.register_cmap(cmap=orig_cmap)
 
 
+def test_colormap_dict_deprecate():
+    # Make sure we warn on get and set access into cmap_d
+    with pytest.warns(cbook.MatplotlibDeprecationWarning,
+                      match="The global colormaps dictionary is no longer"):
+        cm = plt.cm.cmap_d['viridis']
+
+    with pytest.warns(cbook.MatplotlibDeprecationWarning,
+                      match="The global colormaps dictionary is no longer"):
+        plt.cm.cmap_d['test'] = cm
+
+
 def test_colormap_copy():
     cm = plt.cm.Reds
     cm_copy = copy.copy(cm)
diff --git a/lib/matplotlib/tests/test_pickle.py b/lib/matplotlib/tests/test_pickle.py
@@ -190,7 +190,7 @@ def test_shared():
     assert fig.axes[1].get_xlim() == (10, 20)
 
 
-@pytest.mark.parametrize("cmap", cm.cmap_d.values())
+@pytest.mark.parametrize("cmap", cm._cmap_registry.values())
 def test_cmap(cmap):
     pickle.dumps(cmap)
 
