8000 Merge pull request #10899 from timhoffm/switch-cycler-to-kwargs · matplotlib/matplotlib@e1c9ec5 · GitHub
[go: up one dir, main page]
Skip to content

Commit e1c9ec5

Browse files
tacaswelltacaswell
authored
Merge pull request #10899 from timhoffm/switch-cycler-to-kwargs
DOC: Update cycler docstrings and favor kwarg over two-args form
2 parents f78ee3f + 3a5a5a4 commit e1c9ec5

File tree

8 files changed

+47
-40
lines changed

8 files changed

+47
-40
lines changed

‎doc/conf.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,8 @@ def _check_deps():
8888
'python': ('https://docs.python.org/3', None),
8989
'numpy': ('https://docs.scipy.org/doc/numpy/', None),
9090
'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
91-
'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None)
91+
'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
92+
'cycler': ('https://matplotlib.org/cycler', None),
9293
}
9394

9495
explicit_order_folders = [

‎examples/api/filled_step.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -180,8 +180,8 @@ def stack_hist(ax, stacked_data, sty_cycle, bottoms=None,
180180

181181
# set up style cycles
182182
color_cycle = cycler(facecolor=plt.rcParams['axes.prop_cycle'][:4])
183-
label_cycle = cycler('label', ['set {n}'.format(n=n) for n in range(4)])
184-
hatch_cycle = cycler('hatch', ['/', '*', '+', '|'])
183+
label_cycle = cycler(label=['set {n}'.format(n=n) for n in range(4)])
184+
hatch_cycle = cycler(hatch=['/', '*', '+', '|'])
185185

186186
# Fixing random state for reproducibility
187187
np.random.seed(19680801)

‎examples/color/color_cycler.py

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,15 +24,19 @@
2424

2525
# 1. Setting prop cycle on default rc parameter
2626
plt.rc('lines', linewidth=4)
27-
plt.rc('axes', prop_cycle=(cycler('color', ['r', 'g', 'b', 'y']) +
28-
cycler('linestyle', ['-', '--', ':', '-.'])))
27+
plt.rc('axes', prop_cycle=(cycler(color=['r', 'g', 'b', 'y']) +
28+
cycler(linestyle=['-', '--', ':', '-.'])))
2929
fig, (ax0, ax1) = plt.subplots(nrows=2)
3030
ax0.plot(yy)
3131
ax0.set_title('Set default color cycle to rgby')
3232

3333
# 2. Define prop cycle for single set of axes
34-
ax1.set_prop_cycle(cycler('color', ['c', 'm', 'y', 'k']) +
35-
cycler('lw', [1, 2, 3, 4]))
34+
# For the most general use-case, you can provide a cycler to
35+
# `.set_prop_cycle`.
36+
# Here, we use the convenient shortcut that we can alternatively pass
37+
# one or more properties as keyword arguements. This creates and sets
38+
# a cycler iterating simultaneously over all properties.
39+
ax1.set_prop_cycle(color=['c', 'm', 'y', 'k'], lw=[1, 2, 3, 4])
3640
ax1.plot(yy)
3741
ax1.set_title('Set axes color cycle to cmyk')
3842

‎examples/lines_bars_and_markers/markevery_prop_cycle.py

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -41,13 +41,8 @@
4141
'#17becf',
4242
'#1a55FF']
4343

44-
# Create two different cyclers to use with axes.prop_cycle
45-
markevery_cycler = cycler(markevery=cases)
46-
color_cycler = cycler('color', colors)
47-
48-
# Configure rcParams axes.prop_cycle with custom cycler
49-
custom_cycler = color_cycler + markevery_cycler
50-
mpl.rcParams['axes.prop_cycle'] = custom_cycler
44+
# Configure rcParams axes.prop_cycle to simultaneously cycle cases and colors.
45+
mpl.rcParams['axes.prop_cycle'] = cycler(markevery=cases, color=colors)
5146

5247
# Create data points and offsets
5348
x = np.linspace(0, 2 * np.pi)

‎lib/matplotlib/axes/_base.py

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1160,16 +1160,22 @@ def set_prop_cycle(self, *args, **kwargs):
11601160
Call signatures::
11611161
11621162
set_prop_cycle(cycler)
1163-
set_prop_cycle(label, values)
11641163
set_prop_cycle(label=values[, label2=values2[, ...]])
1164+
set_prop_cycle(label, values)
11651165
1166-
Form 1 simply sets given `Cycler` object.
1166+
Form 1 sets given `~cycler.Cycler` object.
11671167
1168-
Form 2 creates and sets a `Cycler` from a label and an iterable.
1168+
Form 2 creates a `~cycler.Cycler` which cycles over one or more
1169+
properties simultaneously and set it as the property cycle of the
1170+
axes. If multiple properties are given, their value lists must have
1171+
the same length. This is just a shortcut for explicitly creating a
1172+
cycler and passing it to the function, i.e. it's short for
1173+
``set_prop_cycle(cycler(label=values label2=values2, ...))``.
11691174
1170-
Form 3 composes and sets a `Cycler` as an inner product of the
1171-
pairs of keyword arguments. In other words, all of the
1172-
iterables are cycled simultaneously, as if through zip().
1175+
Form 3 creates a `~cycler.Cycler` for a single property and set it
1176+
as the property cycle of the axes. This form exists for compatibility
1177+
with the original `cycler.cycler` interface. Its use is discouraged
1178+
in favor of the kwarg form, i.e. ``set_prop_cycle(label=values)``.
11731179
11741180
Parameters
11751181
----------
@@ -1190,8 +1196,7 @@ def set_prop_cycle(self, *args, **kwargs):
11901196
--------
11911197
Setting the property cycle for a single property:
11921198
1193-
>>> ax.set_prop_cycle(color=['red', 'green', 'blue']) # or
1194-
>>> ax.set_prop_cycle('color', ['red', 'green', 'blue'])
1199+
>>> ax.set_prop_cycle(color=['red', 'green', 'blue'])
11951200
11961201
Setting the property cycle for simultaneously cycling over multiple
11971202
properties (e.g. red circle, green plus, blue cross):
@@ -1202,7 +1207,9 @@ def set_prop_cycle(self, *args, **kwargs):
12021207
See Also
12031208
--------
12041209
matplotlib.rcsetup.cycler
1205-
Convenience function for creating your own cyclers.
1210+
Convenience function for creating validated cyclers for properties.
1211+
cycler.cycler
1212+
The original function for creating unvalidated cyclers.
12061213
12071214
"""
12081215
if args and kwargs:

‎lib/matplotlib/rcsetup.py

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -735,22 +735,24 @@ def validate_hatch(s):
735735

736736
def cycler(*args, **kwargs):
737737
"""
738-
Creates a :class:`cycler.Cycler` object much like :func:`cycler.cycler`,
738+
Creates a `~cycler.Cycler` object much like :func:`cycler.cycler`,
739739
but includes input validation.
740740
741741
Call signatures::
742742
743743
cycler(cycler)
744-
cycler(label, values)
745744
cycler(label=values[, label2=values2[, ...]])
745+
cycler(label, values)
746746
747-
Form 1 simply copies a given `Cycler` object.
747+
Form 1 copies a given `~cycler.Cycler` object.
748748
749-
Form 2 creates a `Cycler` from a label and an iterable.
749+
Form 2 creates a `~cycler.Cycler` which cycles over one or more
750+
properties simultaneously. If multiple properties are given, their
751+
value lists must have the same length.
750752
751-
Form 3 composes a `Cycler` as an inner product of the
752-
pairs of keyword arguments. In other words, all of the
753-
iterables are cycled simultaneously, as if through zip().
753+
Form 3 creates a `~cycler.Cycler` for a single property. This form
754+
exists for compatibility with the original cycler. Its use is
755+
discouraged in favor of the kwarg form, i.e. ``cycler(label=values)``.
754756
755757
Parameters
756758
----------
@@ -769,14 +771,13 @@ def cycler(*args, **kwargs):
769771
Returns
770772
-------
771773
cycler : Cycler
772-
New :class:`cycler.Cycler` for the given properties
774+
A new :class:`~cycler.Cycler` for the given properties.
773775
774776
Examples
775777
--------
776778
Creating a cycler for a single property:
777779
778-
>>> c = cycler(color=['red', 'green', 'blue']) # or
779-
>>> c = cycler('color', ['red', 'green', 'blue'])
780+
>>> c = cycler(color=['red', 'green', 'blue'])
780781
781782
Creating a cycler for simultaneously cycling over multiple properties
782783
(e.g. red circle, green plus, blue cross):

‎lib/matplotlib/stackplot.py

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line number 7802 Diff line change
@@ -9,7 +9,6 @@
99
from __future__ import (absolute_import, division, print_function,
1010
unicode_literals)
1111

12-
from cycler import cycler
1312
import numpy as np
1413

1514
__all__ = ['stackplot']
@@ -66,7 +65,7 @@ def stackplot(axes, x, *args, **kwargs):
6665

6766
colors = kwargs.pop('colors', None)
6867
if colors is not None:
69-
axes.set_prop_cycle(cycler('color', colors))
68+
axes.set_prop_cycle(color=colors)
7069

7170
baseline = kwargs.pop('baseline', 'zero')
7271
# Assume data passed has not been 'stacked', so stack it here.

‎tutorials/intermediate/color_cycle.py

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,8 @@
3939
# cycler and a linestyle cycler by adding (``+``) two ``cycler``'s together.
4040
# See the bottom of this tutorial for more information about combining
4141
# different cyclers.
42-
default_cycler = cycler('color', ['r', 'g', 'b', 'y']) \
43-
+ cycler('linestyle', ['-', '--', ':', '-.'])
42+
default_cycler = (cycler(color=['r', 'g', 'b', 'y']) +
43+
cycler(linestyle=['-', '--', ':', '-.']))
4444

4545
plt.rc('lines', linewidth=4)
4646
plt.rc('axes', prop_cycle=default_cycler)
@@ -52,8 +52,8 @@
5252
# which will only set the ``prop_cycle`` for this :mod:`matplotlib.axes.Axes`
5353
# instance. We'll use a second ``cycler`` that combines a color cycler and a
5454
# linewidth cycler.
55-
custom_cycler = cycler('color', ['c', 'm', 'y', 'k']) \
56-
+ cycler('lw', [1, 2, 3, 4])
55+
custom_cycler = (cycler(color=['c', 'm', 'y', 'k']) +
56+
cycler(lw=[1, 2, 3, 4]))
5757

5858
fig, (ax0, ax1) = plt.subplots(nrows=2)
5959
ax0.plot(yy)
@@ -76,7 +76,7 @@
7676
#
7777
# ..code-block:: python
7878
#
79-
# axes.prop_cycle : cycler('color', 'bgrcmyk')
79+
# axes.prop_cycle : cycler(color='bgrcmyk')
8080
#
8181
# Cycling through multiple properties
8282
# -----------------------------------

0 commit comments

Comments
 (0)
0