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
Appearance settings

Commit 114d516

Browse filesBrowse files
tacaswelltacaswell
authored
Merge pull request #13128 from anntzer/rename_parameter
ENH/API: Parameter-renaming decorator
2 parents 00d71ce + 90b0f4d commit 114d516
Copy full SHA for 114d516

File tree

Expand file treeCollapse file tree

8 files changed

+95
-17
lines changed
Filter options
Expand file treeCollapse file tree

8 files changed

+95
-17
lines changed

‎doc/api/next_api_changes/2018-01-10-AL.rst

Copy file name to clipboard
+11Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Changes in parameter names
2+
``````````````````````````
3+
4+
- The ``arg`` parameter to `matplotlib.use` has been renamed to ``backend``.
5+
- The ``normed`` parameter to `Axes.hist2d` has been renamed to ``density``.
6+
- The ``s`` parameter to `Annotation` (and indirectly `Axes.annotation`) has
7+
been renamed to ``text``.
8+
9+
In each case, the old parameter name remains supported (it cannot be used
10+
simultaneously with the new name), but suppport for it will be dropped in
11+
Matplotlib 3.3.

‎lib/matplotlib/__init__.py

Copy file name to clipboardExpand all lines: lib/matplotlib/__init__.py
+6-3Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1183,13 +1183,14 @@ def __exit__(self, exc_type, exc_value, exc_tb):
11831183
self.__fallback()
11841184

11851185

1186-
def use(arg, warn=False, force=True):
1186+
@cbook._rename_parameter("3.1", "arg", "backend")
1187+
def use(backend, warn=False, force=True):
11871188
"""
11881189
Set the matplotlib backend to one of the known backends.
11891190
11901191
Parameters
11911192
----------
1192-
arg : str
1193+
backend : str
11931194
The backend to switch to. This can either be one of the
11941195
'standard' backend names:
11951196
@@ -1205,6 +1206,8 @@ def use(arg, warn=False, force=True):
12051206
12061207
Note: Standard backend names are case-insensitive here.
12071208
1209+
*arg* is a deprecated synonym for this parameter.
1210+
12081211
warn : bool, optional
12091212
If True, warn if this is called after pyplot has been imported
12101213
and a backend is set up.
@@ -1221,7 +1224,7 @@ def use(arg, warn=False, force=True):
12211224
:ref:`backends`
12221225
matplotlib.get_backend
12231226
"""
1224-
name = validate_backend(arg)
1227+
name = validate_backend(backend)
12251228

12261229
# if setting back to the same thing, do nothing
12271230
if (dict.__getitem__(rcParams, 'backend') == name):

‎lib/matplotlib/axes/_axes.py

Copy file name to clipboardExpand all lines: lib/matplotlib/axes/_axes.py
+6-4Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6845,7 +6845,8 @@ def hist(self, x, bins=None, range=None, density=None, weights=None,
68456845
return tops, bins, cbook.silent_list('Lists of Patches', patches)
68466846

68476847
@_preprocess_data(replace_names=["x", "y", "weights"])
6848-
def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
6848+
@cbook._rename_parameter("3.1", "normed", "density")
6849+
def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
68496850
cmin=None, cmax=None, **kwargs):
68506851
"""
68516852
Make a 2D histogram plot.
@@ -6879,8 +6880,9 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
68796880
xmax], [ymin, ymax]]``. All values outside of this range will be
68806881
considered outliers and not tallied in the histogram.
68816882
6882-
normed : bool, optional, default: False
6883-
Normalize histogram.
6883+
density : bool, optional, default: False
6884+
Normalize histogram. *normed* is a deprecated synonym for this
6885+
parameter.
68846886
68856887
weights : array_like, shape (n, ), optional, default: None
68866888
An array of values w_i weighing each sample (x_i, y_i).
@@ -6939,7 +6941,7 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
69396941
"""
69406942

69416943
h, xedges, yedges = np.histogram2d(x, y, bins=bins, range=range,
6942-
normed=normed, weights=weights)
6944+
normed=density, weights=weights)
69436945

69446946
if cmin is not None:
69456947
h[h < cmin] = None

‎lib/matplotlib/cbook/__init__.py

Copy file name to clipboardExpand all lines: lib/matplotlib/cbook/__init__.py
+2-1Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,8 @@
3232

3333
import matplotlib
3434
from .deprecation import (
35-
mplDeprecation, deprecated, warn_deprecated, MatplotlibDeprecationWarning)
35+
deprecated, warn_deprecated, _rename_parameter,
36+
MatplotlibDeprecationWarning, mplDeprecation)
3637

3738

3839
@deprecated("3.0")

‎lib/matplotlib/cbook/deprecation.py

Copy file name to clipboardExpand all lines: lib/matplotlib/cbook/deprecation.py
+48Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -258,3 +258,51 @@ def wrapper(*args, **kwargs):
258258
return finalize(wrapper, new_doc)
259259

