From 213a0dbbfaf510138b6c369c3792c1e0598975a0 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Wed, 18 Apr 2018 17:58:16 -0400 Subject: [PATCH] Backport PR #10899: Update cycler docstrings and favor kwarg over two-args form --- doc/conf.py | 3 ++- examples/api/filled_step.py | 4 ++-- examples/color/color_cycler.py | 12 ++++++++---- lib/matplotlib/axes/_base.py | 25 ++++++++++++++++--------- lib/matplotlib/rcsetup.py | 21 +++++++++++---------- lib/matplotlib/stackplot.py | 4 +--- tutorials/intermediate/color_cycle.py | 10 +++++----- 7 files changed, 45 insertions(+), 34 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index d0a20da36c44..f90a8a216b12 100644 --- 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 index 320e48f2a71f..a384438fe5a2 100644 --- 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 index cec1b278c886..b1f64c794b95 100644 --- 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 index 2094883445d3..9ebee5e85b1a 100644 --- 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 index 1c1717278e86..f8d5ad5036d5 100644 --- 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 index c2c80a6f0ba5..c16ef36eea0d 100644 --- 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 index ba463ade6bf9..7a2e55ffd389 100644 --- 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 # -----------------------------------