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

- matplotlib.cm.get_cmap
- matplotlib.cm.register_cmap
- matplotlib.cm.unregister_cmap
- matplotlib.pyplot.register_cmap

in preference for working with the ColormapRegistry on the top level module.

Co-authored-by: Greg Lucas <greg.m.lucas@gmail.com>

Author: tacaswell

doc/api/next_api_changes/deprecations/23668-TC.rst

@@ -0,0 +1,23 @@
+Pending deprecation top-level cmap registration and access functions in ``mpl.cm``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As part of a `multi-step process
+<https://github.com/matplotlib/matplotlib/issues/20853>`_ we are refactoring
+the global state for managing the registered colormaps.
+
+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.  The
+following functions have been marked for pending deprecation:
+
+- `matplotlib.cm.get_cmap`
+- `matplotlib.cm.register_cmap`
+- `matplotlib.cm.unregister_cmap`
+- ``matplotlib.pyplot.register_cmap``
+
+The ``matplotlib.pyplot.get_cmap`` function is intentionally exempted from this
+deprecation process.

lib/matplotlib/cm.py

@@ -201,6 +201,11 @@ def unregister(self, name):
 globals().update(_colormaps)
 
 
+@_api.deprecated(
+    '3.6',
+    pending=True,
+    alternative="``matplotlib.colormaps.register_cmap(name)``"
+)
 def register_cmap(name=None, cmap=None, *, override_builtin=False):
     """
     Add a colormap to the set recognized by :func:`get_cmap`.
@@ -244,7 +249,7 @@ def register_cmap(name=None, cmap=None, *, override_builtin=False):
     _colormaps._allow_override_builtin = False
 
 
-def get_cmap(name=None, lut=None):
+def _get_cmap(name=None, lut=None):
     """
     Get a colormap instance, defaulting to rc values if *name* is None.
 
@@ -260,6 +265,10 @@ def get_cmap(name=None, lut=None):
     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.
+
+    Returns
+    -------
+    Colormap
     """
     if name is None:
         name = mpl.rcParams['image.cmap']
@@ -271,7 +280,18 @@ def get_cmap(name=None, lut=None):
     else:
         return _colormaps[name].resampled(lut)
 
+# do it in two steps like this so we can have an un-deprecated version in
+# pyplot.
+get_cmap = _api.deprecated(
+    '3.6', pending=True, alternative="``matplotlib.colormaps[name]``"
+)(_get_cmap)
+
 
+@_api.deprecated(
+    '3.6',
+    pending=True,
+    alternative="``matplotlib.colormaps.unregister_cmap(name)``"
+)
 def unregister_cmap(name):
     """
     Remove a colormap recognized by :func:`get_cmap`.

lib/matplotlib/pyplot.py

@@ -68,7 +68,7 @@
 from matplotlib.scale import get_scale_names
 
 from matplotlib import cm
-from matplotlib.cm import _colormaps as colormaps, get_cmap, register_cmap
+from matplotlib.cm import _colormaps as colormaps, register_cmap
 from matplotlib.colors import _color_sequences as color_sequences
 
 import numpy as np
@@ -2022,7 +2022,7 @@ def get_plot_commands():
     # This works by searching for all functions in this module and removing
     # a few hard-coded exclusions, as well as all of the colormap-setting
     # functions, and anything marked as private with a preceding underscore.
-    exclude = {'colormaps', 'colors', 'get_plot_commands',
+    exclude = {'colormaps', 'colors', 'get_plot_commands', 'get_cmap',
                *_NON_PLOT_COMMANDS, *colormaps}
     this_module = inspect.getmodule(get_plot_commands)
     return sorted(
@@ -2069,6 +2069,11 @@ def clim(vmin=None, vmax=None):
     im.set_clim(vmin, vmax)
 
 
+def get_cmap(name=None, lut=None):
+    return cm._get_cmap(name=name, lut=lut)
+get_cmap.__doc__ = cm._get_cmap.__doc__
+
+
 def set_cmap(cmap):
     """
     Set the default colormap, and applies it to the current image if any.
@@ -2084,7 +2089,7 @@ def set_cmap(cmap):
     matplotlib.cm.register_cmap
     matplotlib.cm.get_cmap
     """
-    cmap = colormaps[cmap]
+    cmap = get_cmap(cmap)
 
     rc('image', cmap=cmap.name)
     im = gci()

lib/matplotlib/tests/test_colors.py

@@ -65,44 +65,71 @@ def test_resampled():
 
 
 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(
+            PendingDeprecationWarning,
+            match=r"matplotlib\.colormaps\.register_cmap\(name\)"
+    ):
+        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()
-
-    cm.unregister_cmap(target)
+        with pytest.warns(
+            PendingDeprecationWarning,
+            match=r"matplotlib\.colormaps\.register_cmap\(name\)"
+        ):
+            cm.register_cmap()
+
+    with pytest.warns(
+            PendingDeprecationWarning,
+            match=r"matplotlib\.colormaps\.unregister_cmap\(name\)"
+    ):
+        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(
+                PendingDeprecationWarning,
+                match=r"matplotlib\.colormaps\[name\]"
+        ):
+            cm.get_cmap(target)
+    with pytest.warns(
+            PendingDeprecationWarning,
+            match=r"matplotlib\.colormaps\.unregister_cmap\(name\)"
+    ):
+        # 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(
+            PendingDeprecationWarning,
+            match=r"matplotlib\.colormaps\.register_cmap\(name\)"
+        ):
+            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():