260260
return deprecate
261+
262+
263+
def _rename_parameter(since, old, new, func=None):
264+
"""
265+
Decorator indicating that parameter *old* of *func* is renamed to *new*.
266+
267+
The actual implementation of *func* should use *new*, not *old*. If *old*
268+
is passed to *func*, a DeprecationWarning is emitted, and its value is
269+
used, even if *new* is also passed by keyword (this is to simplify pyplot
270+
wrapper functions, which always pass *new* explicitly to the Axes method).
271+
If *new* is also passed but positionally, a TypeError will be raised by the
272+
underlying function during argument binding.
273+
274+
Examples
275+
--------
276+
277+
::
278+
@_rename_parameter("3.1", "bad_name", "good_name")
279+
def func(good_name): ...
280+
"""
281+
282+
if func is None:
283+
return functools.partial(_rename_parameter, since, old, new)
284+
285+
signature = inspect.signature(func)
286+
assert old not in signature.parameters, (
287+
f"Matplotlib internal error: {old!r} cannot be a parameter for "
288+
f"{func.__name__}()")
289+
assert new in signature.parameters, (
290+
f"Matplotlib internal error: {new!r} must be a parameter for "
291+
f"{func.__name__}()")
292+
293+
@functools.wraps(func)
294+
def wrapper(*args, **kwargs):
295+
if old in kwargs:
296+
warn_deprecated(
297+
since, message=f"The {old!r} parameter of {func.__name__}() "
298+
f"has been renamed {new!r} since Matplotlib {since}; support "
299+
f"for the old name will be dropped %(removal)s.")
300+
kwargs[new] = kwargs.pop(old)
301+
return func(*args, **kwargs)
302+
303+
# wrapper() must keep the same documented signature as func(): if we
304+
# instead made both *old* and *new* appear in wrapper()'s signature, they
305+
# would both show up in the pyplot function for an Axes method as well and
306+
# pyplot would explicitly pass both arguments to the Axes method.
307+
308+
return wrapper

‎lib/matplotlib/pyplot.py

Copy file name to clipboardExpand all lines: lib/matplotlib/pyplot.py
+4-4Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2632,12 +2632,12 @@ def hist(
26322632
# Autogenerated by boilerplate.py. Do not edit as changes will be lost.
26332633
@_autogen_docstring(Axes.hist2d)
26342634
def hist2d(
2635-
x, y, bins=10, range=None, normed=False, weights=None,
2635+
x, y, bins=10, range=None, density=False, weights=None,
26362636
cmin=None, cmax=None, *, data=None, **kwargs):
26372637
__ret = gca().hist2d(
2638-
x, y, bins=bins, range=range, normed=normed, weights=weights,
2639-
cmin=cmin, cmax=cmax, **({"data": data} if data is not None
2640-
else {}), **kwargs)
2638+
x, y, bins=bins, range=range, density=density,
2639+
weights=weights, cmin=cmin, cmax=cmax, **({"data": data} if
2640+
data is not None else {}), **kwargs)
26412641
sci(__ret[-1])
26422642
return __ret
26432643

‎lib/matplotlib/tests/test_axes.py

Copy file name to clipboardExpand all lines: lib/matplotlib/tests/test_axes.py
+11Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1739,6 +1739,17 @@ def test_hist2d_transpose():
17391739
ax.hist2d(x, y, bins=10, rasterized=True)
17401740

17411741

1742+
def test_hist2d_density_normed():
1743+
x, y = np.random.random((2, 100))
1744+
ax = plt.figure().subplots()
1745+
for obj in [ax, plt]:
1746+
obj.hist2d(x, y, density=True)
1747+
with pytest.warns(MatplotlibDeprecationWarning):
1748+
obj.hist2d(x, y, normed=True)
1749+
with pytest.warns(MatplotlibDeprecationWarning):
1750+
obj.hist2d(x, y, density=True, normed=True)
1751+
1752+
17421753
class TestScatter(object):
17431754
@image_comparison(baseline_images=['scatter'],
17441755
style='mpl20', remove_text=True)

‎lib/matplotlib/text.py

Copy file name to clipboardExpand all lines: lib/matplotlib/text.py
+7-5Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1971,15 +1971,16 @@ class Annotation(Text, _AnnotationBase):
19711971
def __str__(self):
19721972
return "Annotation(%g, %g, %r)" % (self.xy[0], self.xy[1], self._text)
19731973

1974-
def __init__(self, s, xy,
1974+
@cbook._rename_parameter("3.1", "s", "text")
1975+
def __init__(self, text, xy,
19751976
xytext=None,
19761977
xycoords='data',
19771978
textcoords=None,
19781979
arrowprops=None,
19791980
annotation_clip=None,
19801981
**kwargs):
19811982
"""
1982-
Annotate the point *xy* with text *s*.
1983+
Annotate the point *xy* with text *text*.
19831984
19841985
In the simplest form, the text is placed at *xy*.
19851986
@@ -1989,8 +1990,9 @@ def __init__(self, s, xy,
19891990
19901991
Parameters
19911992
----------
1992-
s : str
1993-
The text of the annotation.
1993+
text : str
1994+
The text of the annotation. *s* is a deprecated synonym for this
1995+
parameter.
19941996
19951997
xy : (float, float)
19961998
The point *(x,y)* to annotate.
@@ -2165,7 +2167,7 @@ def transform(renderer) -> Transform
21652167
xytext = self.xy
21662168
x, y = xytext
21672169

2168-
Text.__init__(self, x, y, s, **kwargs)
2170+
Text.__init__(self, x, y, text, **kwargs)
21692171

21702172
self.arrowprops = arrowprops
21712173

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.