Merge pull request #11099 from anntzer/markerstyles

dstansby · web-flow · commit c50273b599ac · 2018-04-22T18:02:34.000+01:00
Deprecate certain marker styles that have simpler synonyms.
diff --git a/doc/api/next_api_changes/2018-04-22-AL.rst b/doc/api/next_api_changes/2018-04-22-AL.rst
@@ -0,0 +1,8 @@
+Deprecation of certain marker styles
+````````````````````````````````````
+
+Using ``(n, 3)`` as marker style to specify a circle marker is deprecated.  Use
+``"o"`` instead.
+
+Using ``([(x0, y0), (x1, y1), ...], 0)`` as marker style to specify a custom
+marker path is deprecated.  Use ``[(x0, y0), (x1, y1), ...]`` instead.
diff --git a/examples/api/scatter_piecharts.py b/examples/api/scatter_piecharts.py
@@ -38,11 +38,11 @@
 s3 = np.abs(xy3).max()
 
 fig, ax = plt.subplots()
-ax.scatter(range(3), range(3), marker=(xy1, 0),
+ax.scatter(range(3), range(3), marker=xy1,
            s=s1 ** 2 * sizes, facecolor='blue')
-ax.scatter(range(3), range(3), marker=(xy2, 0),
+ax.scatter(range(3), range(3), marker=xy2,
            s=s2 ** 2 * sizes, facecolor='green')
-ax.scatter(range(3), range(3), marker=(xy3, 0),
+ax.scatter(range(3), range(3), marker=xy3,
            s=s3 ** 2 * sizes, facecolor='red')
 
 plt.show()
diff --git a/lib/matplotlib/markers.py b/lib/matplotlib/markers.py
@@ -68,15 +68,15 @@
                                      an asterisk
                                    3
                                      a circle (`numsides` and `angle` is
-                                     ignored)
+                                     ignored); deprecated.
 
                                `angle`:
                                    the angle of rotation of the symbol
 ============================== ===============================================
 
-For backward compatibility, the form (`verts`, 0) is also accepted,
-but it is equivalent to just `verts` for giving a raw set of vertices
-that define the shape.
+For backward compatibility, the form (`verts`, 0) is also accepted, but it is
+deprecated and equivalent to just `verts` for giving a raw set of vertices that
+define the shape.
 
 `None` is the default which means 'nothing', however this table is
 referred to from other docs for the valid inputs from marker inputs and in
@@ -307,9 +307,17 @@ def _set_tuple_marker(self):
                 self._filled = False
                 self._joinstyle = 'bevel'
             elif symstyle == 3:
+                cbook.warn_deprecated(
+                    "3.0", "Setting a circle marker using `(..., 3)` is "
+                    "deprecated since Matplotlib 3.0, and support for it will "
+                    "be removed in 3.2.  Directly pass 'o' instead.")
                 self._path = Path.unit_circle()
             self._transform = Affine2D().scale(0.5).rotate_deg(rotation)
         else:
+            cbook.warn_deprecated(
+                "3.0", "Passing vertices as `(verts, 0)` is deprecated since "
+                "Matplotlib 3.0, and support for it will be removed in 3.2.  "
+                "Directly pass `verts` instead.")
             verts = np.asarray(marker[0])
             path = Path(verts)
             self._set_custom_marker(path)
