Merge pull request matplotlib#23668 from tacaswell/api_deprecate_cmap_functions

Api deprecate cmap functions

Author: QuLogic

doc/api/next_api_changes/deprecations/23668-TC.rst

@@ -0,0 +1,22 @@
+Pending deprecation 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 with the intention of deprecation in Matplotlib 3.7.  The
+following functions have been marked for pending deprecation:
+
+- `matplotlib.cm.get_cmap` - use ``matplotlib.colormaps[name]`` instead
+- `matplotlib.cm.register_cmap` - use ``matplotlib.colormaps.register`` instead
+- `matplotlib.cm.unregister_cmap` - use ``matplotlib.colormaps.unregister`` instead
+- ``matplotlib.pyplot.register_cmap`` - use ``matplotlib.colormaps.register`` instead
+
+The `matplotlib.pyplot.get_cmap` function will stay available for backward compatibility.

doc/api/pyplot_summary.rst

@@ -64,6 +64,7 @@ Plotting commands
    gcf
    gci
    get
+   get_cmap
    get_figlabels
    get_fignums
    getp

doc/users/next_whats_new/resample_colormaps.rst

@@ -0,0 +1,13 @@
+Colormap method for creating a different lookup table size
+----------------------------------------------------------
+The new method `.Colormap.resampled` creates a new `.Colormap` instance
+with the specified lookup table size. This is a replacement for manipulating
+the lookup table size via ``get_cmap``.
+
+Use::
+
+    get_cmap(name).resampled(N)
+
+instead of::
+
+    get_cmap(name, lut=N)

examples/images_contours_and_fields/contour_image.py

@@ -41,7 +41,7 @@
 axs = _axs.flatten()
 
 cset1 = axs[0].contourf(X, Y, Z, levels, norm=norm,
-                        cmap=cm.get_cmap(cmap, len(levels) - 1))
+                        cmap=cmap.resampled(len(levels) - 1))
 # It is not necessary, but for the colormap, we need only the
 # number of levels minus 1.  To avoid discretization error, use
 # either this number or a large number such as the default (256).

examples/images_contours_and_fields/image_annotated_heatmap.py

@@ -39,6 +39,7 @@
 
 import numpy as np
 import matplotlib
+import matplotlib as mpl
 import matplotlib.pyplot as plt
 # sphinx_gallery_thumbnail_number = 2
 
@@ -272,7 +273,7 @@ def annotate_heatmap(im, data=None, valfmt="{x:.2f}",
 fmt = matplotlib.ticker.FuncFormatter(lambda x, pos: qrates[::-1][norm(x)])
 
 im, _ = heatmap(data, y, x, ax=ax3,
-                cmap=plt.get_cmap("PiYG", 7), norm=norm,
+                cmap=mpl.colormaps["PiYG"].resampled(7), norm=norm,
                 cbar_kw=dict(ticks=np.arange(-3, 4), format=fmt),
                 cbarlabel="Quality Rating")
 

examples/lines_bars_and_markers/multivariate_marker_plot.py

@@ -31,7 +31,7 @@
 positions = np.random.normal(size=(N, 2)) * 5
 data = zip(skills, takeoff_angles, thrusts, successful, positions)
 
-cmap = plt.cm.get_cmap("plasma")
+cmap = plt.colormaps["plasma"]
 fig, ax = plt.subplots()
 fig.suptitle("Throwing success", size=14)
 for skill, takeoff, thrust, mood, pos in data:

lib/matplotlib/cm.py

@@ -201,6 +201,11 @@ def unregister(self, name):
 globals().update(_colormaps)
 
 
+@_api.deprecated(
+    '3.6',
+    pending=True,
+    alternative="``matplotlib.colormaps.register_cmap(name)``"
+)
 def register_cmap(name=None, cmap=None, *, override_builtin=False):
     """
     Add a colormap to the set recognized by :func:`get_cmap`.
@@ -244,13 +249,10 @@ def register_cmap(name=None, cmap=None, *, override_builtin=False):
     _colormaps._allow_override_builtin = False
 
 
-def get_cmap(name=None, lut=None):
+def _get_cmap(name=None, lut=None):
     """
     Get a colormap instance, defaulting to rc values if *name* is None.
 
-    Colormaps added with :func:`register_cmap` take precedence over
-    built-in colormaps.
-
     Parameters
     ----------
     name : `matplotlib.colors.Colormap` or str or None, default: None
@@ -260,6 +262,10 @@ def get_cmap(name=None, lut=None):
     lut : int or None, default: None
         If *name* is not already a Colormap instance and *lut* is not None, the
         colormap will be resampled to have *lut* entries in the lookup table.
+
+    Returns
+    -------
+    Colormap
     """
     if name is None:
         name = mpl.rcParams['image.cmap']
@@ -269,9 +275,20 @@ def get_cmap(name=None, lut=None):
     if lut is None:
         return _colormaps[name]
     else:
-        return _colormaps[name]._resample(lut)
+        return _colormaps[name].resampled(lut)
 
+# do it in two steps like this so we can have an un-deprecated version in
+# pyplot.
+get_cmap = _api.deprecated(
+    '3.6', pending=True, alternative="``matplotlib.colormaps[name]``"
+)(_get_cmap)
 
+
+@_api.deprecated(
+    '3.6',
+    pending=True,
+    alternative="``matplotlib.colormaps.unregister_cmap(name)``"
+)
 def unregister_cmap(name):
     """
     Remove a colormap recognized by :func:`get_cmap`.
@@ -550,8 +567,8 @@ def set_cmap(self, cmap):
         cmap : `.Colormap` or str or None
         """
         in_init = self.cmap is None
-        cmap = get_cmap(cmap)
-        self.cmap = cmap
+
+        self.cmap = _ensure_cmap(cmap)
         if not in_init:
             self.changed()  # Things are not set up properly yet.
 
@@ -663,3 +680,26 @@ def changed(self):
     *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm*
     name together with *vmin*/*vmax* is acceptable).""",
 )
