Deprecation warning for cmap_d.

greglucas · greglucas · commit 692b83c3f5b4 · 2020-04-26T21:32:32.000-06:00
diff --git a/examples/images_contours_and_fields/demo_bboximage.py b/examples/images_contours_and_fields/demo_bboximage.py
@@ -38,7 +38,7 @@
 a = np.vstack((a, a))
 
 # List of all colormaps; skip reversed colormaps.
-maps = sorted(m for m in plt.cm.cmap_d if not m.endswith("_r"))
+maps = sorted(m for m in plt.colormaps() if not m.endswith("_r"))
 
 ncol = 2
 nrow = len(maps)//ncol + 1
diff --git a/lib/matplotlib/backends/qt_editor/figureoptions.py b/lib/matplotlib/backends/qt_editor/figureoptions.py
@@ -140,11 +140,11 @@ def prepare_data(d, init):
         mappabledict[label] = mappable
     mappablelabels = sorted(mappabledict, key=cmp_key)
     mappables = []
-    cmaps = [(cmap, name) for name, cmap in sorted(cm.cmap_d.items())]
+    cmaps = [(cmap, name) for name, cmap in sorted(cm._cmap_registry.items())]
     for label in mappablelabels:
         mappable = mappabledict[label]
         cmap = mappable.get_cmap()
-        if cmap not in cm.cmap_d.values():
+        if cmap not in cm._cmap_registry.values():
             cmaps = [(cmap, cmap.name), *cmaps]
         low, high = mappable.get_clim()
         mappabledata = [
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,50 @@ def _gen_cmap_d():
     return cmap_d
 
 
-_cmap_d = _gen_cmap_d()
-locals().update(_cmap_d)
+class _DeprecatedCmapDictWrapper(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):
+        self._warn_deprecated()
+        return self._cmap_registry.__iter__()
+
+    def __len__(self):
+        self._warn_deprecated()
+        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 = _DeprecatedCmapDictWrapper(_cmap_registry)
 
 
 # Continue with definitions ...
@@ -99,6 +140,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 +157,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 +171,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 +181,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`.
+        If a `.Colormap` instance, it will be returned. Otherwise, the name of
+        a colormap known to Matplotlib, which will 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 +201,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,18 +484,15 @@ 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 "
-                    "colormap. In future versions, you will not be able "
-                    "to modify a globally registered colormap directly. "
-                    "To eliminate this warning until then, you can make "
-                    "a copy of the requested colormap before modifying it. ",
-            alternative="To modify a colormap without overwriting the "
-                        "global state, you can make a copy of the colormap "
-                        f"first. cmap = copy.copy(mpl.cm.get_cmap({cmap.name})"
+                    "colormap. In future versions, you will not be able to "
+                    "modify a registered colormap in-place. To remove this "
+                    "warning, you can make a copy of the colormap first. "
+                    f"cmap = mpl.cm.get_cmap({cmap.name}).copy()"
         )
 
 
@@ -619,28 +616,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/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1948,7 +1948,7 @@ def colormaps():
       <https://www.mathworks.com/matlabcentral/fileexchange/2662-cmrmap-m>`_
       by Carey Rappaport
     """
-    return sorted(cm.cmap_d)
+    return sorted(cm._cmap_registry)
 
 
 def _setup_pyplot_info_docstrings():
diff --git a/lib/matplotlib/tests/test_colors.py b/lib/matplotlib/tests/test_colors.py
@@ -70,38 +70,6 @@ def test_register_cmap():
         cm.register_cmap()
 
 
-@pytest.mark.skipif(matplotlib.__version__ < "3.5",
-                    reason="This test modifies the global state of colormaps.")
-def test_colormap_global_unchanged_state():
-    new_cm = plt.get_cmap('viridis')
-    new_cm.set_over('b')
-    # Make sure that this didn't mess with the original viridis cmap
-    assert new_cm != plt.get_cmap('viridis')
-
-    # Also test that pyplot access doesn't mess the original up
-    new_cm = plt.cm.viridis
-    new_cm.set_over('b')
-    assert new_cm != plt.get_cmap('viridis')
-
-
-@pytest.mark.skipif(matplotlib.__version__ < "3.4",
-                    reason="This test modifies the global state of colormaps.")
-def test_colormap_global_get_warn():
-    new_cm = plt.get_cmap('viridis')
-    # Store the old value so we don't override the state later on.
-    orig_cmap = copy.copy(new_cm)
-    new_cm.set_under('k')
-    with pytest.warns(cbook.MatplotlibDeprecationWarning,
-                      match="You are modifying the state of a globally"):
-        # This should warn now because we've modified the global state
-        # without registering it
-        plt.get_cmap('viridis')
-
-    # Test that re-registering the original cmap clears the warning
-    plt.register_cmap(cmap=orig_cmap)
-    plt.get_cmap('viridis')
-
-
 def test_colormap_global_set_warn():
     new_cm = plt.get_cmap('viridis')
     # Store the old value so we don't override the state later on.
@@ -126,6 +94,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)
@@ -874,7 +853,7 @@ def test_pandas_iterable(pd):
     assert_array_equal(cm1.colors, cm2.colors)
 
 
-@pytest.mark.parametrize('name', sorted(cm.cmap_d))
+@pytest.mark.parametrize('name', sorted(plt.colormaps()))
 def test_colormap_reversing(name):
     """
     Check the generated _lut data of a colormap and corresponding reversed
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)
 
