From 88cdf1b88be8b993eef723a488cdd3fe71a6bd59 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Sun, 19 Sep 2021 15:17:15 +0200
Subject: [PATCH] Make stem formatting parameters keyword only.

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.
---
 doc/api/next_api_changes/deprecations/21126-TH.rst | 2 ++
 lib/matplotlib/axes/_axes.py                       | 6 ++++++
 lib/matplotlib/tests/test_axes.py                  | 6 +++---
 3 files changed, 11 insertions(+), 3 deletions(-)
 create mode 100644 doc/api/next_api_changes/deprecations/21126-TH.rst

diff --git a/doc/api/next_api_changes/deprecations/21126-TH.rst b/doc/api/next_api_changes/deprecations/21126-TH.rst
new file mode 100644
index 000000000000..43df16287319
--- /dev/null
+++ 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
index 3856e45229fc..e8614e07ebed 100644
--- 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
index e96f9d5605d6..b1d6dae02d4f 100644
--- a/lib/matplotlib/tests/test_axes.py
+++ b/lib/matplotlib/tests/test_axes.py
@@ -3641,8 +3641,8 @@ 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():
@@ -3650,7 +3650,7 @@ def test_stem_dates():
     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],