Deprecate implicit creation of colormaps in register_cmap()

timhoffm · timhoffm · commit eb61e47860ea · 2019-12-08T22:09:21.000+01:00
diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
@@ -52,3 +52,10 @@ Case-insensitive capstyles and joinstyles
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Please pass capstyles ("miter", "round", "bevel") and joinstyles ("butt",
 "round", "projecting") as lowercase.
+
+Passing raw data to ``register_cmap()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Passing raw data via parameters *data* and *lut* to `.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/lib/matplotlib/cm.py b/lib/matplotlib/cm.py
@@ -90,9 +90,11 @@ def register_cmap(name=None, cmap=None, data=None, lut=None):
     instance.  The *name* is optional; if absent, the name will
     be the :attr:`~matplotlib.colors.Colormap.name` attribute of the *cmap*.
 
-    In the second case, the three arguments are passed to
+    The second case is deprecated. Here, the three arguments are passed to
     the :class:`~matplotlib.colors.LinearSegmentedColormap` initializer,
-    and the resulting colormap is registered.
+    and the resulting colormap is registered. Instead of this implicit
+    colormap creation, create a `.LinearSegmentedColormap` and use the first
+    case: ``register_cmap(cmap=LinearSegmentedColormap(name, data, lut))``.
     """
     cbook._check_isinstance((str, None), name=name)
     if name is None:
@@ -103,6 +105,13 @@ def register_cmap(name=None, cmap=None, data=None, lut=None):
     if isinstance(cmap, colors.Colormap):
         cmap_d[name] = cmap
         return
+    if lut is not None or data is not None:
+        cbook.warn_deprecated(
+            "3.3",
+            message="Passing raw data via parameters data and lut to "
+                    "register_cmap() is deprecated. Instead use: "
+                    "register_cmap("
+                    "cmap=LinearSegmentedColormap(name, data, lut))")
     # For the remainder, let exceptions propagate.
     if lut is None:
         lut = mpl.rcParams['image.lut']
