Merge pull request matplotlib#24846 from QuLogic/cm-deprecations

Promote pending cm deprecations to full deprecations

Author: ksunden

doc/api/next_api_changes/deprecations/24846-ES.rst

@@ -0,0 +1,30 @@
+Deprecation of 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.
+
+In Matplotlib 3.7, the following functions have been marked for deprecation:
+
+- ``matplotlib.cm.get_cmap``; use ``matplotlib.colormaps[name]`` instead if you
+  have a `str`.
+
+  **Added 3.6.1** Use `matplotlib.cm.ColormapRegistry.get_cmap` if you
+  have a string, `None` or a `matplotlib.colors.Colormap` object that you want
+  to convert to a `matplotlib.colors.Colormap` instance.
+- ``matplotlib.cm.register_cmap``; use `matplotlib.colormaps.register
+  <.ColormapRegistry.register>` instead
+- ``matplotlib.cm.unregister_cmap``; use `matplotlib.colormaps.unregister
+  <.ColormapRegistry.unregister>` instead
+- ``matplotlib.pyplot.register_cmap``; use `matplotlib.colormaps.register
+  <.ColormapRegistry.register>` instead
+
+The `matplotlib.pyplot.get_cmap` function will stay available for backward
+compatibility.

lib/matplotlib/cm.py

@@ -220,11 +220,7 @@ def get_cmap(self, cmap):
 globals().update(_colormaps)
 
 
-@_api.deprecated(
-    '3.6',
-    pending=True,
-    alternative="``matplotlib.colormaps.register(name)``"
-)
+@_api.deprecated("3.7", alternative="``matplotlib.colormaps.register(name)``")
 def register_cmap(name=None, cmap=None, *, override_builtin=False):
     """
     Add a colormap to the set recognized by :func:`get_cmap`.
@@ -299,21 +295,17 @@ def _get_cmap(name=None, lut=None):
 # do it in two steps like this so we can have an un-deprecated version in
 # pyplot.
 get_cmap = _api.deprecated(
-    '3.6',
+    '3.7',
     name='get_cmap',
-    pending=True,
     alternative=(
         "``matplotlib.colormaps[name]`` " +
         "or ``matplotlib.colormaps.get_cmap(obj)``"
     )
 )(_get_cmap)
 
 
-@_api.deprecated(
-    '3.6',
-    pending=True,
-    alternative="``matplotlib.colormaps.unregister(name)``"
-)
+@_api.deprecated("3.7",
+                 alternative="``matplotlib.colormaps.unregister(name)``")
 def unregister_cmap(name):
     """
     Remove a colormap recognized by :func:`get_cmap`.

lib/matplotlib/tests/test_colors.py

@@ -68,7 +68,7 @@ def test_register_cmap():
     new_cm = mpl.colormaps["viridis"]
     target = "viridis2"
     with pytest.warns(
-            PendingDeprecationWarning,
+            mpl.MatplotlibDeprecationWarning,
             match=r"matplotlib\.colormaps\.register\(name\)"
     ):
         cm.register_cmap(target, new_cm)
@@ -77,33 +77,33 @@ def test_register_cmap():
     with pytest.raises(ValueError,
                        match="Arguments must include a name or a Colormap"):
         with pytest.warns(
-            PendingDeprecationWarning,
+            mpl.MatplotlibDeprecationWarning,
             match=r"matplotlib\.colormaps\.register\(name\)"
         ):
             cm.register_cmap()
 
     with pytest.warns(
-            PendingDeprecationWarning,
+            mpl.MatplotlibDeprecationWarning,
             match=r"matplotlib\.colormaps\.unregister\(name\)"
     ):
         cm.unregister_cmap(target)
     with pytest.raises(ValueError,
                        match=f'{target!r} is not a valid value for name;'):
         with pytest.warns(
-                PendingDeprecationWarning,
+                mpl.MatplotlibDeprecationWarning,
                 match=r"matplotlib\.colormaps\[name\]"
         ):
             cm.get_cmap(target)
     with pytest.warns(
-            PendingDeprecationWarning,
+            mpl.MatplotlibDeprecationWarning,
             match=r"matplotlib\.colormaps\.unregister\(name\)"
     ):
         # test that second time is error free
         cm.unregister_cmap(target)
 
     with pytest.raises(TypeError, match="'cmap' must be"):
         with pytest.warns(
-            PendingDeprecationWarning,
+            mpl.MatplotlibDeprecationWarning,
             match=r"matplotlib\.colormaps\.register\(name\)"
         ):
             cm.register_cmap('nome', cmap='not a cmap')
@@ -137,7 +137,7 @@ def test_double_register_builtin_cmap():
             mpl.colormaps[name], name=name, force=True
         )
     with pytest.raises(ValueError, match='A colormap named "viridis"'):
-        with pytest.warns(PendingDeprecationWarning):
+        with pytest.warns(mpl.MatplotlibDeprecationWarning):
             cm.register_cmap(name, mpl.colormaps[name])
     with pytest.warns(UserWarning):
         # TODO is warning more than once!
@@ -148,7 +148,7 @@ def test_unregister_builtin_cmap():
     name = "viridis"
     match = f'cannot unregister {name!r} which is a builtin colormap.'
     with pytest.raises(ValueError, match=match):
-        with pytest.warns(PendingDeprecationWarning):
+        with pytest.warns(mpl.MatplotlibDeprecationWarning):
             cm.unregister_cmap(name)