diff --git a/doc/api/next_api_changes/deprecations/24846-ES.rst b/doc/api/next_api_changes/deprecations/24846-ES.rst new file mode 100644 index 000000000000..c70168706afb --- /dev/null +++ b/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 +`_ 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. diff --git a/lib/matplotlib/cm.py b/lib/matplotlib/cm.py index 2b805973fe50..d170b7d6b37f 100644 --- a/lib/matplotlib/cm.py +++ b/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,9 +295,8 @@ 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)``" @@ -309,11 +304,8 @@ def _get_cmap(name=None, lut=None): )(_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`. diff --git a/lib/matplotlib/tests/test_colors.py b/lib/matplotlib/tests/test_colors.py index 5d34b8b6d2e4..ff893e71acdb 100644 --- a/lib/matplotlib/tests/test_colors.py +++ b/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,25 +77,25 @@ 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 @@ -103,7 +103,7 @@ def test_register_cmap(): 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)