Skip to content

Deprecate positional passing of most Artist constructor parameters #23177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 16, 2022
Merged

Deprecate positional passing of most Artist constructor parameters #23177

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions doc/api/next_api_changes/deprecations/23166-ES.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
7 changes: 4 additions & 3 deletions lib/matplotlib/axes/_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down
1 change: 1 addition & 0 deletions lib/matplotlib/axis.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 7 additions & 0 deletions lib/matplotlib/collections.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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',
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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*
Expand Down
4 changes: 3 additions & 1 deletion lib/matplotlib/figure.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
5 changes: 5 additions & 0 deletions lib/matplotlib/image.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down
1 change: 1 addition & 0 deletions lib/matplotlib/lines.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
8 changes: 8 additions & 0 deletions lib/matplotlib/offsetbox.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you want to start at "pad" here? In AnchoredText/AnchoredBox you chose "pad".

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd leave this as proposed. If in doubt I try to err on the more permissive side, so that we don't overly constrain the API and force people to change still reasonable calls. For PaddedBox pad is quite canonical and I think we should still allow PaddedBox(child, 0.5). AnchoredText/AnchoredBox have other parameters before pad and pad as central a concept as it is with PaddedBox.

def __init__(self, child, pad=None, draw_frame=False, patch_attrs=None):
"""
Parameters
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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',
Expand Down
18 changes: 16 additions & 2 deletions lib/matplotlib/patches.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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):
"""
Expand Down Expand Up @@ -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):
"""
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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*).
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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):
Expand All @@ -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):
Expand All @@ -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
Expand Down Expand Up @@ -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):
"""
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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="-",
Expand Down
1 change: 1 addition & 0 deletions lib/matplotlib/table.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion lib/matplotlib/tests/test_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7586,7 +7586,7 @@ def test_nan_barlabels():

def test_patch_bounds(): # PR 19078
fig, ax = plt.subplots()
ax.add_patch(mpatches.Wedge((0, -1), 1.05, 60, 120, 0.1))
ax.add_patch(mpatches.Wedge((0, -1), 1.05, 60, 120, width=0.1))
bot = 1.9*np.sin(15*np.pi/180)**2
np.testing.assert_array_almost_equal_nulp(
np.array((-0.525, -(bot+0.05), 1.05, bot+0.1)), ax.dataLim.bounds, 16)
Expand Down
4 changes: 2 additions & 2 deletions lib/matplotlib/tests/test_collections.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1156,9 +1156,9 @@ def test_set_offsets_late():

def test_set_offset_transform():
skew = mtransforms.Affine2D().skew(2, 2)
init = mcollections.Collection([], offset_transform=skew)
init = mcollections.Collection(offset_transform=skew)

late = mcollections.Collection([])
late = mcollections.Collection()
late.set_offset_transform(skew)

assert skew == init.get_offset_transform() == late.get_offset_transform()
Expand Down
4 changes: 2 additions & 2 deletions lib/matplotlib/tests/test_patches.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -547,7 +547,7 @@ def test_datetime_datetime_fails():


def test_contains_point():
ell = mpatches.Ellipse((0.5, 0.5), 0.5, 1.0, 0)
ell = mpatches.Ellipse((0.5, 0.5), 0.5, 1.0)
points = [(0.0, 0.5), (0.2, 0.5), (0.25, 0.5), (0.5, 0.5)]
path = ell.get_path()
transform = ell.get_transform()
Expand All @@ -560,7 +560,7 @@ def test_contains_point():


def test_contains_points():
ell = mpatches.Ellipse((0.5, 0.5), 0.5, 1.0, 0)
ell = mpatches.Ellipse((0.5, 0.5), 0.5, 1.0)
points = [(0.0, 0.5), (0.2, 0.5), (0.25, 0.5), (0.5, 0.5)]
path = ell.get_path()
transform = ell.get_transform()
Expand Down
1 change: 1 addition & 0 deletions lib/matplotlib/text.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,7 @@ class Text(Artist):
def __repr__(self):
return "Text(%s, %s, %s)" % (self._x, self._y, repr(self._text))

@_api.make_keyword_only("3.6", name="color")
def __init__(self,
x=0, y=0, text='',
color=None, # defaults to rc params
Expand Down