API: Add pending deprecation to mpl.cm top level functions

tacaswell · tacaswell · commit 90dba9fbbbbb · 2022-08-18T19:35:07.000-04:00
- .get_cmap
- .register_cmap
- .unregister_cmap

in preference for working with the ColormapRegistry on the top level module.
diff --git a/doc/api/next_api_changes/deprecations/XYZ-TC.rst b/doc/api/next_api_changes/deprecations/XYZ-TC.rst
@@ -0,0 +1,14 @@
+Deprecated top-level cmap registration and access functions in ``mpl.cm``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As part of `multi-step process
+<https://github.com/matplotlib/matplotlib/issues/20853>`_ we are refactoring
+global state for managing the registered colormap.
+
+In Matplotlib 3.5 we added a `.ColormapRegistry` class and exposed an
+instance at the top level as ``matplotlib.colormaps``.  The existing
+top level functions in `matplotlib.cm` (``get_cmap``, ``register_cmap``,
+``unregister_cmap``) were changed to be aliases around the same instance.
+
+In Matplotlib 3.6 we have marked those top level functions as pending
+deprecation with the intention of deprecation in Matplotlib 3.7.
diff --git a/lib/matplotlib/cm.py b/lib/matplotlib/cm.py
@@ -201,6 +201,11 @@ def unregister(self, name):
 globals().update(_colormaps)
 
 
+@_api.deprecated(
+    '3.6',
+    pending=True,
+    alternative="``matplotilb.colormaps.unregister_cmap(name)``"
+)
 def register_cmap(name=None, cmap=None, *, override_builtin=False):
     """
     Add a colormap to the set recognized by :func:`get_cmap`.
@@ -244,6 +249,11 @@ def register_cmap(name=None, cmap=None, *, override_builtin=False):
     _colormaps._allow_override_builtin = False
 
 
+@_api.deprecated(
+    '3.6',
+    pending=True,
+    alternative="``matplotilb.colormaps[name]``"
+)
 def get_cmap(name=None, lut=None):
     """
     Get a colormap instance, defaulting to rc values if *name* is None.
@@ -272,6 +282,11 @@ def get_cmap(name=None, lut=None):
         return _colormaps[name].resample(lut)
 
 
+@_api.deprecated(
+    '3.6',
+    pending=True,
+    alternative="``matplotilb.colormaps.unregister_cmap(name)``"
+)
 def unregister_cmap(name):
     """
     Remove a colormap recognized by :func:`get_cmap`.
diff --git a/lib/matplotlib/tests/test_colors.py b/lib/matplotlib/tests/test_colors.py
@@ -65,44 +65,53 @@ def test_resample():
 
 
 def test_register_cmap():
-    new_cm = cm.get_cmap("viridis")
+    new_cm = mpl.colormaps["viridis"]
     target = "viridis2"
-    cm.register_cmap(target, new_cm)
-    assert plt.get_cmap(target) == new_cm
+    with pytest.warns():
+        cm.register_cmap(target, new_cm)
+    assert mpl.colormaps[target] == new_cm
 
     with pytest.raises(ValueError,
                        match="Arguments must include a name or a Colormap"):
-        cm.register_cmap()
+        with pytest.warns():
+            cm.register_cmap()
 
-    cm.unregister_cmap(target)
+    with pytest.warns():
+        cm.unregister_cmap(target)
     with pytest.raises(ValueError,
                        match=f'{target!r} is not a valid value for name;'):
-        cm.get_cmap(target)
-    # test that second time is error free
-    cm.unregister_cmap(target)
+        with pytest.warns():
+            cm.get_cmap(target)
+    with pytest.warns():
+        # test that second time is error free
+        cm.unregister_cmap(target)
 
     with pytest.raises(TypeError, match="'cmap' must be"):
-        cm.register_cmap('nome', cmap='not a cmap')
+        with pytest.warns():
+            cm.register_cmap('nome', cmap='not a cmap')
 
 
 def test_double_register_builtin_cmap():
     name = "viridis"
     match = f"Re-registering the builtin cmap {name!r}."
     with pytest.raises(ValueError, match=match):
         matplotlib.colormaps.register(
-            cm.get_cmap(name), name=name, force=True
+            mpl.colormaps[name], name=name, force=True
         )
     with pytest.raises(ValueError, match='A colormap named "viridis"'):
-        cm.register_cmap(name, cm.get_cmap(name))
+        with pytest.warns():
+            cm.register_cmap(name, mpl.colormaps[name])
     with pytest.warns(UserWarning):
-        cm.register_cmap(name, cm.get_cmap(name), override_builtin=True)
+        # TODO is warning more than once!
+        cm.register_cmap(name, mpl.colormaps[name], override_builtin=True)
 
 
 def test_unregister_builtin_cmap():
     name = "viridis"
     match = f'cannot unregister {name!r} which is a builtin colormap.'
     with pytest.raises(ValueError, match=match):
-        cm.unregister_cmap(name)
+        with pytest.warns():
+            cm.unregister_cmap(name)
 
 
 def test_colormap_copy():
