Deprecate implicit creation of colormaps in register_cmap()

timhoffm · timhoffm · commit 7524ced6013b · 2019-12-08T12:44:03.000+01:00
diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
@@ -47,3 +47,9 @@ PDF and PS character tracking internals
 The ``used_characters`` attribute and ``track_characters`` and
 ``merge_used_characters`` methods of `.RendererPdf`, `.PdfFile`, and
 `.RendererPS` are deprecated.
+
+Passing raw data to ``register_cmap()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Passing raw data via parameters *data* and *lut* to ``register_cmap()`` is
+deprecated. Instead, create the colormap explicitly using
+``register_cmap(cmap=LinearSementedColormap(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, use the first case by calling
+    ``register_cmap(cmap=LinearSementedColormap(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=LinearSementedColormap(name, data, lut))")
     # For the remainder, let exceptions propagate.
     if lut is None:
         lut = mpl.rcParams['image.lut']
