🌐 AI搜索 & 代理 主页
Skip to content

Commit 3edfce3

Browse files
timhoffmtimhoffm
committed
Deprecate positional use of most arguments of plotting functions
This increases maintainability for developers and disallows bad practice of passing lots of positional arguments for users. If in doubt, I've erred on the side of allowing as much positional arguments as possible as long as the intent of a call is still readable. Note: This was originally motivated by bxp() and boxplot() having many overlapping parameters but differently ordered. While at it, I think it's better to rollout the change to all plotting functions and communicate that in one go rather than having lots of individual change notices over time. Also, the freedom to reorder parameters only sets in after the deprecation. So let's start this now.
1 parent 1defb57 commit 3edfce3

File tree

3 files changed

+53
-20
lines changed

3 files changed

+53
-20
lines changed

‎doc/api/next_api_changes/deprecations/27786-TH.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Positional parameters in plotting functions
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3+
4+
Many plotting functions will restrict positional arguments to the first few parameters
5+
in the future. All further configuration parameters will have to be passed as keyword
6+
arguments. This is to enforce better code and and allow for future changes with reduced
7+
risk of breaking existing code.

‎lib/matplotlib/axes/_axes.py‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1059,6 +1059,7 @@ def axvspan(self, xmin, xmax, ymin=0, ymax=1, **kwargs):
10591059

10601060
@_preprocess_data(replace_names=["y", "xmin", "xmax", "colors"],
10611061
label_namer="y")
1062+
@_api.make_keyword_only("3.9", "label")
10621063
def hlines(self, y, xmin, xmax, colors=None, linestyles='solid',
10631064
label='', **kwargs):
10641065
"""
@@ -1150,6 +1151,7 @@ def hlines(self, y, xmin, xmax, colors=None, linestyles='solid',
11501151

11511152
@_preprocess_data(replace_names=["x", "ymin", "ymax", "colors"],
11521153
label_namer="x")
1154+
@_api.make_keyword_only("3.9", "label")
11531155
def vlines(self, x, ymin, ymax, colors=None, linestyles='solid',
11541156
label='', **kwargs):
11551157
"""
@@ -1243,6 +1245,7 @@ def vlines(self, x, ymin, ymax, colors=None, linestyles='solid',
12431245
"linelengths", "linewidths",
12441246
"colors", "linestyles"])
12451247
@_docstring.dedent_interpd
1248+
@_api.make_keyword_only("3.9", "orientation")
12461249
def eventplot(self, positions, orientation='horizontal', lineoffsets=1,
12471250
linelengths=1, linewidths=None, colors=None, alpha=None,
12481251
linestyles='solid', **kwargs):
@@ -1744,6 +1747,7 @@ def plot(self, *args, scalex=True, scaley=True, data=None, **kwargs):
17441747

17451748
@_preprocess_data(replace_names=["x", "y"], label_namer="y")
17461749
@_docstring.dedent_interpd
1750+
@_api.make_keyword_only("3.9", "tz")
17471751
def plot_date(self, x, y, fmt='o', tz=None, xdate=True, ydate=False,
17481752
**kwargs):
17491753
"""
@@ -2046,6 +2050,7 @@ def acorr(self, x, **kwargs):
20462050
return self.xcorr(x, x, **kwargs)
20472051

20482052
@_preprocess_data(replace_names=["x", "y"], label_namer="y")
2053+
@_api.make_keyword_only("3.9", "normed")
20492054
def xcorr(self, x, y, normed=True, detrend=mlab.detrend_none,
20502055
usevlines=True, maxlags=10, **kwargs):
20512056
r"""
@@ -3113,6 +3118,7 @@ def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
31133118
return stem_container
31143119

31153120
@_preprocess_data(replace_names=["x", "explode", "labels", "colors"])
3121+
@_api.make_keyword_only("3.9", "explode")
31163122
def pie(self, x, explode=None, labels=None, colors=None,
31173123
autopct=None, pctdistance=0.6, shadow=False, labeldistance=1.1,
31183124
startangle=0, radius=1, counterclock=True,
@@ -3391,6 +3397,7 @@ def _errorevery_to_mask(x, errorevery):
33913397
@_preprocess_data(replace_names=["x", "y", "xerr", "yerr"],
33923398
label_namer="y")
33933399
@_docstring.dedent_interpd
3400+
@_api.make_keyword_only("3.9", "ecolor")
33943401
def errorbar(self, x, y, yerr=None, xerr=None,
33953402
fmt='', ecolor=None, elinewidth=None, capsize=None,
33963403
barsabove=False, lolims=False, uplims=False,
@@ -3765,6 +3772,7 @@ def apply_mask(arrays, mask):
37653772
return errorbar_container # (l0, caplines, barcols)
37663773

37673774
@_preprocess_data()
3775+
@_api.make_keyword_only("3.9", "notch")
37683776
def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
37693777
positions=None, widths=None, patch_artist=None,
37703778
bootstrap=None, usermedians=None, conf_intervals=None,
@@ -4078,6 +4086,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
40784086
capwidths=capwidths)
40794087
return artists
40804088

4089+
@_api.make_keyword_only("3.9", "widths")
40814090
def bxp(self, bxpstats, positions=None, widths=None, vert=True,
40824091
patch_artist=False, shownotches=False, showmeans=False,
40834092
showcaps=True, showbox=True, showfliers=True,
@@ -4535,6 +4544,7 @@ def invalid_shape_exception(csize, xsize):
45354544
"edgecolors", "c", "facecolor",
45364545
"facecolors", "color"],
45374546
label_namer="y")
4547+
@_api.make_keyword_only("3.9", "marker")
45384548
@_docstring.interpd
45394549
def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
45404550
vmin=None, vmax=None, alpha=None, linewidths=None, *,
@@ -4813,6 +4823,7 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
48134823

