revert explicit keyword arguments in Axes.stem

timhoffm · timhoffm · commit 57b716e87647 · 2018-01-04T21:30:16.000+01:00
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -2391,19 +2391,19 @@ def broken_barh(self, xranges, yrange, **kwargs):
         return col
 
     @_preprocess_data(replace_all_args=True, label_namer=None)
-    def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
-             label=None, **kwargs):
+    def stem(self, *args, **kwargs):
         """
         Create a stem plot.
 
-        Call signatures::
-
-          stem(y)
-          stem(x, y)
-
         A stem plot plots vertical lines at each *x* location from the baseline
         to *y*, and places a marker there.
 
+        Call signature::
+
+          stem([x,] y, linefmt=None, markerfmt=None, basefmt=None)
+
+        The x-positions are optional. The formats may be provided either as
+        positional or as keyword-arguments.
 
         Parameters
         ----------
@@ -2462,25 +2462,39 @@ def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
 
         Returns
         -------
-        a :class:`~matplotlib.container.StemContainer`
+        :class:`~matplotlib.container.StemContainer`
+            The stemcontainer may be treated like a tuple
+            (*markerline*, *stemlines*, *baseline*)
 
-        The stemcontainer may be treated like a tuple
-        (*markerline*, *stemlines*, *baseline*)
 
+        Notes
+        -----
 
         .. seealso::
             The MATLAB function
             `stem <http://www.mathworks.com/help/techdoc/ref/stem.html>`_
             which inspired this method.
 
         """
+
+        # kwargs handling
+        # We would like to have a signature with explicit kewords:
+        # stem(*args, linefmt=None, markerfmt=None, basefmt=None,
+        #      bottom=0, label=None)
+        # Unfortunately,  this is not supported in Python 2.x. There, *args
+        # can only exist after keyword arguments.
+        linefmt = kwargs.pop('linefmt', None)
+        markerfmt = kwargs.pop('markerfmt', None)
+        basefmt = kwargs.pop('basefmt', None)
+        bottom = kwargs.pop('bottom', None)
+        if bottom is None:
+            bottom = 0
+        label = kwargs.pop('label', None)
         if kwargs:
-            # TODO: to remove the deprecated behavior, simply remove **kwargs
-            #       from the function signature and remove this warning.
             warn_deprecated(since='2.2',
-                            message = "stem() got an unexpected keyword "
-                                      "argument '%s'. This will raise a "
-                                      "TypeError in future versions." % (
+                            message="stem() got an unexpected keyword "
+                                    "argument '%s'. This will raise a "
+                                    "TypeError in future versions." % (
                                 next(k for k in kwargs), )
                             )
 
@@ -2503,7 +2517,7 @@ def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
             second = np.arange(len(y))
             x = second
 
-        # Popping some defaults
+        # defaults for formats
         if linefmt is None:
             try:
                 # fallback to positional argument
@@ -2550,9 +2564,6 @@ def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
         else:
             basestyle, basemarker, basecolor = _process_plot_format(basefmt)
 
-        if bottom is None:
-            bottom = 0
-
         markerline, = self.plot(x, y, color=markercolor, linestyle=markerstyle,
                                 marker=markermarker, label="_nolegend_")
 
diff --git a/lib/matplotlib/container.py b/lib/matplotlib/container.py
@@ -111,9 +111,7 @@ def get_children(self):
 
 class BarContainer(Container):
     """
-    Container for the artists of bar plots.
-
-    E.g. created in a :meth:`.Axes.bar` plot.
+    Container for the artists of bar plots (e.g. created by `.Axes.bar`).
 
     The container can be treated as a tuple of the *patches* themselves.
     Additionally, you can access these and further parameters by the
@@ -138,9 +136,7 @@ def __init__(self, patches, errorbar=None, **kwargs):
 
 class ErrorbarContainer(Container):
     """
-    Container for the artists of error bars.
-
-    E.g. created in a :meth:`.Axes.errorbar` plot.
+    Container for the artists of error bars (e.g. created by `.Axes.errorbar`).
 
     The container can be treated as the *lines* tuple itself.
     Additionally, you can access these and further parameters by the
