Skip to content

Promote pending cm deprecations to full deprecations #24846

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 31, 2022
Merged

Promote pending cm deprecations to full deprecations #24846

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions doc/api/next_api_changes/deprecations/24846-ES.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
16 changes: 4 additions & 12 deletions lib/matplotlib/cm.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -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`.
Expand Down
16 changes: 8 additions & 8 deletions lib/matplotlib/tests/test_colors.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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')
Expand Down Expand Up @@ -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!
Expand All @@ -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)


Expand Down