Deprecate support for no-args MarkerStyle().

As noted in the module docstring, there is a confusion between using a
generic default MarkerStyle (empty) and the artist-specific one (e.g.
scatter plots use `rcParams["scatter.marker"]`).  Fortunately, direct
construction of MarkerStyles (especially of empty ones) is hardly ever
needed, so we can just make the parameter required.

Author: anntzer

doc/api/next_api_changes/deprecations/21056-AL.rst

@@ -0,0 +1,3 @@
+Calling ``MarkerStyle()`` with no arguments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+... is deprecated; use ``MarkerStyle("")`` to construct an empty marker style.

lib/matplotlib/markers.py

@@ -63,9 +63,9 @@
                                       rotated by ``angle``.
 ============================== ====== =========================================
 
-``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
-those cases ``None`` still means 'default'.
+``None`` also means 'nothing' when directly constructing a `.MarkerStyle`, but
+note that there are other contexts where ``marker=None`` instead means "the
+default marker" (e.g. :rc:`scatter.marker` for `.Axes.scatter`).
 
 Note that special symbols can be defined via the
 :doc:`STIX math font </tutorials/text/mathtext>`,
@@ -127,6 +127,7 @@
 """
 
 from collections.abc import Sized
+import inspect
 
 import numpy as np
 
@@ -216,14 +217,16 @@ class MarkerStyle:
     # TODO: Is this ever used as a non-constant?
     _point_size_reduction = 0.5
 
-    def __init__(self, marker=None, fillstyle=None):
+    _unset = object()  # For deprecation of MarkerStyle(<noargs>).
+
+    def __init__(self, marker=_unset, fillstyle=None):
         """
         Parameters
         ----------
-        marker : str, array-like, Path, MarkerStyle, or None, default: None
+        marker : str, array-like, Path, MarkerStyle, or None
             - Another instance of *MarkerStyle* copies the details of that
               ``marker``.
-            - *None* means no marker.
+            - *None* means no marker.  This is the deprecated default.
             - For other possible marker values see the module docstring
               `matplotlib.markers`.
 
@@ -232,8 +235,19 @@ def __init__(self, marker=None, fillstyle=None):
         """
         self._marker_function = None
         self._set_fillstyle(fillstyle)
+        # Remove _unset and signature rewriting after deprecation elapses.
+        if marker is self._unset:
+            marker = ""
+            _api.warn_deprecated(
+                "3.6", message="Calling MarkerStyle() with no parameters is "
+                "deprecated since %(since)s; support will be removed "
+                "%(removal)s.  Use MarkerStyle('') to construct an empty "
+                "MarkerStyle.")
         self._set_marker(marker)
 
+    __init__.__signature__ = inspect.signature(  # Only for deprecation period.
+        lambda self, marker, fillstyle=None: None)
+
     def _recache(self):
         if self._marker_function is None:
             return

lib/matplotlib/tests/test_marker.py

@@ -1,6 +1,7 @@
 import numpy as np
 import matplotlib.pyplot as plt
 from matplotlib import markers
+from matplotlib._api.deprecation import MatplotlibDeprecationWarning
 from matplotlib.path import Path
 from matplotlib.testing.decorators import check_figures_equal
 
@@ -32,14 +33,19 @@ def test_marker_fillstyle():
     (5, 0, 10),  # a pentagon, rotated by 10 degrees
     (7, 1, 10),  # a 7-pointed star, rotated by 10 degrees
     (5, 2, 10),  # asterisk, rotated by 10 degrees
-    markers.MarkerStyle(),
     markers.MarkerStyle('o'),
 ])
 def test_markers_valid(marker):
     # Checking this doesn't fail.
     markers.MarkerStyle(marker)
 
 
+def test_deprecated_marker_noargs():
+    with pytest.warns(MatplotlibDeprecationWarning):
+        ms = markers.MarkerStyle()
+    markers.MarkerStyle(ms)  # No warning on copy.
+
+
 @pytest.mark.parametrize('marker', [
     'square',  # arbitrary string
     np.array([[-0.5, 0, 1, 2, 3]]),  # 1D array