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.

Author: timhoffm

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

@@ -0,0 +1,7 @@
+Positional parameters in plotting functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Many plotting functions will restrict positional arguments to the first few parameters
+in the future. All further configuration parameters will have to be passed as keyword
+arguments. This is to enforce better code and and allow for future changes with reduced
+risk of breaking existing code.

galleries/examples/lines_bars_and_markers/cohere.py

@@ -27,7 +27,7 @@
 axs[0].set_ylabel('s1 and s2')
 axs[0].grid(True)
 
-cxy, f = axs[1].cohere(s1, s2, 256, 1. / dt)
+cxy, f = axs[1].cohere(s1, s2, NFFT=256, Fs=1. / dt)
 axs[1].set_ylabel('Coherence')
 
 plt.show()

galleries/examples/lines_bars_and_markers/csd_demo.py

@@ -34,7 +34,7 @@
 ax1.set_ylabel('s1 and s2')
 ax1.grid(True)
 
-cxy, f = ax2.csd(s1, s2, 256, 1. / dt)
+cxy, f = ax2.csd(s1, s2, NFFT=256, Fs=1. / dt)
 ax2.set_ylabel('CSD (dB)')
 
 plt.show()

galleries/examples/lines_bars_and_markers/psd_demo.py

@@ -30,7 +30,7 @@
 ax0.plot(t, s)
 ax0.set_xlabel('Time (s)')
 ax0.set_ylabel('Signal')
-ax1.psd(s, 512, 1 / dt)
+ax1.psd(s, NFFT=512, Fs=1 / dt)
 
 plt.show()
 

galleries/examples/statistics/boxplot_demo.py

@@ -34,23 +34,23 @@
 axs[0, 0].set_title('basic plot')
 
 # notched plot
-axs[0, 1].boxplot(data, 1)
+axs[0, 1].boxplot(data, notch=True)
 axs[0, 1].set_title('notched plot')
 
 # change outlier point symbols
-axs[0, 2].boxplot(data, 0, 'gD')
+axs[0, 2].boxplot(data, sym='gD')
 axs[0, 2].set_title('change outlier\npoint symbols')
 
 # don't show outlier points
-axs[1, 0].boxplot(data, 0, '')
+axs[1, 0].boxplot(data, sym='')
 axs[1, 0].set_title("don't show\noutlier points")
 
 # horizontal boxes
-axs[1, 1].boxplot(data, 0, 'rs', 0)
+axs[1, 1].boxplot(data, sym='rs', vert=False)
 axs[1, 1].set_title('horizontal boxes')
 
 # change whisker length