+
+
+def _ensure_cmap(cmap):
+    """
+    Ensure that we have a `.Colormap` object.
+
+    Parameters
+    ----------
+    cmap : None, str, Colormap
+
+        - if a `Colormap`, return it
+        - if a string, look it up in mpl.colormaps
+        - if None, look up the default color map in mpl.colormaps
+
+    Returns
+    -------
+    Colormap
+    """
+    if isinstance(cmap, colors.Colormap):
+        return cmap
+    return mpl.colormaps[
+        cmap if cmap is not None else mpl.rcParams['image.cmap']
+    ]

lib/matplotlib/colors.py

@@ -853,8 +853,17 @@ def is_gray(self):
         return (np.all(self._lut[:, 0] == self._lut[:, 1]) and
                 np.all(self._lut[:, 0] == self._lut[:, 2]))
 
-    def _resample(self, lutsize):
+    def resampled(self, lutsize):
         """Return a new colormap with *lutsize* entries."""
+        if hasattr(self, '_resample'):
+            _api.warn_external(
+                "The ability to resample a color map is now public API "
+                f"However the class {type(self)} still only implements "
+                "the previous private _resample method.  Please update "
+                "your class."
+            )
+            return self._resample(lutsize)
+
         raise NotImplementedError()
 
     def reversed(self, name=None):
@@ -1049,7 +1058,7 @@ def from_list(name, colors, N=256, gamma=1.0):
 
         return LinearSegmentedColormap(name, cdict, N, gamma)
 
-    def _resample(self, lutsize):
+    def resampled(self, lutsize):
         """Return a new colormap with *lutsize* entries."""
         new_cmap = LinearSegmentedColormap(self.name, self._segmentdata,
                                            lutsize)
@@ -1153,7 +1162,7 @@ def _init(self):
         self._isinit = True
         self._set_extremes()
 
-    def _resample(self, lutsize):
+    def resampled(self, lutsize):
         """Return a new colormap with *lutsize* entries."""
         colors = self(np.linspace(0, 1, lutsize))
         new_cmap = ListedColormap(colors, name=self.name)

lib/matplotlib/pyplot.py

@@ -68,7 +68,7 @@
 from matplotlib.scale import get_scale_names
 
 from matplotlib import cm
-from matplotlib.cm import _colormaps as colormaps, get_cmap, register_cmap
+from matplotlib.cm import _colormaps as colormaps, register_cmap
 from matplotlib.colors import _color_sequences as color_sequences
 
 import numpy as np
@@ -2075,6 +2075,13 @@ def clim(vmin=None, vmax=None):
     im.set_clim(vmin, vmax)
 
 
+# eventually this implementation should move here, use indirection for now to
+# avoid having two copies of the code floating around.
+def get_cmap(name=None, lut=None):
+    return cm._get_cmap(name=name, lut=lut)
+get_cmap.__doc__ = cm._get_cmap.__doc__
+
+
 def set_cmap(cmap):
     """
     Set the default colormap, and applies it to the current image if any.
@@ -2090,7 +2097,7 @@ def set_cmap(cmap):
     matplotlib.cm.register_cmap
     matplotlib.cm.get_cmap
     """
-    cmap = cm.get_cmap(cmap)
+    cmap = get_cmap(cmap)
 
     rc('image', cmap=cmap.name)
     im = gci()

lib/matplotlib/streamplot.py

@@ -187,7 +187,7 @@ def streamplot(axes, x, y, u, v, density=1, linewidth=None, color=None,
     if use_multicolor_lines:
         if norm is None:
             norm = mcolors.Normalize(color.min(), color.max())
-        cmap = cm.get_cmap(cmap)
+        cmap = cm._ensure_cmap(cmap)
 
     streamlines = []
     arrows = []