MNT: Pending-deprecate setting colormap extremes

Per matplotlib#29141 we have the long-term plan to make colormaps immutable. As a
result, the in-place modifications have to be removed. We take this
particularly slow with at least two minor releases of pending
deprecation and two further releases of actual deprecations. As it's
quite a common concept and migrating away will take time.

Author: timhoffm

doc/api/next_api_changes/deprecations/30531-TH.rst

@@ -0,0 +1,16 @@
+In-place modifications of colormaps
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Colormaps are planned to become immutable in the long term.
+
+As a first step, in-place modifications of colormaps are now pending-deprecated.
+This affects the following methods of `.Colormap`:
+
+- `.Colormap.set_bad` - use ``cmap.with_extremes(bad=...)`` instead
+- `.Colormap.set_under` - use ``cmap.with_extremes(under=...)`` instead
+- `.Colormap.set_over` - use ``cmap.with_extremes(over=...)`` instead
+- `.Colormap.set_extremes` - use ``cmap.with_extremes(...)`` instead
+
+Use the respective `.Colormap.with_extremes` and appropriate keyword arguments
+instead which returns a copy of the colormap (available since matplotlib 3.4).
+Alternatively, if you create the colormap yourself, you can also pass the
+respective arguments to the constructor (available since matplotlib 3.11).

lib/matplotlib/colors.py

@@ -871,6 +871,10 @@ def get_bad(self):
         self._ensure_inited()
         return np.array(self._lut[self._i_bad])
 
+    @_api.deprecated(
+        "3.11",
+        pending=True,
+        alternative="cmap.with_extremes(bad=...) or Colormap(bad=...)")
     def set_bad(self, color='k', alpha=None):
         """Set the color for masked values."""
         self._set_extremes(bad=(color, alpha))
@@ -880,6 +884,10 @@ def get_under(self):
         self._ensure_inited()
         return np.array(self._lut[self._i_under])
 
+    @_api.deprecated(
+        "3.11",
+        pending=True,
+        alternative="cmap.with_extremes(under=...) or Colormap(under=...)")
     def set_under(self, color='k', alpha=None):
         """Set the color for low out-of-range values."""
         self._set_extremes(under=(color, alpha))
@@ -889,10 +897,19 @@ def get_over(self):
         self._ensure_inited()
         return np.array(self._lut[self._i_over])
 
+    @_api.deprecated(
+        "3.11",
+        pending=True,
+        alternative="cmap.with_extremes(over=...) or Colormap(over=...)")
     def set_over(self, color='k', alpha=None):
         """Set the color for high out-of-range values."""
         self._set_extremes(over=(color, alpha))
 
+    @_api.deprecated(
+        "3.11",
+        pending=True,
+        alternative="cmap.with_extremes(bad=..., under=..., over=...) or "
+                    "Colormap(bad=..., under=..., over=...)")
     def set_extremes(self, *, bad=None, under=None, over=None):
         """
         Set the colors for masked (*bad*) values and, when ``norm.clip =

lib/matplotlib/tests/test_colors.py

@@ -111,7 +111,8 @@ def test_colormap_copy():
     with np.errstate(invalid='ignore'):
         ret1 = copied_cmap([-1, 0, .5, 1, np.nan, np.inf])
     cmap2 = copy.copy(copied_cmap)
-    cmap2.set_bad('g')
+    with pytest.warns(PendingDeprecationWarning):
+        cmap2.set_bad('g')
     with np.errstate(invalid='ignore'):
         ret2 = copied_cmap([-1, 0, .5, 1, np.nan, np.inf])
     assert_array_equal(ret1, ret2)
@@ -121,7 +122,8 @@ def test_colormap_copy():
     with np.errstate(invalid='ignore'):
         ret1 = copied_cmap([-1, 0, .5, 1, np.nan, np.inf])
     cmap2 = copy.copy(copied_cmap)
-    cmap2.set_bad('g')
+    with pytest.warns(PendingDeprecationWarning):
+        cmap2.set_bad('g')
     with np.errstate(invalid='ignore'):
         ret2 = copied_cmap([-1, 0, .5, 1, np.nan, np.inf])
     assert_array_equal(ret1, ret2)
@@ -135,7 +137,8 @@ def test_colormap_equals():
     # But the same data should be equal
     assert cm_copy == cmap
     # Change the copy
-    cm_copy.set_bad('y')
+    with pytest.warns(PendingDeprecationWarning):
+        cm_copy.set_bad('y')
     assert cm_copy != cmap
     # Make sure we can compare different sizes without failure
     cm_copy._lut = cm_copy._lut[:10, :]
@@ -1535,7 +1538,8 @@ def test_get_under_over_bad():
 def test_non_mutable_get_values(kind):
     cmap = copy.copy(mpl.colormaps['viridis'])
     init_value = getattr(cmap, f'get_{kind}')()
-    getattr(cmap, f'set_{kind}')('k')
+    with pytest.warns(PendingDeprecationWarning):
+        getattr(cmap, f'set_{kind}')('k')
     black_value = getattr(cmap, f'get_{kind}')()
     assert np.all(black_value == [0, 0, 0, 1])
     assert not np.all(init_value == black_value)