Deprecate the verts kwarg to scatter.

anntzer · anntzer · commit 2b34931f621d · 2018-06-07T08:07:09.000+02:00
The `marker` kwarg is completely compatible and more general.
diff --git a/doc/api/next_api_changes/2018-02-15-AL-deprecations.rst b/doc/api/next_api_changes/2018-02-15-AL-deprecations.rst
@@ -40,3 +40,6 @@ The following classes, methods, functions, and attributes are deprecated:
 
 The following rcParams are deprecated:
 - ``pgf.debug`` (the pgf backend relies on logging),
+
+The following keyword arguments are deprecated:
+- passing ``verts`` to ``scatter`` (use ``marker`` instead),
diff --git a/examples/lines_bars_and_markers/scatter_custom_symbol.py b/examples/lines_bars_and_markers/scatter_custom_symbol.py
@@ -19,6 +19,6 @@
 s *= 10**2.
 
 fig, ax = plt.subplots()
-ax.scatter(x, y, s, c, marker=None, verts=verts)
+ax.scatter(x, y, s, c, marker=verts)
 
 plt.show()
diff --git a/examples/lines_bars_and_markers/scatter_star_poly.py b/examples/lines_bars_and_markers/scatter_star_poly.py
@@ -26,9 +26,7 @@
 
 verts = np.array([[-1, -1], [1, -1], [1, 1], [-1, -1]])
 plt.subplot(323)
-plt.scatter(x, y, s=80, c=z, marker=(verts, 0))
-# equivalent:
-# plt.scatter(x, y, s=80, c=z, marker=None, verts=verts)
+plt.scatter(x, y, s=80, c=z, marker=verts)
 
 plt.subplot(324)
 plt.scatter(x, y, s=80, c=z, marker=(5, 1))
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -3818,11 +3818,6 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
             is 'face'. You may want to change this as well.
             If *None*, defaults to rcParams ``lines.linewidth``.
 
-        verts : sequence of (x, y), optional
-            If *marker* is *None*, these vertices will be used to construct
-            the marker.  The center of the marker is located at (0, 0) in
-            normalized units.  The overall marker is rescaled by *s*.
-
         edgecolors : color or sequence of color, optional, default: 'face'
             The edge color of the marker. Possible values:
 
@@ -3960,9 +3955,11 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
         scales = s   # Renamed for readability below.
 
         # to be API compatible
-        if marker is None and verts is not None:
-            marker = (verts, 0)
-            verts = None
+        if verts is not None:
+            cbook.warn_deprecated("3.0", name="'verts'", obj_type="kwarg",
+                                  alternative="'marker'")
+            if marker is None:
+                marker = verts
 
         # load default marker from rcParams
         if marker is None:
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -1743,7 +1743,7 @@ def test_scatter_marker():
                 c=[(1, 0, 0), 'y', 'b', 'lime'],
                 s=[60, 50, 40, 30],
                 edgecolors=['k', 'r', 'g', 'b'],
-                verts=verts)
+                marker=verts)
 
 
 @image_comparison(baseline_images=['scatter_2D'], remove_text=True,
