Backport PR #10899: Update cycler docstrings and favor kwarg over two-args form

tacaswell · timhoffm · commit 213a0dbbfaf5 · 2018-04-19T00:29:21.000+02:00
diff --git a/doc/conf.py b/doc/conf.py
@@ -96,7 +96,8 @@ def _check_deps():
     'python': ('https://docs.python.org/3', None),
     'numpy': ('https://docs.scipy.org/doc/numpy/', None),
     'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
-    'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None)
+    'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
+    'cycler': ('https://matplotlib.org/cycler', None),
 }
 
 explicit_order_folders = [
diff --git a/examples/api/filled_step.py b/examples/api/filled_step.py
@@ -181,8 +181,8 @@ def stack_hist(ax, stacked_data, sty_cycle, bottoms=None,
 
 # set up style cycles
 color_cycle = cycler(facecolor=plt.rcParams['axes.prop_cycle'][:4])
-label_cycle = cycler('label', ['set {n}'.format(n=n) for n in range(4)])
-hatch_cycle = cycler('hatch', ['/', '*', '+', '|'])
+label_cycle = cycler(label=['set {n}'.format(n=n) for n in range(4)])
+hatch_cycle = cycler(hatch=['/', '*', '+', '|'])
 
 # Fixing random state for reproducibility
 np.random.seed(19680801)
diff --git a/examples/color/color_cycler.py b/examples/color/color_cycler.py
@@ -24,15 +24,19 @@
 
 # 1. Setting prop cycle on default rc parameter
 plt.rc('lines', linewidth=4)
-plt.rc('axes', prop_cycle=(cycler('color', ['r', 'g', 'b', 'y']) +
-                           cycler('linestyle', ['-', '--', ':', '-.'])))
+plt.rc('axes', prop_cycle=(cycler(color=['r', 'g', 'b', 'y']) +
+                           cycler(linestyle=['-', '--', ':', '-.'])))
 fig, (ax0, ax1) = plt.subplots(nrows=2)
 ax0.plot(yy)
 ax0.set_title('Set default color cycle to rgby')
 
 # 2. Define prop cycle for single set of axes
-ax1.set_prop_cycle(cycler('color', ['c', 'm', 'y', 'k']) +
-                   cycler('lw', [1, 2, 3, 4]))
+#    For the most general use-case, you can provide a cycler to
+#    `.set_prop_cycle`.
+#    Here, we use the convenient shortcut that we can alternatively pass
+#    one or more properties as keyword arguements. This creates and sets
+#    a cycler iterating simultaneously over all properties.
+ax1.set_prop_cycle(color=['c', 'm', 'y', 'k'], lw=[1, 2, 3, 4])
 ax1.plot(yy)
 ax1.set_title('Set axes color cycle to cmyk')
 
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1186,16 +1186,22 @@ def set_prop_cycle(self, *args, **kwargs):
         Call signatures::
 
           set_prop_cycle(cycler)
-          set_prop_cycle(label, values)
           set_prop_cycle(label=values[, label2=values2[, ...]])
+          set_prop_cycle(label, values)
 
-        Form 1 simply sets given `Cycler` object.
+        Form 1 sets given `~cycler.Cycler` object.
 
-        Form 2 creates and sets a `Cycler` from a label and an iterable.
+        Form 2 creates a `~cycler.Cycler` which cycles over one or more
+        properties simultaneously and set it as the property cycle of the
+        axes. If multiple properties are given, their value lists must have
+        the same length. This is just a shortcut for explicitly creating a
+        cycler and passing it to the function, i.e. it's short for
+        ``set_prop_cycle(cycler(label=values label2=values2, ...))``.
 
-        Form 3 composes and sets a `Cycler` as an inner product of the
-        pairs of keyword arguments. In other words, all of the
-        iterables are cycled simultaneously, as if through zip().
+        Form 3 creates a `~cycler.Cycler` for a single property and set it
+        as the property cycle of the axes. This form exists for compatibility
+        with the original `cycler.cycler` interface. Its use is discouraged
+        in favor of the kwarg form, i.e. ``set_prop_cycle(label=values)``.
 
         Parameters
         ----------
@@ -1216,8 +1222,7 @@ def set_prop_cycle(self, *args, **kwargs):
         --------
         Setting the property cycle for a single property:
 
-        >>> ax.set_prop_cycle(color=['red', 'green', 'blue'])  # or
-        >>> ax.set_prop_cycle('color', ['red', 'green', 'blue'])
+        >>> ax.set_prop_cycle(color=['red', 'green', 'blue'])
 
         Setting the property cycle for simultaneously cycling over multiple
         properties (e.g. red circle, green plus, blue cross):
@@ -1228,7 +1233,9 @@ def set_prop_cycle(self, *args, **kwargs):
         See Also
         --------
         matplotlib.rcsetup.cycler
-            Convenience function for creating your own cyclers.
+            Convenience function for creating validated cyclers for properties.
+        cycler.cycler
+            The original function for creating unvalidated cyclers.
 
         """
         if args and kwargs:
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -719,22 +719,24 @@ def validate_hatch(s):
 
 def cycler(*args, **kwargs):
     """
-    Creates a :class:`cycler.Cycler` object much like :func:`cycler.cycler`,
+    Creates a `~cycler.Cycler` object much like :func:`cycler.cycler`,
     but includes input validation.
 
     Call signatures::
 
       cycler(cycler)
-      cycler(label, values)
       cycler(label=values[, label2=values2[, ...]])
+      cycler(label, values)
 
-    Form 1 simply copies a given `Cycler` object.
+    Form 1 copies a given `~cycler.Cycler` object.
 
-    Form 2 creates a `Cycler` from a label and an iterable.
+    Form 2 creates a `~cycler.Cycler` which cycles over one or more
+    properties simultaneously. If multiple properties are given, their
+    value lists must have the same length.
 
-    Form 3 composes a `Cycler` as an inner product of the
-    pairs of keyword arguments. In other words, all of the
-    iterables are cycled simultaneously, as if through zip().
+    Form 3 creates a `~cycler.Cycler` for a single property. This form
+    exists for compatibility with the original cycler. Its use is
+    discouraged in favor of the kwarg form, i.e. ``cycler(label=values)``.
 
     Parameters
     ----------
@@ -753,14 +755,13 @@ def cycler(*args, **kwargs):
     Returns
     -------
     cycler : Cycler
-        New :class:`cycler.Cycler` for the given properties
+        A new :class:`~cycler.Cycler` for the given properties.
 
     Examples
     --------
     Creating a cycler for a single property:
 
-    >>> c = cycler(color=['red', 'green', 'blue'])  # or
-    >>> c = cycler('color', ['red', 'green', 'blue'])
+    >>> c = cycler(color=['red', 'green', 'blue'])
 
     Creating a cycler for simultaneously cycling over multiple properties
     (e.g. red circle, green plus, blue cross):
diff --git a/lib/matplotlib/stackplot.py b/lib/matplotlib/stackplot.py
@@ -11,8 +11,6 @@
 
 import six
 from six.moves import xrange
-
-from cycler import cycler
 import numpy as np
 
 __all__ = ['stackplot']
@@ -69,7 +67,7 @@ def stackplot(axes, x, *args, **kwargs):
 
     colors = kwargs.pop('colors', None)
     if colors is not None:
-        axes.set_prop_cycle(cycler('color', colors))
+        axes.set_prop_cycle(color=colors)
 
     baseline = kwargs.pop('baseline', 'zero')
     # Assume data passed has not been 'stacked', so stack it here.
diff --git a/tutorials/intermediate/color_cycle.py b/tutorials/intermediate/color_cycle.py
@@ -39,8 +39,8 @@
 # cycler and a linestyle cycler by adding (``+``) two ``cycler``'s together.
 # See the bottom of this tutorial for more information about combining
 # different cyclers.
-default_cycler = cycler('color', ['r', 'g', 'b', 'y']) \
-                    + cycler('linestyle', ['-', '--', ':', '-.'])
+default_cycler = (cycler(color=['r', 'g', 'b', 'y']) +
+                  cycler(linestyle=['-', '--', ':', '-.']))
 
 plt.rc('lines', linewidth=4)
 plt.rc('axes', prop_cycle=default_cycler)
@@ -52,8 +52,8 @@
 # which will only set the ``prop_cycle`` for this :mod:`matplotlib.axes.Axes`
 # instance. We'll use a second ``cycler`` that combines a color cycler and a
 # linewidth cycler.
-custom_cycler = cycler('color', ['c', 'm', 'y', 'k']) \
-    + cycler('lw', [1, 2, 3, 4])
+custom_cycler = (cycler(color=['c', 'm', 'y', 'k']) +
+                 cycler(lw=[1, 2, 3, 4]))
 
 fig, (ax0, ax1) = plt.subplots(nrows=2)
 ax0.plot(yy)
@@ -76,7 +76,7 @@
 #
 # ..code-block:: python
 #
-#    axes.prop_cycle    : cycler('color', 'bgrcmyk')
+#    axes.prop_cycle    : cycler(color='bgrcmyk')
 #
 # Cycling through multiple properties
 # -----------------------------------

Original file line number	Diff line number	Diff line change
`@@ -96,7 +96,8 @@ def _check_deps():`
`96`	`96`	`'python': ('https://docs.python.org/3', None),`
`97`	`97`	`'numpy': ('https://docs.scipy.org/doc/numpy/', None),`
`98`	`98`	`'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),`
`99`		`- 'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None)`
	`99`	`+ 'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),`
	`100`	`+ 'cycler': ('https://matplotlib.org/cycler', None),`
`100`	`101`	`}`
`101`	`102`
`102`	`103`	`explicit_order_folders = [`