-axs[1, 2].boxplot(data, 0, 'rs', 0, 0.75)
+axs[1, 2].boxplot(data, sym='rs', vert=False, whis=0.75)
 axs[1, 2].set_title('change whisker length')
 
 fig.subplots_adjust(left=0.08, right=0.98, bottom=0.05, top=0.9,

lib/matplotlib/axes/_axes.py

@@ -1100,6 +1100,7 @@ def axvspan(self, xmin, xmax, ymin=0, ymax=1, **kwargs):
         self._request_autoscale_view("x")
         return p
 
+    @_api.make_keyword_only("3.9", "label")
     @_preprocess_data(replace_names=["y", "xmin", "xmax", "colors"],
                       label_namer="y")
     def hlines(self, y, xmin, xmax, colors=None, linestyles='solid',
@@ -1191,6 +1192,7 @@ def hlines(self, y, xmin, xmax, colors=None, linestyles='solid',
             self._request_autoscale_view()
         return lines
 
+    @_api.make_keyword_only("3.9", "label")
     @_preprocess_data(replace_names=["x", "ymin", "ymax", "colors"],
                       label_namer="x")
     def vlines(self, x, ymin, ymax, colors=None, linestyles='solid',
@@ -1282,6 +1284,7 @@ def vlines(self, x, ymin, ymax, colors=None, linestyles='solid',
             self._request_autoscale_view()
         return lines
 
+    @_api.make_keyword_only("3.9", "orientation")
     @_preprocess_data(replace_names=["positions", "lineoffsets",
                                      "linelengths", "linewidths",
                                      "colors", "linestyles"])
@@ -2088,6 +2091,7 @@ def acorr(self, x, **kwargs):
         """
         return self.xcorr(x, x, **kwargs)
 
+    @_api.make_keyword_only("3.9", "normed")
     @_preprocess_data(replace_names=["x", "y"], label_namer="y")
     def xcorr(self, x, y, normed=True, detrend=mlab.detrend_none,
               usevlines=True, maxlags=10, **kwargs):
@@ -3155,6 +3159,7 @@ def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
         self.add_container(stem_container)
         return stem_container
 
+    @_api.make_keyword_only("3.9", "explode")
     @_preprocess_data(replace_names=["x", "explode", "labels", "colors"])
     def pie(self, x, explode=None, labels=None, colors=None,
             autopct=None, pctdistance=0.6, shadow=False, labeldistance=1.1,
@@ -3434,6 +3439,7 @@ def _errorevery_to_mask(x, errorevery):
         everymask[errorevery] = True
         return everymask
 
+    @_api.make_keyword_only("3.9", "ecolor")
     @_preprocess_data(replace_names=["x", "y", "xerr", "yerr"],
                       label_namer="y")
     @_docstring.dedent_interpd
@@ -3810,6 +3816,7 @@ def apply_mask(arrays, mask):
 
         return errorbar_container  # (l0, caplines, barcols)
 
+    @_api.make_keyword_only("3.9", "notch")
     @_preprocess_data()
     @_api.rename_parameter("3.9", "labels", "tick_labels")
     def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
@@ -4144,6 +4151,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
                            capwidths=capwidths, label=label)
         return artists
 
+    @_api.make_keyword_only("3.9", "widths")
     def bxp(self, bxpstats, positions=None, widths=None, vert=True,
             patch_artist=False, shownotches=False, showmeans=False,
             showcaps=True, showbox=True, showfliers=True,
@@ -4636,6 +4644,7 @@ def invalid_shape_exception(csize, xsize):
             colors = None  # use cmap, norm after collection is created
         return c, colors, edgecolors
 
+    @_api.make_keyword_only("3.9", "marker")
     @_preprocess_data(replace_names=["x", "y", "s", "linewidths",
                                      "edgecolors", "c", "facecolor",
                                      "facecolors", "color"],
@@ -4916,6 +4925,7 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
 
         return collection
 
+    @_api.make_keyword_only("3.9", "gridsize")
     @_preprocess_data(replace_names=["x", "y", "C"], label_namer="y")
     @_docstring.dedent_interpd
     def hexbin(self, x, y, C=None, gridsize=100, bins=None,
@@ -6698,6 +6708,7 @@ def clabel(self, CS, levels=None, **kwargs):
 
     #### Data analysis
 
+    @_api.make_keyword_only("3.9", "range")
     @_preprocess_data(replace_names=["x", 'weights'], label_namer="x")
     def hist(self, x, bins=None, range=None, density=False, weights=None,
              cumulative=False, bottom=None, histtype='bar', align='mid',
@@ -7245,6 +7256,7 @@ def stairs(self, values, edges=None, *,
         self._request_autoscale_view()
         return patch
 
+    @_api.make_keyword_only("3.9", "range")
     @_preprocess_data(replace_names=["x", "y", "weights"])
     @_docstring.dedent_interpd
     def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
@@ -7454,6 +7466,7 @@ def ecdf(self, x, weights=None, *, complementary=False,
             line.sticky_edges.x[:] = [0, 1]
         return line
 
+    @_api.make_keyword_only("3.9", "NFFT")
     @_preprocess_data(replace_names=["x"])
     @_docstring.dedent_interpd
     def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
@@ -7565,6 +7578,7 @@ def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
         else:
             return pxx, freqs, line
 
+    @_api.make_keyword_only("3.9", "NFFT")
     @_preprocess_data(replace_names=["x", "y"], label_namer="y")
     @_docstring.dedent_interpd
     def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None,
@@ -7667,6 +7681,7 @@ def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None,
         else:
             return pxy, freqs, line
 
+    @_api.make_keyword_only("3.9", "Fs")
     @_preprocess_data(replace_names=["x"])
     @_docstring.dedent_interpd
     def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
@@ -7753,6 +7768,7 @@ def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
 
         return spec, freqs, line
 
+    @_api.make_keyword_only("3.9", "Fs")
     @_preprocess_data(replace_names=["x"])
     @_docstring.dedent_interpd
     def angle_spectrum(self, x, Fs=None, Fc=None, window=None,
@@ -7822,6 +7838,7 @@ def angle_spectrum(self, x, Fs=None, Fc=None, window=None,
 
         return spec, freqs, lines[0]
 
+    @_api.make_keyword_only("3.9", "Fs")
     @_preprocess_data(replace_names=["x"])
     @_docstring.dedent_interpd
     def phase_spectrum(self, x, Fs=None, Fc=None, window=None,
@@ -7891,6 +7908,7 @@ def phase_spectrum(self, x, Fs=None, Fc=None, window=None,
 
         return spec, freqs, lines[0]
 
+    @_api.make_keyword_only("3.9", "NFFT")
     @_preprocess_data(replace_names=["x", "y"])
     @_docstring.dedent_interpd
     def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
@@ -7955,6 +7973,7 @@ def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
 
         return cxy, freqs
 
+    @_api.make_keyword_only("3.9", "NFFT")
     @_preprocess_data(replace_names=["x"])
     @_docstring.dedent_interpd
     def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
@@ -8111,6 +8130,7 @@ def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
 
         return spec, freqs, t, im
 
+    @_api.make_keyword_only("3.9", "precision")
     @_docstring.dedent_interpd
     def spy(self, Z, precision=0, marker=None, markersize=None,
             aspect='equal', origin="upper", **kwargs):
@@ -8301,6 +8321,7 @@ def matshow(self, Z, **kwargs):
             mticker.MaxNLocator(nbins=9, steps=[1, 2, 5, 10], integer=True))
         return im
 
+    @_api.make_keyword_only("3.9", "vert")
     @_preprocess_data(replace_names=["dataset"])
     def violinplot(self, dataset, positions=None, vert=True, widths=0.5,
                    showmeans=False, showextrema=True, showmedians=False,
@@ -8412,6 +8433,7 @@ def _kde_method(X, coords):
                            widths=widths, showmeans=showmeans,
                            showextrema=showextrema, showmedians=showmedians, side=side)
 
+    @_api.make_keyword_only("3.9", "vert")
     def violin(self, vpstats, positions=None, vert=True, widths=0.5,
                showmeans=False, showextrema=True, showmedians=False, side='both'):
         """