48144824
@_preprocess_data(replace_names=["x", "y", "C"], label_namer="y")
48154825
@_docstring.dedent_interpd
4826+
@_api.make_keyword_only("3.9", "gridsize")
48164827
def hexbin(self, x, y, C=None, gridsize=100, bins=None,
48174828
xscale='linear', yscale='linear', extent=None,
48184829
cmap=None, norm=None, vmin=None, vmax=None,
@@ -6591,6 +6602,7 @@ def clabel(self, CS, levels=None, **kwargs):
65916602
#### Data analysis
65926603

65936604
@_preprocess_data(replace_names=["x", 'weights'], label_namer="x")
6605+
@_api.make_keyword_only("3.9", "range")
65946606
def hist(self, x, bins=None, range=None, density=False, weights=None,
65956607
cumulative=False, bottom=None, histtype='bar', align='mid',
65966608
orientation='vertical', rwidth=None, log=False,
@@ -7136,6 +7148,7 @@ def stairs(self, values, edges=None, *,
71367148

71377149
@_preprocess_data(replace_names=["x", "y", "weights"])
71387150
@_docstring.dedent_interpd
7151+
@_api.make_keyword_only("3.9", "range")
71397152
def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
71407153
cmin=None, cmax=None, **kwargs):
71417154
"""
@@ -7345,6 +7358,7 @@ def ecdf(self, x, weights=None, *, complementary=False,
73457358

73467359
@_preprocess_data(replace_names=["x"])
73477360
@_docstring.dedent_interpd
7361+
@_api.make_keyword_only("3.9", "NFFT")
73487362
def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
73497363
window=None, noverlap=None, pad_to=None,
73507364
sides=None, scale_by_freq=None, return_line=None, **kwargs):
@@ -7456,6 +7470,7 @@ def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
74567470

74577471
@_preprocess_data(replace_names=["x", "y"], label_namer="y")
74587472
@_docstring.dedent_interpd
7473+
@_api.make_keyword_only("3.9", "NFFT")
74597474
def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None,
74607475
window=None, noverlap=None, pad_to=None,
74617476
sides=None, scale_by_freq=None, return_line=None, **kwargs):
@@ -7558,6 +7573,7 @@ def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None,
75587573

75597574
@_preprocess_data(replace_names=["x"])
75607575
@_docstring.dedent_interpd
7576+
@_api.make_keyword_only("3.9", "Fs")
75617577
def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
75627578
pad_to=None, sides=None, scale=None,
75637579
**kwargs):
@@ -7644,6 +7660,7 @@ def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
76447660

76457661
@_preprocess_data(replace_names=["x"])
76467662
@_docstring.dedent_interpd
7663+
@_api.make_keyword_only("3.9", "Fs")
76477664
def angle_spectrum(self, x, Fs=None, Fc=None, window=None,
76487665
pad_to=None, sides=None, **kwargs):
76497666
"""
@@ -7713,6 +7730,7 @@ def angle_spectrum(self, x, Fs=None, Fc=None, window=None,
77137730

77147731
@_preprocess_data(replace_names=["x"])
77157732
@_docstring.dedent_interpd
7733+
@_api.make_keyword_only("3.9", "Fs")
77167734
def phase_spectrum(self, x, Fs=None, Fc=None, window=None,
77177735
pad_to=None, sides=None, **kwargs):
77187736
"""
@@ -7782,6 +7800,7 @@ def phase_spectrum(self, x, Fs=None, Fc=None, window=None,
77827800

77837801
@_preprocess_data(replace_names=["x", "y"])
77847802
@_docstring.dedent_interpd
7803+
@_api.make_keyword_only("3.9", "NFFT")
77857804
def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
77867805
window=mlab.window_hanning, noverlap=0, pad_to=None,
77877806
sides='default', scale_by_freq=None, **kwargs):
@@ -7846,6 +7865,7 @@ def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
78467865

78477866
@_preprocess_data(replace_names=["x"])
78487867
@_docstring.dedent_interpd
7868+
@_api.make_keyword_only("3.9", "NFFT")
78497869
def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
78507870
window=None, noverlap=None,
78517871
cmap=None, xextent=None, pad_to=None, sides=None,
@@ -8001,6 +8021,7 @@ def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
80018021
return spec, freqs, t, im
80028022

80038023
@_docstring.dedent_interpd
8024+
@_api.make_keyword_only("3.9", "precision")
80048025
def spy(self, Z, precision=0, marker=None, markersize=None,
80058026
aspect='equal', origin="upper", **kwargs):
80068027
"""
@@ -8191,6 +8212,7 @@ def matshow(self, Z, **kwargs):
81918212
return im
81928213

81938214
@_preprocess_data(replace_names=["dataset"])
8215+
@_api.make_keyword_only("3.9", "vert")
81948216
def violinplot(self, dataset, positions=None, vert=True, widths=0.5,
81958217
showmeans=False, showextrema=True, showmedians=False,
81968218
quantiles=None, points=100, bw_method=None):
@@ -8295,6 +8317,7 @@ def _kde_method(X, coords):
82958317
widths=widths, showmeans=showmeans,
82968318
showextrema=showextrema, showmedians=showmedians)
82978319

8320+
@_api.make_keyword_only("3.9", "vert")
82988321
def violin(self, vpstats, positions=None, vert=True, widths=0.5,
82998322
showmeans=False, showextrema=True, showmedians=False):
83008323
"""

0 commit comments

Comments
 (0)