Removed tests, updated documentation with code style for removed functions, moved code to pyplot from cm

UFEddy · UFEddy · commit a8a4f7f02206 · 2023-10-10T21:25:20.000-04:00
diff --git a/ci/mypy-stubtest-allowlist.txt b/ci/mypy-stubtest-allowlist.txt
@@ -49,8 +49,6 @@ matplotlib.figure.Figure.set_constrained_layout
 matplotlib.figure.Figure.set_constrained_layout_pads
 matplotlib.figure.Figure.set_tight_layout
 
-# 3.7 deprecations
-
 # 3.8 deprecations
 matplotlib.cbook.get_sample_data
 matplotlib.contour.ContourSet.allkinds
diff --git a/doc/api/next_api_changes/removals/26965-ER.rst b/doc/api/next_api_changes/removals/26965-ER.rst
@@ -1,20 +1,23 @@
-``matplotlib.cm.register_cmap``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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.
 
-... was removed as it was deprecated during 3.7. Use `matplotlib.colormaps.register` instead.
+In Matplotlib 3.7, the following functions have been marked for deprecation:
 
-``matplotlib.cm.unregister_cmap``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- ``matplotlib.cm.get_cmap``; use ``matplotlib.colormaps[name]`` instead if you
+  have a `str`.
 
-... was removed as it was deprecated during 3.7. Use `matplotlib.colormaps.unregister` instead.
+  **Added 3.6.1** Use `matplotlib.cm.ColormapRegistry.get_cmap` if you
+  have a string, `None` or a `matplotlib.colors.Colormap` object that you want
+  to convert to a `matplotlib.colors.Colormap` instance.
+- ``matplotlib.cm.register_cmap``; use `matplotlib.colormaps.register
+  <.ColormapRegistry.register>` instead
+- ``matplotlib.cm.unregister_cmap``; use `matplotlib.colormaps.unregister
+  <.ColormapRegistry.unregister>` instead
+- ``matplotlib.pyplot.register_cmap``; use `matplotlib.colormaps.register
+  <.ColormapRegistry.register>` instead
 
-``matplotlib.pyplot.register_cmap``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-... was removed as it was deprecated during 3.7. Use `matplotlib.colormaps.register` instead.
-
-``matplotlib.cm.get_cmap``
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-... was removed as it was deprecated during 3.7. Use `matplotlib.cm.ColormapRegistry.get_cmap` if you have a string, `None`
-or a `matplotlib.colors.Colormap` object that you want to convert to a `matplotlib.colors.Colormap` instance.
+The `matplotlib.pyplot.get_cmap` function will stay available for backward
+compatibility.
diff --git a/doc/api/prev_api_changes/api_changes_0.99.rst b/doc/api/prev_api_changes/api_changes_0.99.rst
@@ -7,7 +7,7 @@ Changes in 0.99
   NumPy arrays.
 
 * User-generated colormaps can now be added to the set recognized
-  by :func:`matplotlib.cm.get_cmap`.  Colormaps can be made the
+  by ``matplotlib.cm.get_cmap``.  Colormaps can be made the
   default and applied to the current image using
   :func:`matplotlib.pyplot.set_cmap`.
 
diff --git a/doc/api/prev_api_changes/api_changes_3.2.0/behavior.rst b/doc/api/prev_api_changes/api_changes_3.2.0/behavior.rst
@@ -294,7 +294,7 @@ Exception changes
 ~~~~~~~~~~~~~~~~~
 Various APIs that raised a `ValueError` for incorrectly typed inputs now raise
 `TypeError` instead: `.backend_bases.GraphicsContextBase.set_clip_path`,
-``blocking_input.BlockingInput.__call__``, `.cm.register_cmap`, `.dviread.DviFont`,
+``blocking_input.BlockingInput.__call__``, ``matplotlib.cm.register_cmap``, `.dviread.DviFont`,
 `.rcsetup.validate_hatch`, ``.rcsetup.validate_animation_writer_path``, `.spines.Spine`,
 many classes in the :mod:`matplotlib.transforms` module and :mod:`matplotlib.tri`
 package, and Axes methods that take a ``norm`` parameter.
