Deprecate positional passing of most Artist constructor parameters

This should have very little impact on the practical use, as it's anyway
error-prone to pass more than a few arguments by position. But enforcing
keyword-only makes future API changes simpler for us.

Author: timhoffm

doc/api/next_api_changes/deprecations/23166-ES.rst

@@ -1,5 +1,6 @@
-``Legend`` constructor
-~~~~~~~~~~~~~~~~~~~~~~
+Positional arguments in Artist constructors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-All arguments to `.legend.Legend` other than *parent*, *handles*, and *labels*
-will become keyword-only in a future version.
+Passing all but the very few first arguments positionally in the constructors
+of Artists is deprecated. Most arguments will become keyword-only in a future
+version.

lib/matplotlib/axes/_axes.py

@@ -5490,8 +5490,9 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
         if aspect is None:
             aspect = rcParams['image.aspect']
         self.set_aspect(aspect)
-        im = mimage.AxesImage(self, cmap, norm, interpolation,
-                              origin, extent, filternorm=filternorm,
+        im = mimage.AxesImage(self, cmap=cmap, norm=norm,
+                              interpolation=interpolation, origin=origin,
+                              extent=extent, filternorm=filternorm,
                               filterrad=filterrad, resample=resample,
                               interpolation_stage=interpolation_stage,
                               **kwargs)
@@ -6275,7 +6276,7 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
             extent = xl, xr, yb, yt = x[0], x[-1], y[0], y[-1]
             if style == "image":
                 im = mimage.AxesImage(
-                    self, cmap, norm,
+                    self, cmap=cmap, norm=norm,
                     data=C, alpha=alpha, extent=extent,
                     interpolation='nearest', origin='lower',
                     **kwargs)

lib/matplotlib/axis.py

@@ -643,6 +643,7 @@ def __str__(self):
         return "{}({},{})".format(
             type(self).__name__, *self.axes.transAxes.transform((0, 0)))
 
+    @_api.make_keyword_only("3.6", name="pickradius")
     def __init__(self, axes, pickradius=15):
         """
         Parameters

lib/matplotlib/collections.py

@@ -75,6 +75,7 @@ class Collection(artist.Artist, cm.ScalarMappable):
     _edge_default = False
 
     @_docstring.interpd
+    @_api.make_keyword_only("3.6", name="edgecolors")
     def __init__(self,
                  edgecolors=None,
                  facecolors=None,
@@ -1151,6 +1152,8 @@ def legend_elements(self, prop="colors", num="auto",
 
 
 class PolyCollection(_CollectionWithSizes):
+
+    @_api.make_keyword_only("3.6", name="closed")
     def __init__(self, verts, sizes=None, closed=True, **kwargs):
         """
         Parameters
@@ -1287,6 +1290,7 @@ class RegularPolyCollection(_CollectionWithSizes):
     _path_generator = mpath.Path.unit_regular_polygon
     _factor = np.pi ** (-1/2)
 
+    @_api.make_keyword_only("3.6", name="rotation")
     def __init__(self,
                  numsides,
                  rotation=0,
@@ -1503,6 +1507,7 @@ class EventCollection(LineCollection):
 
     _edge_default = True
 
+    @_api.make_keyword_only("3.6", name="lineoffset")
     def __init__(self,
                  positions,  # Cannot be None.
                  orientation='horizontal',
@@ -1698,6 +1703,7 @@ def __init__(self, sizes, **kwargs):
 class EllipseCollection(Collection):
     """A collection of ellipses, drawn using splines."""
 
+    @_api.make_keyword_only("3.6", name="units")
     def __init__(self, widths, heights, angles, units='points', **kwargs):
         """
         Parameters
@@ -1787,6 +1793,7 @@ class PatchCollection(Collection):
     draw faster than a large number of patches.
     """
 
+    @_api.make_keyword_only("3.6", name="match_original")
     def __init__(self, patches, match_original=False, **kwargs):
         """
         *patches*

lib/matplotlib/figure.py

@@ -2726,7 +2726,9 @@ def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
             figsize = [x / dpi for x in (X.shape[1], X.shape[0])]
             self.set_size_inches(figsize, forward=True)
 
-        im = mimage.FigureImage(self, cmap, norm, xo, yo, origin, **kwargs)
+        im = mimage.FigureImage(self, cmap=cmap, norm=norm,
+                                offsetx=xo, offsety=yo,
+                                origin=origin, **kwargs)
         im.stale_callback = _stale_figure_callback
 
         im.set_array(X)

lib/matplotlib/image.py

@@ -902,6 +902,7 @@ class AxesImage(_ImageBase):
     **kwargs : `.Artist` properties
     """
 
+    @_api.make_keyword_only("3.6", name="cmap")
     def __init__(self, ax,
                  cmap=None,
                  norm=None,
@@ -1185,6 +1186,8 @@ class PcolorImage(AxesImage):
     This uses a variation of the original irregular image code,
     and it is used by pcolorfast for the corresponding grid type.
     """
+
+    @_api.make_keyword_only("3.6", name="cmap")
     def __init__(self, ax,
                  x=None,
                  y=None,
@@ -1336,6 +1339,7 @@ class FigureImage(_ImageBase):
 
     _interpolation = 'nearest'
 
+    @_api.make_keyword_only("3.6", name="cmap")
     def __init__(self, fig,
                  cmap=None,
                  norm=None,
@@ -1394,6 +1398,7 @@ def set_data(self, A):
 class BboxImage(_ImageBase):
     """The Image class whose size is determined by the given bbox."""
 
+    @_api.make_keyword_only("3.6", name="cmap")
     def __init__(self, bbox,
                  cmap=None,
                  norm=None,

lib/matplotlib/lines.py

@@ -264,6 +264,7 @@ def __str__(self):
             return "Line2D(%s)" % ",".join(
                 map("({:g},{:g})".format, self._x, self._y))
 
+    @_api.make_keyword_only("3.6", name="linewidth")
     def __init__(self, xdata, ydata,
                  linewidth=None,  # all Nones default to rc
                  linestyle=None,

lib/matplotlib/offsetbox.py

@@ -498,6 +498,8 @@ class PaddedBox(OffsetBox):
     The `.PaddedBox` contains a `.FancyBboxPatch` that is used to visualize
     it when rendering.
     """
+
+    @_api.make_keyword_only("3.6", name="draw_frame")
     def __init__(self, child, pad=None, draw_frame=False, patch_attrs=None):
         """
         Parameters
@@ -688,6 +690,7 @@ class TextArea(OffsetBox):
     child text.
     """
 
+    @_api.make_keyword_only("3.6", name="textprops")
     def __init__(self, s,
                  textprops=None,
                  multilinebaseline=False,
@@ -919,6 +922,7 @@ class AnchoredOffsetbox(OffsetBox):
              'center': 10,
              }
 
+    @_api.make_keyword_only("3.6", name="pad")
     def __init__(self, loc,
                  pad=0.4, borderpad=0.5,
                  child=None, prop=None, frameon=True,
@@ -1118,6 +1122,7 @@ class AnchoredText(AnchoredOffsetbox):
     AnchoredOffsetbox with Text.
     """
 
+    @_api.make_keyword_only("3.6", name="pad")
     def __init__(self, s, loc, pad=0.4, borderpad=0.5, prop=None, **kwargs):
         """
         Parameters
@@ -1157,6 +1162,8 @@ def __init__(self, s, loc, pad=0.4, borderpad=0.5, prop=None, **kwargs):
 
 
 class OffsetImage(OffsetBox):
+
+    @_api.make_keyword_only("3.6", name="zoom")
     def __init__(self, arr,
                  zoom=1,
                  cmap=None,
@@ -1252,6 +1259,7 @@ def __str__(self):
         return "AnnotationBbox(%g,%g)" % (self.xy[0], self.xy[1])
 
     @_docstring.dedent_interpd
+    @_api.make_keyword_only("3.6", name="xycoords")
     def __init__(self, offsetbox, xy,
                  xybox=None,
                  xycoords='data',

lib/matplotlib/patches.py

@@ -44,6 +44,7 @@ class Patch(artist.Artist):
     # subclass-by-subclass basis.
     _edge_default = False
 
+    @_api.make_keyword_only("3.6", name="edgecolor")
     def __init__(self,
                  edgecolor=None,
                  facecolor=None,
@@ -690,6 +691,7 @@ def __str__(self):
         return fmt % pars
 
     @_docstring.dedent_interpd
+    @_api.make_keyword_only("3.6", name="angle")
     def __init__(self, xy, width, height, angle=0.0, *,
                  rotation_point='xy', **kwargs):
         """
@@ -892,6 +894,7 @@ def __str__(self):
                     self.orientation)
 
     @_docstring.dedent_interpd
+    @_api.make_keyword_only("3.6", name="radius")
     def __init__(self, xy, numVertices, radius=5, orientation=0,
                  **kwargs):
         """
@@ -1079,6 +1082,7 @@ def __str__(self):
             return "Polygon0()"
 
     @_docstring.dedent_interpd
+    @_api.make_keyword_only("3.6", name="closed")
     def __init__(self, xy, closed=True, **kwargs):
         """
         *xy* is a numpy array with shape Nx2.
@@ -1175,6 +1179,7 @@ def __str__(self):
         return fmt % pars
 
     @_docstring.dedent_interpd
+    @_api.make_keyword_only("3.6", name="width")
     def __init__(self, center, r, theta1, theta2, width=None, **kwargs):
         """
         A wedge centered at *x*, *y* center with radius *r* that
@@ -1271,6 +1276,7 @@ def __str__(self):
                  closed=True)
 
     @_docstring.dedent_interpd
+    @_api.make_keyword_only("3.6", name="width")
     def __init__(self, x, y, dx, dy, width=1.0, **kwargs):
         """
         Draws an arrow from (*x*, *y*) to (*x* + *dx*, *y* + *dy*).
@@ -1326,6 +1332,7 @@ def __str__(self):
         return "FancyArrow()"
 
     @_docstring.dedent_interpd
+    @_api.make_keyword_only("3.6", name="width")
     def __init__(self, x, y, dx, dy, width=0.001, length_includes_head=False,
                  head_width=None, head_length=None, shape='full', overhang=0,
                  head_starts_at_zero=False, **kwargs):
@@ -1496,6 +1503,7 @@ def __str__(self):
         return s % (self.xy[0], self.xy[1], self.radius, self.numvertices)
 
     @_docstring.dedent_interpd
+    @_api.make_keyword_only("3.6", name="resolution")
     def __init__(self, xy, radius=5,
                  resolution=20,  # the number of vertices
                  ** kwargs):
@@ -1509,7 +1517,8 @@ def __init__(self, xy, radius=5,
 
         %(Patch:kwdoc)s
         """
-        super().__init__(xy, resolution, radius, orientation=0, **kwargs)
+        super().__init__(
+            xy, resolution, radius=radius, orientation=0, **kwargs)
 
 
 class Ellipse(Patch):
@@ -1522,6 +1531,7 @@ def __str__(self):
         return fmt % pars
 
     @_docstring.dedent_interpd
+    @_api.make_keyword_only("3.6", name="angle")
     def __init__(self, xy, width, height, angle=0, **kwargs):
         """
         Parameters
@@ -1913,6 +1923,7 @@ def __str__(self):
         return fmt % pars
 
     @_docstring.dedent_interpd
+    @_api.make_keyword_only("3.6", name="angle")
     def __init__(self, xy, width, height, angle=0.0,
                  theta1=0.0, theta2=360.0, **kwargs):
         """
@@ -1953,7 +1964,7 @@ def __init__(self, xy, width, height, angle=0.0,
         if fill:
             raise ValueError("Arc objects can not be filled")
 
-        super().__init__(xy, width, height, angle, **kwargs)
+        super().__init__(xy, width, height, angle=angle, **kwargs)
 
         self.theta1 = theta1
         self.theta2 = theta2
@@ -3916,6 +3927,7 @@ def __str__(self):
         return s % (self._x, self._y, self._width, self._height)
 
     @_docstring.dedent_interpd
+    @_api.make_keyword_only("3.6", name="mutation_scale")
     @_api.delete_parameter("3.4", "bbox_transmuter", alternative="boxstyle")
     def __init__(self, xy, width, height,
                  boxstyle="round", bbox_transmuter=None,
@@ -4207,6 +4219,7 @@ def __str__(self):
             return f"{type(self).__name__}({self._path_original})"
 
     @_docstring.dedent_interpd
+    @_api.make_keyword_only("3.6", name="path")
     def __init__(self, posA=None, posB=None, path=None,
                  arrowstyle="simple", connectionstyle="arc3",
                  patchA=None, patchB=None,
@@ -4522,6 +4535,7 @@ def __str__(self):
                (self.xy1[0], self.xy1[1], self.xy2[0], self.xy2[1])
 
     @_docstring.dedent_interpd
+    @_api.make_keyword_only("3.6", name="axesA")
     def __init__(self, xyA, xyB, coordsA, coordsB=None,
                  axesA=None, axesB=None,
                  arrowstyle="-",

lib/matplotlib/table.py

@@ -51,6 +51,7 @@ class Cell(Rectangle):
                      'vertical':     'RL'
                      }
 
+    @_api.make_keyword_only("3.6", name="edgecolor")
     def __init__(self, xy, width, height,
                  edgecolor='k', facecolor='w',
                  fill=True,