Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit aa6e21c

Browse files
committed
Write data parameter docs as regular parameter not as note (v2)
Replaces matplotlib#19859. This approach uses an explicit template ``` data : indexable object, optional # data_parameter_message ``` in the docstring and does not try to guess a reasonable insertion position based on the docstring content. This is much simpler.
1 parent 9b9c42d commit aa6e21c

File tree

4 files changed

+124
-29
lines changed

4 files changed

+124
-29
lines changed

‎lib/matplotlib/__init__.py

Lines changed: 22 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1256,24 +1256,6 @@ def _label_from_arg(y, default_name):
12561256
return None
12571257

12581258

1259-
_DATA_DOC_TITLE = """
1260-
1261-
Notes
1262-
-----
1263-
"""
1264-
1265-
_DATA_DOC_APPENDIX = """
1266-
1267-
.. note::
1268-
In addition to the above described arguments, this function can take
1269-
a *data* keyword argument. If such a *data* argument is given,
1270-
{replaced}
1271-
1272-
Objects passed as **data** must support item access (``data[s]``) and
1273-
membership test (``s in data``).
1274-
"""
1275-
1276-
12771259
def _add_data_doc(docstring, replace_names):
12781260
"""
12791261
Add documentation for a *data* field to the given docstring.
@@ -1296,17 +1278,28 @@ def _add_data_doc(docstring, replace_names):
12961278
or replace_names is not None and len(replace_names) == 0):
12971279
return docstring
12981280
docstring = inspect.cleandoc(docstring)
1299-
repl = (
1300-
(" every other argument can also be string ``s``, which is\n"
1301-
" interpreted as ``data[s]`` (unless this raises an exception).")
1302-
if replace_names is None else
1303-
(" the following arguments can also be string ``s``, which is\n"
1304-
" interpreted as ``data[s]`` (unless this raises an exception):\n"
1305-
" " + ", ".join(map("*{}*".format, replace_names))) + ".")
1306-
addendum = _DATA_DOC_APPENDIX.format(replaced=repl)
1307-
if _DATA_DOC_TITLE not in docstring:
1308-
addendum = _DATA_DOC_TITLE + addendum
1309-
return docstring + addendum
1281+
1282+
data_doc = ("""\
1283+
If given, all parameters also accept a string ``s``, which is
1284+
interpreted as ``data[s]`` (unless this raises an exception).
1285+
1286+
Objects passed as **data** must support item access (``data[s]``) and
1287+
membership test (``s in data``)."""
1288+
if replace_names is None else ("""\
1289+
If given, the following parameters also accept a string ``s``, which
1290+
is interpreted as ``data[s]`` (unless this raises an exception):
1291+
1292+
{names}
1293+
1294+
Objects passed as **data** must support item access (``data[s]``) and
1295+
membership test (``s in data``).""".format(
1296+
names=", ".join(map("*{}*".format, replace_names)))
1297+
)
1298+
)
1299+
# using string replacement instead of formatting has the advantages
1300+
# 1) simpler indent handling
1301+
# 2) prevent problems with formatting characters '{', '%' in the docstring
1302+
return docstring.replace(' # data_parameter_message', data_doc)
13101303

13111304

13121305
def _preprocess_data(func=None, *, replace_names=None, label_namer=None):

‎lib/matplotlib/axes/_axes.py

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1007,6 +1007,8 @@ def hlines(self, y, xmin, xmax, colors=None, linestyles='solid',
10071007
10081008
Other Parameters
10091009
----------------
1010+
data : indexable object, optional
1011+
# data_parameter_message
10101012
**kwargs : `~matplotlib.collections.LineCollection` properties.
10111013
10121014
See Also
@@ -1084,6 +1086,8 @@ def vlines(self, x, ymin, ymax, colors=None, linestyles='solid',
10841086
10851087
Other Parameters
10861088
----------------
1089+
data : indexable object, optional
1090+
# data_parameter_message
10871091
**kwargs : `~matplotlib.collections.LineCollection` properties.
10881092
10891093
See Also
@@ -1212,6 +1216,9 @@ def eventplot(self, positions, orientation='horizontal', lineoffsets=1,
12121216
If *positions* is 2D, this can be a sequence with length matching
12131217
the length of *positions*.
12141218
1219+
data : indexable object, optional
1220+
# data_parameter_message
1221+
12151222
**kwargs
12161223
Other keyword arguments are line collection properties. See
12171224
`.LineCollection` for a list of the valid properties.
@@ -1660,6 +1667,8 @@ def plot_date(self, x, y, fmt='o', tz=None, xdate=True, ydate=False,
16601667
16611668
Other Parameters
16621669
----------------
1670+
data : indexable object, optional
1671+
# data_parameter_message
16631672
**kwargs
16641673
Keyword arguments control the `.Line2D` properties:
16651674
@@ -1730,6 +1739,9 @@ def loglog(self, *args, **kwargs):
17301739
17311740
Other Parameters
17321741
----------------
1742+
data : indexable object, optional
1743+
# data_parameter_message
1744+
17331745
**kwargs
17341746
All parameters supported by `.plot`.
17351747
"""
@@ -1783,6 +1795,9 @@ def semilogx(self, *args, **kwargs):
17831795
17841796
Other Parameters
17851797
----------------
1798+
data : indexable object, optional
1799+
# data_parameter_message
1800+
17861801
**kwargs
17871802
All parameters supported by `.plot`.
17881803
"""
@@ -1832,6 +1847,9 @@ def semilogy(self, *args, **kwargs):
18321847
18331848
Other Parameters
18341849
----------------
1850+
data : indexable object, optional
1851+
# data_parameter_message
1852+
18351853
**kwargs
18361854
All parameters supported by `.plot`.
18371855
"""
@@ -1899,6 +1917,9 @@ def acorr(self, x, **kwargs):
18991917
The marker for plotting the data points.
19001918
Only used if *usevlines* is ``False``.
19011919
1920+
data : indexable object, optional
1921+
# data_parameter_message
1922+
19021923
**kwargs
19031924
Additional parameters are passed to `.Axes.vlines` and
19041925
`.Axes.axhline` if *usevlines* is ``True``; otherwise they are
@@ -1973,6 +1994,9 @@ def xcorr(self, x, y, normed=True, detrend=mlab.detrend_none,
19731994
The marker for plotting the data points.
19741995
Only used if *usevlines* is ``False``.
19751996
1997+
data : indexable object, optional
1998+
# data_parameter_message
1999+
19762000
**kwargs
19772001
Additional parameters are passed to `.Axes.vlines` and
19782002
`.Axes.axhline` if *usevlines* is ``True``; otherwise they are
@@ -2083,6 +2107,9 @@ def step(self, x, y, *args, where='pre', data=None, **kwargs):
20832107
20842108
Other Parameters
20852109
----------------
2110+
data : indexable object, optional
2111+
# data_parameter_message
2112+
20862113
**kwargs
20872114
Additional parameters are the same as those for `.plot`.
20882115
@@ -2232,6 +2259,9 @@ def bar(self, x, height, width=0.8, bottom=None, *, align="center",
22322259
log : bool, default: False
22332260
If *True*, set the y-axis to be log scale.
22342261
2262+
data : indexable object, optional
2263+
# data_parameter_message
2264+
22352265
**kwargs : `.Rectangle` properties
22362266
22372267
%(Rectangle_kwdoc)s
@@ -2682,6 +2712,8 @@ def broken_barh(self, xranges, yrange, **kwargs):
26822712
26832713
Other Parameters
26842714
----------------
2715+
data : indexable object, optional
2716+
# data_parameter_message
26852717
**kwargs : `.BrokenBarHCollection` properties
26862718
26872719
Each *kwarg* can be either a single argument applying to all
@@ -2801,6 +2833,9 @@ def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
28012833
old behavior of using a list of `.Line2D` objects. This parameter
28022834
may be deprecated in the future.
28032835
2836+
data : indexable object, optional
2837+
# data_parameter_message
2838+
28042839
Returns
28052840
-------
28062841
`.StemContainer`
@@ -3018,6 +3053,9 @@ def pie(self, x, explode=None, labels=None, colors=None,
30183053
rotatelabels : bool, default: False
30193054
Rotate each label to the angle of the corresponding slice if true.
30203055
3056+
data : indexable object, optional
3057+
# data_parameter_message
3058+
30213059
Returns
30223060
-------
30233061
patches : list
@@ -3273,6 +3311,9 @@ def errorbar(self, x, y, yerr=None, xerr=None,
32733311
32743312
Other Parameters
32753313
----------------
3314+
data : indexable object, optional
3315+
# data_parameter_message
3316+
32763317
**kwargs
32773318
All other keyword arguments are passed on to the `~.Axes.plot` call
32783319
drawing the markers. For example, this code makes big red squares
@@ -3667,6 +3708,8 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
36673708
The style of the median.
36683709
meanprops : dict, default: None
36693710
The style of the mean.
3711+
data : indexable object, optional
3712+
# data_parameter_message
36703713
36713714
See Also
36723715
--------
@@ -4401,6 +4444,8 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
44014444
44024445
Other Parameters
44034446
----------------
4447+
data : indexable object, optional
4448+
# data_parameter_message
44044449
**kwargs : `~matplotlib.collections.Collection` properties
44054450
44064451
See Also
@@ -4687,6 +4732,9 @@ def reduce_C_function(C: array) -> float
46874732
- `numpy.sum`: integral of the point values
46884733
- `numpy.amax`: value taken from the largest point
46894734
4735+
data : indexable object, optional
4736+
# data_parameter_message
4737+
46904738
**kwargs : `~matplotlib.collections.PolyCollection` properties
46914739
All other keyword arguments are passed on to `.PolyCollection`:
46924740
@@ -5506,6 +5554,9 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
55065554
55075555
Other Parameters
55085556
----------------
5557+
data : indexable object, optional
5558+
# data_parameter_message
5559+
55095560
**kwargs : `~matplotlib.artist.Artist` properties
55105561
These parameters are passed on to the constructor of the
55115562
`.AxesImage` artist.
@@ -5802,6 +5853,9 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
58025853
Stroking the edges may be preferred if *alpha* is 1, but will
58035854
cause artifacts otherwise.
58045855
5856+
data : indexable object, optional
5857+
# data_parameter_message
5858+
58055859
**kwargs
58065860
Additionally, the following arguments are allowed. They are passed
58075861
along to the `~matplotlib.collections.PolyCollection` constructor:
@@ -6047,6 +6101,9 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
60476101
60486102
Other Parameters
60496103
----------------
6104+
data : indexable object, optional
6105+
# data_parameter_message
6106+
60506107
**kwargs
60516108
Additionally, the following arguments are allowed. They are passed
60526109
along to the `~matplotlib.collections.QuadMesh` constructor:
@@ -6262,6 +6319,9 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
62626319
62636320
Other Parameters
62646321
----------------
6322+
data : indexable object, optional
6323+
# data_parameter_message
6324+
62656325
**kwargs
62666326
Supported additional parameters depend on the type of grid.
62676327
See return types of *image* for further description.
@@ -6567,6 +6627,9 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
65676627
65686628
Other Parameters
65696629
----------------
6630+
data : indexable object, optional
6631+
# data_parameter_message
6632+
65706633
**kwargs
65716634
`~matplotlib.patches.Patch` properties
65726635
@@ -6888,6 +6951,9 @@ def stairs(self, values, edges=None, *,
68886951
68896952
Other Parameters
68906953
----------------
6954+
data : indexable object, optional
6955+
# data_parameter_message
6956+
68916957
**kwargs
68926958
`~matplotlib.patches.StepPatch` properties
68936959
@@ -7001,6 +7067,9 @@ def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
70017067
alpha : ``0 <= scalar <= 1`` or ``None``, optional
70027068
The alpha blending value.
70037069
7070+
data : indexable object, optional
7071+
# data_parameter_message
7072+
70047073
**kwargs
70057074
Additional parameters are passed along to the
70067075
`~.Axes.pcolormesh` method and `~matplotlib.collections.QuadMesh`
@@ -7088,6 +7157,9 @@ def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
70887157
70897158
Other Parameters
70907159
----------------
7160+
data : indexable object, optional
7161+
# data_parameter_message
7162+
70917163
**kwargs
70927164
Keyword arguments control the `.Line2D` properties:
70937165
@@ -7201,6 +7273,9 @@ def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None,
72017273
72027274
Other Parameters
72037275
----------------
7276+
data : indexable object, optional
7277+
# data_parameter_message
7278+
72047279
**kwargs
72057280
Keyword arguments control the `.Line2D` properties:
72067281
@@ -7291,6 +7366,9 @@ def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
72917366
72927367
Other Parameters
72937368
----------------
7369+
data : indexable object, optional
7370+
# data_parameter_message
7371+
72947372
**kwargs
72957373
Keyword arguments control the `.Line2D` properties:
72967374
@@ -7368,6 +7446,9 @@ def angle_spectrum(self, x, Fs=None, Fc=None, window=None,
73687446
73697447
Other Parameters
73707448
----------------
7449+
data : indexable object, optional
7450+
# data_parameter_message
7451+
73717452
**kwargs
73727453
Keyword arguments control the `.Line2D` properties:
73737454
@@ -7434,6 +7515,9 @@ def phase_spectrum(self, x, Fs=None, Fc=None, window=None,
74347515
74357516
Other Parameters
74367517
----------------
7518+
data : indexable object, optional
7519+
# data_parameter_message
7520+
74377521
**kwargs
74387522
Keyword arguments control the `.Line2D` properties:
74397523
@@ -7501,6 +7585,9 @@ def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
75017585
75027586
Other Parameters
75037587
----------------
7588+
data : indexable object, optional
7589+
# data_parameter_message
7590+
75047591
**kwargs
75057592
Keyword arguments control the `.Line2D` properties:
75067593
@@ -7579,6 +7666,9 @@ def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
75797666
right border of the last bin. Note that for *noverlap>0* the width
75807667
of the bins is smaller than those of the segments.
75817668
7669+
data : indexable object, optional
7670+
# data_parameter_message
7671+
75827672
**kwargs
75837673
Additional keyword arguments are passed on to `~.axes.Axes.imshow`
75847674
which makes the specgram image. The origin keyword argument
@@ -7924,6 +8014,9 @@ def violinplot(self, dataset, positions=None, vert=True, widths=0.5,
79248014
callable, it should take a `GaussianKDE` instance as its only
79258015
parameter and return a scalar. If None (default), 'scott' is used.
79268016
8017+
data : indexable object, optional
8018+
# data_parameter_message
8019+
79278020
Returns
79288021
-------
79298022
dict

‎lib/matplotlib/contour.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1726,6 +1726,9 @@ def _initialize_x_y(self, z):
17261726
Hatching is supported in the PostScript, PDF, SVG and Agg
17271727
backends only.
17281728
1729+
data : indexable object, optional
1730+
# data_parameter_message
1731+
17291732
Notes
17301733
-----
17311734
1. `.contourf` differs from the MATLAB version in that it does not draw

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /