Make stem formatting parameters keyword only.

timhoffm · timhoffm · commit 88cdf1b88be8 · 2021-09-23T13:11:53.000+02:00
This will allow to simplify the implementation because, currently,
`stem(*args, linefmt=None, ...)` still tries to resolve excess
positionally passed args, to *linefmt* and following parameters, which
is quite a bit of logic.

OTOH, since we have 3 formats, passing them positionally is already
difficult from a usability/readability perspective, because they can
easily be mixed up.
diff --git a/doc/api/next_api_changes/deprecations/21126-TH.rst b/doc/api/next_api_changes/deprecations/21126-TH.rst
@@ -0,0 +1,2 @@
+Passing formatting parameters positionally to ``stem()`` is deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -2849,6 +2849,12 @@ def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
             args = ()
         else:
             locs, heads, *args = args
+        if args:
+            _api.warn_deprecated(
+                "3.5",
+                message="Passing the linefmt parameter positionally is "
+                        "deprecated since Matplotlib %(since)s; the "
+                        "parameter will become keyword-only %(removal)s.")
 
         if orientation == 'vertical':
             locs, heads = self._process_unit_info([("x", locs), ("y", heads)])
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -3641,16 +3641,16 @@ def test_stem_args():
     # Test the call signatures
     ax.stem(y)
     ax.stem(x, y)
-    ax.stem(x, y, 'r--')
-    ax.stem(x, y, 'r--', basefmt='b--')
+    ax.stem(x, y, linefmt='r--')
+    ax.stem(x, y, linefmt='r--', basefmt='b--')
 
 
 def test_stem_dates():
     fig, ax = plt.subplots(1, 1)
     xs = [dateutil.parser.parse("2013-9-28 11:00:00"),
           dateutil.parser.parse("2013-9-28 12:00:00")]
     ys = [100, 200]
-    ax.stem(xs, ys, "*-")
+    ax.stem(xs, ys)
 
 
 @pytest.mark.parametrize("use_line_collection", [True, False],

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+Passing formatting parameters positionally to ``stem()`` is deprecated
	`2`	`+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~`