diff --git a/doc/api/prev_api_changes/api_changes_3.3.0/deprecations.rst b/doc/api/prev_api_changes/api_changes_3.3.0/deprecations.rst
@@ -55,7 +55,7 @@ Please pass capstyles ("miter", "round", "bevel") and joinstyles ("butt",
 
 Passing raw data to ``register_cmap()``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Passing raw data via parameters *data* and *lut* to `.register_cmap()` is
+Passing raw data via parameters *data* and *lut* to ``matplotlib.cm.register_cmap()`` is
 deprecated. Instead, explicitly create a `.LinearSegmentedColormap` and pass
 it via the *cmap* parameter:
 ``register_cmap(cmap=LinearSegmentedColormap(name, data, lut))``.
diff --git a/doc/api/prev_api_changes/api_changes_3.4.0/behaviour.rst b/doc/api/prev_api_changes/api_changes_3.4.0/behaviour.rst
@@ -203,7 +203,7 @@ time, not at draw time.
 Raise or warn on registering a colormap twice
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When using `matplotlib.cm.register_cmap` to register a user provided or
+When using ``matplotlib.cm.register_cmap`` to register a user provided or
 third-party colormap it will now raise a `ValueError` if trying to over-write
 one of the built in colormaps and warn if trying to over write a user
 registered colormap. This may raise for user-registered colormaps in the
diff --git a/doc/api/prev_api_changes/api_changes_3.6.0/behaviour.rst b/doc/api/prev_api_changes/api_changes_3.6.0/behaviour.rst
@@ -4,7 +4,7 @@ Behaviour changes
 ``plt.get_cmap`` and ``matplotlib.cm.get_cmap`` return a copy
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Formerly, `~.pyplot.get_cmap` and `.cm.get_cmap` returned a global version of a
+Formerly, `~.pyplot.get_cmap` and ``matplotlib.cm.get_cmap`` returned a global version of a
 `.Colormap`. This was prone to errors as modification of the colormap would
 propagate from one location to another without warning. Now, a new copy of the
 colormap is returned.
diff --git a/doc/api/prev_api_changes/api_changes_3.7.0/behaviour.rst b/doc/api/prev_api_changes/api_changes_3.7.0/behaviour.rst
@@ -20,7 +20,7 @@ also be based on ``mpl_toolkits.axisartist``.  This behavior is consistent with
 ``plt.get_cmap`` and ``matplotlib.cm.get_cmap`` return a copy
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Formerly, `~.pyplot.get_cmap` and `.cm.get_cmap` returned a global version of a
+Formerly, `~.pyplot.get_cmap` and ``matplotlib.cm.get_cmap`` returned a global version of a
 `.Colormap`. This was prone to errors as modification of the colormap would
 propagate from one location to another without warning. Now, a new copy of the
 colormap is returned.
diff --git a/doc/users/prev_whats_new/whats_new_3.4.0.rst b/doc/users/prev_whats_new/whats_new_3.4.0.rst
@@ -547,7 +547,7 @@ for out-of-range and masked values.
 New ``cm.unregister_cmap`` function
 -----------------------------------
 
-`.cm.unregister_cmap` allows users to remove a colormap that they have
+``matplotlib.cm.unregister_cmap`` allows users to remove a colormap that they have
 previously registered.
 
 New ``CenteredNorm`` for symmetrical data around a center
diff --git a/doc/users/prev_whats_new/whats_new_3.5.0.rst b/doc/users/prev_whats_new/whats_new_3.5.0.rst
@@ -148,9 +148,9 @@ To register new colormaps use::
 
     plt.colormaps.register(my_colormap)
 
-We recommend to use the new API instead of the `~.cm.get_cmap` and
-`~.cm.register_cmap` functions for new code. `matplotlib.cm.get_cmap` and
-`matplotlib.cm.register_cmap` will eventually be deprecated and removed.
+We recommend to use the new API instead of the ``matplotlib.cm.get_cmap`` and
+``matplotlib.cm.register_cmap`` functions for new code. ``matplotlib.cm.get_cmap`` and
+``matplotlib.cm.register_cmap`` will eventually be deprecated and removed.
 Within `.pyplot`, ``plt.get_cmap()`` and ``plt.register_cmap()`` will continue
 to be supported for backward compatibility.
 
diff --git a/lib/matplotlib/cm.py b/lib/matplotlib/cm.py
@@ -78,8 +78,6 @@ class ColormapRegistry(Mapping):
     def __init__(self, cmaps):
         self._cmaps = cmaps
         self._builtin_cmaps = tuple(cmaps)
-        # A shim to allow register_cmap() to force an override
-        self._allow_override_builtin = False
 
     def __getitem__(self, item):
         try:
@@ -141,10 +139,8 @@ def register(self, cmap, *, name=None, force=False):
                 # unless explicitly asked to
                 raise ValueError(
                     f'A colormap named "{name}" is already registered.')
-            elif (name in self._builtin_cmaps
-                    and not self._allow_override_builtin):
-                # We don't allow overriding a builtin unless privately
-                # coming from register_cmap()
+            elif name in self._builtin_cmap:
+                # We don't allow overriding a builtin
                 raise ValueError("Re-registering the builtin cmap "
                                  f"{name!r} is not allowed.")
 
@@ -231,35 +227,6 @@ def get_cmap(self, cmap):
 globals().update(_colormaps)
 
 
-def _get_cmap(name=None, lut=None):
-    """
-    Get a colormap instance, defaulting to rc values if *name* is None.
-
-    Parameters
-    ----------
-    name : `~matplotlib.colors.Colormap` or str or None, default: None
-        If a `.Colormap` instance, it will be returned. Otherwise, the name of
-        a colormap known to Matplotlib, which will be resampled by *lut*. The
-        default, None, means :rc:`image.cmap`.
-    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']
-    if isinstance(name, colors.Colormap):
-        return name
-    _api.check_in_list(sorted(_colormaps), name=name)
-    if lut is None:
-        return _colormaps[name]
-    else:
-        return _colormaps[name].resampled(lut)
-
-
 def _auto_norm_from_scale(scale_cls):
     """
     Automatically generate a norm class from *scale_cls*.
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -55,7 +55,8 @@
 import matplotlib
 import matplotlib.colorbar
 import matplotlib.image
-from matplotlib import _api
+import matplotlib as mpl
+from matplotlib import _api, colors
 from matplotlib import (  # Re-exported for typing.
     cm as cm, get_backend as get_backend, rcParams as rcParams, style as style)
 from matplotlib import _pylab_helpers, interactive
@@ -2347,7 +2348,36 @@ def clim(vmin: float | None = None, vmax: float | None = None) -> None:
 
 
 # eventually this implementation should move here, use indirection for now to
-# avoid having two copies of the code floating around.
+# avoid having two copies of the code floating around. 
+def _get_cmap(name=None, lut=None):
+    """
+    Get a colormap instance, defaulting to rc values if *name* is None.
+
+    Parameters
+    ----------
+    name : `~matplotlib.colors.Colormap` or str or None, default: None
+        If a `.Colormap` instance, it will be returned. Otherwise, the name of
+        a colormap known to Matplotlib, which will be resampled by *lut*. The
+        default, None, means :rc:`image.cmap`.
+    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']
+    if isinstance(name, colors.Colormap):
+        return name
+    _api.check_in_list(sorted(_colormaps), name=name)
+    if lut is None:
+        return _colormaps[name]
+    else:
+        return _colormaps[name].resampled(lut)
+
+
 def get_cmap(
     name: Colormap | str | None = None,
     lut: int | None = None
diff --git a/lib/matplotlib/tests/test_colors.py b/lib/matplotlib/tests/test_colors.py
@@ -72,51 +72,6 @@ def test_resampled():
     assert_array_almost_equal(lc(np.nan), lc3(np.nan))
 
 
-def test_register_cmap():
-    new_cm = mpl.colormaps["viridis"]
-    target = "viridis2"
-    with pytest.warns(
-            mpl.MatplotlibDeprecationWarning,
-            match=r"matplotlib\.colormaps\.register\(name\)"
-    ):
-        cm.register_cmap(target, new_cm)
-    assert mpl.colormaps[target] == new_cm
-
-    with pytest.raises(ValueError,
-                       match="Arguments must include a name or a Colormap"):
-        with pytest.warns(
-            mpl.MatplotlibDeprecationWarning,
-            match=r"matplotlib\.colormaps\.register\(name\)"
-        ):
-            cm.register_cmap()
-
-    with pytest.warns(
-            mpl.MatplotlibDeprecationWarning,
-            match=r"matplotlib\.colormaps\.unregister\(name\)"
-    ):
-        cm.unregister_cmap(target)
-    with pytest.raises(ValueError,
-                       match=f'{target!r} is not a valid value for name;'):
-        with pytest.warns(
-                mpl.MatplotlibDeprecationWarning,
-                match=r"matplotlib\.colormaps\[name\]"
-        ):
-            cm.get_cmap(target)
-    with pytest.warns(
-            mpl.MatplotlibDeprecationWarning,
-            match=r"matplotlib\.colormaps\.unregister\(name\)"
-    ):
-        # test that second time is error free
-        cm.unregister_cmap(target)
-
-    with pytest.raises(TypeError, match="'cmap' must be"):
-        with pytest.warns(
-            mpl.MatplotlibDeprecationWarning,
-            match=r"matplotlib\.colormaps\.register\(name\)"
-        ):
-            cm.register_cmap('nome', cmap='not a cmap')
-
-
 def test_colormaps_get_cmap():
     cr = mpl.colormaps
 
@@ -137,29 +92,6 @@ def test_colormaps_get_cmap():
         cr.get_cmap(object())
 
 
-def test_double_register_builtin_cmap():
-    name = "viridis"
-    match = f"Re-registering the builtin cmap {name!r}."
-    with pytest.raises(ValueError, match=match):
-        matplotlib.colormaps.register(
-            mpl.colormaps[name], name=name, force=True
-        )
-    with pytest.raises(ValueError, match='A colormap named "viridis"'):
-        with pytest.warns(mpl.MatplotlibDeprecationWarning):
-            cm.register_cmap(name, mpl.colormaps[name])
-    with pytest.warns(UserWarning):
-        # TODO is warning more than once!
-        cm.register_cmap(name, mpl.colormaps[name], override_builtin=True)
-
-
-def test_unregister_builtin_cmap():
-    name = "viridis"
-    match = f'cannot unregister {name!r} which is a builtin colormap.'
-    with pytest.raises(ValueError, match=match):
-        with pytest.warns(mpl.MatplotlibDeprecationWarning):
-            cm.unregister_cmap(name)
-
-
 def test_colormap_copy():
     cmap = plt.cm.Reds
     copied_cmap = copy.copy(cmap)
