From d35c3a709db3f6a3860ef32b5a53ee1ef4690b6f Mon Sep 17 00:00:00 2001
From: Antony Lee <anntzer.lee@gmail.com>
Date: Mon, 8 Oct 2018 13:40:44 +0200
Subject: [PATCH] Deprecate passing drawstyle with linestyle as single string.

Instead of `plt.plot(..., linestyle="steps--")`, use `plt.plot(...,
linestyle="--", drawstyle="steps")`. `ds` is now an alias for
`drawstyle`.

Note that `plt.plot(..., "steps--")` already doesn't work (due to
confusion as to whether "steps" is a color, a marker or a drawstyle).

The end goal is to simplify and rationalize linestyle specification as
rcParams vs. as arguments.
---
 doc/api/api_changes/2018-10-08-AL-deprecations.rst | 5 +++++
 lib/matplotlib/axes/_axes.py                       | 3 +--
 lib/matplotlib/lines.py                            | 8 ++++++++
 3 files changed, 14 insertions(+), 2 deletions(-)
 create mode 100644 doc/api/api_changes/2018-10-08-AL-deprecations.rst

diff --git a/doc/api/api_changes/2018-10-08-AL-deprecations.rst b/doc/api/api_changes/2018-10-08-AL-deprecations.rst
new file mode 100644
index 000000000000..b990fb7c341a
--- /dev/null
+++ b/doc/api/api_changes/2018-10-08-AL-deprecations.rst
@@ -0,0 +1,5 @@
+Passing a Line2D's drawstyle together with the linestyle is deprecated
+``````````````````````````````````````````````````````````````````````
+
+Instead of ``plt.plot(..., linestyle="steps--")``, use ``plt.plot(...,
+linestyle="--", drawstyle="steps")``. ``ds`` is now an alias for ``drawstyle``.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
index 1915d00bbedc..277ff1be193e 100644
--- a/lib/matplotlib/axes/_axes.py
+++ b/lib/matplotlib/axes/_axes.py
@@ -2047,8 +2047,7 @@ def step(self, x, y, *args, where='pre', **kwargs):
         if where not in ('pre', 'post', 'mid'):
             raise ValueError("'where' argument to step must be "
                              "'pre', 'post' or 'mid'")
-        kwargs['linestyle'] = 'steps-' + where + kwargs.get('linestyle', '')
-
+        kwargs['drawstyle'] = 'steps-' + where
         return self.plot(x, y, *args, **kwargs)
 
     @_preprocess_data(replace_names=["x", "left",
diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py
index 007e5186203f..d45b1caf7473 100644
--- a/lib/matplotlib/lines.py
+++ b/lib/matplotlib/lines.py
@@ -207,6 +207,7 @@ def _slice_or_none(in_v, slc):
 @cbook._define_aliases({
     "antialiased": ["aa"],
     "color": ["c"],
+    "drawstyle": ["ds"],
     "linestyle": ["ls"],
     "linewidth": ["lw"],
     "markeredgecolor": ["mec"],
@@ -1133,6 +1134,13 @@ def _split_drawstyle_linestyle(self, ls):
         """
         for ds in self.drawStyleKeys:  # long names are first in the list
             if ls.startswith(ds):
+                cbook.warn_deprecated(
+                    "3.1", message="Passing the drawstyle with the linestyle "
+                    "as a single string is deprecated since Matplotlib "
+                    "%(since)s and support will be removed %(removal)s; "
+                    "please pass the drawstyle separately using the drawstyle "
+                    "keyword argument to Line2D or set_drawstyle() method (or "
+                    "ds/set_ds()).")
                 return ds, ls[len(ds):] or '-'
         return None, ls