MNT: Pending-deprecate setting colormap extremes

timhoffm · timhoffm · commit 0ff2086b05b3 · 2025-09-08T23:11:53.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/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 =
