MNT: Pending-deprecate setting colormap extremes

timhoffm · timhoffm · commit e2090f48faf8 · 2025-09-08T23:23:24.000+02:00
Per #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.
diff --git a/doc/api/next_api_changes/deprecations/30531-TH.rst b/doc/api/next_api_changes/deprecations/30531-TH.rst
@@ -0,0 +1,16 @@
+In-place modifications of colormaps
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Colormaps are planned to become immuatable 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 with 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).
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -875,6 +875,10 @@ def get_bad(self):
             self._init()
         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._rgba_bad = to_rgba(color, alpha)
@@ -887,6 +891,10 @@ def get_under(self):
             self._init()
         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._rgba_under = to_rgba(color, alpha)
@@ -899,12 +907,21 @@ def get_over(self):
             self._init()
         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._rgba_over = to_rgba(color, alpha)
         if self._isinit:
             self._set_extremes()
 
+    @_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 =
