8000 Update cycler docstrings and favor kwarg over two-args form · matplotlib/matplotlib@3a5a5a4 · GitHub
[go: up one dir, main page]
Skip to content

Commit 3a5a5a4

Browse files
timhoffmy1thof
timhoffm
authored and
y1thof
committed
Update cycler docstrings and favor kwarg over two-args form
1 parent 0d0eb39 commit 3a5a5a4

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
@@ -87,7 +87,8 @@ def _check_deps():
8787
'python': ('https://docs.python.org/3', None),
8888
'numpy': ('https://docs.scipy.org/doc/numpy/', None),
8989
'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
90-
'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None)
90+
'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
91+
'cycler': ('https://matplotlib.org/cycler', None),
9192
}
9293

9394
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
@@ -1158,16 +1158,22 @@ def set_prop_cycle(self, *args, **kwargs):
11581158
Call signatures::
11591159
11601160
set_prop_cycle(cycler)
1161-
set_prop_cycle(label, values)
11621161
set_prop_cycle(label=values[, label2=values2[, ...]])
1162+
set_prop_cycle(label, values)
11631163
1164-
Form 1 simply sets given `Cycler` object.
1164+
Form 1 sets given `~cycler.Cycler` object.
11651165
1166-
Form 2 creates and sets a `Cycler` from a label and an iterable.
1166+
Form 2 creates a `~cycler.Cycler` which cycles over one or more
1167+
properties simultaneously and set it as the property cycle of the
1168+
axes. If multiple properties are given, their value lists must have
1169+
the same length. This is just a shortcut for explicitly creating a
1170+
cycler and passing it to the function, i.e. it's short for
1171+
``set_prop_cycle(cycler(label=values label2=values2, ...))``.
11671172
1168-
Form 3 composes and sets a `Cycler` as an inner product of the
1169-
pairs of keyword arguments. In other words, all of the
1170-
iterables are cycled simultaneously, as if through zip().
1173+
Form 3 creates a `~cycler.Cycler` for a single property and set it
1174+
as the property cycle of the axes. This form exists for compatibility
1175+
with the original `cycler.cycler` interface. Its use is discouraged
1176+
in favor of the kwarg form, i.e. ``set_prop_cycle(label=values)``.
11711177
11721178
Parameters
11731179
----------
@@ -1188,8 +1194,7 @@ def set_prop_cycle(self, *args, **kwargs):
11881194
--------
11891195
Setting the property cycle for a single property:
11901196
1191-
>>> ax.set_prop_cycle(color=['red', 'green', 'blue']) # or
1192-
>>> ax.set_prop_cycle('color', ['red', 'green', 'blue'])
1197+
>>> ax.set_prop_cycle(color=['red', 'green', 'blue'])
11931198
11941199
Setting the property cycle for simultaneously cycling over multiple
11951200
properties (e.g. red circle, green plus, blue cross):
@@ -1200,7 +1205,9 @@ def set_prop_cycle(self, *args, **kwargs):
12001205
See Also
12011206
--------
12021207
matplotlib.rcsetup.cycler
1203-
Convenience function for creating your own cyclers.
1208+
Convenience function for creating validated cyclers for properties.
1209+
cycler.cycler
1210+
The original function for creating unvalidated cyclers.
12041211
12051212
"""
12061213
if args and kwargs:

‎lib/matplotlib/rcsetup.py

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

745745
def cycler(*args, **kwargs):
746746
"""
747-
Creates a :class:`cycler.Cycler` object much like :func:`cycler.cycler`,
747+
Creates a `~cycler.Cycler` object much like :func:`cycler.cycler`,
748748
but includes input validation.
749749
750750
Call signatures::
751751
752752
cycler(cycler)
753-
cycler(label, values)
754753
cycler(label=values[, label2=values2[, ...]])
754+
cycler(label, values)
755755
756-
Form 1 simply copies a given `Cycler` object.
756+
Form 1 copies a given `~cycler.Cycler` object.
757757
758-
Form 2 creates a `Cycler` from a label and an iterable.
758+
Form 2 creates a `~cycler.Cycler` which cycles over one or more
759+
properties simultaneously. If multiple properties are given, their
760+
value lists must have the same length.
759761
760-
Form 3 composes a `Cycler` as an inner product of the
761-
pairs of keyword arguments. In other words, all of the
762-
iterables are cycled simultaneously, as if through zip().
762+
Form 3 creates a `~cycler.Cycler` for a single property. This form
763+
exists for compatibility with the original cycler. Its use is
764+
discouraged in favor of the kwarg form, i.e. ``cycler(label=values)``.
763765
764766
Parameters
765767
----------
@@ -778,14 +780,13 @@ def cycler(*args, **kwargs):
778780
Returns
779781
-------
780782
cycler : Cycler
781-
New :class:`cycler.Cycler` for the given properties
783+
A new :class:`~cycler.Cycler` for the given properties.
782784
783785
Examples
784786
--------
785787
Creating a cycler for a single property:
786788
787-
>>> c = cycler(color=['red', 'green', 'blue']) # or
788-
>>> c = cycler('color', ['red', 'green', 'blue'])
789+
>>> c = cycler(color=['red', 'green', 'blue'])
789790
790791
Creating a cycler for simultaneously cycling over multiple properties
791792
(e.g. red circle, green plus, blue cross):

‎lib/matplotlib/stackplot.py

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff 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