diff --git a/doc/api/next_api_changes/deprecations/30531-TH.rst b/doc/api/next_api_changes/deprecations/30531-TH.rst new file mode 100644 index 000000000000..19d51fd2fb6c --- /dev/null +++ b/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). diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py index f60c8eb48134..efc41efb1e66 100644 --- 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 =