Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 3f12eae

Browse files
anntzeranntzer
committed
Make arguments to @deprecated/warn_deprecated keyword-only.
(except for the deprecated-since version) In 2.2 there were quite a few deprecation warnings of the form ``` warn_deprecated("2.2", "name-of-the-deprecated-API") ``` (e.g. passing 'box-forced' to set_adjustable, or the 'fig' kwarg to get_subplot_params). Such warnings would just display the name of the deprecated API when triggered, without actually including a deprecation message or the deprecated-since version. This is because the correct call would have been ``` warn_deprecated("2.2", name="name-of-the-deprecated-API") ``` (leaving `message` -- the first arg -- to None, and getting an autogenerated message). To avoid this, make all args to `warn_deprecated` and `@deprecated` keyword-only (except the deprecated-since version). There is no deprecation period on the old signature of these deprecator functions(!) because they are clearly intended for internal use, because handling signature changes is a bit of a pain and because deprecations on the deprecation machinery is a bit too meta.
1 parent 9cffe0e commit 3f12eae

File tree

17 files changed

+61
-51
lines changed

17 files changed

+61
-51
lines changed

‎doc/api/next_api_changes/2018-09-18-AL-deprecation-machinery.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Changes to the signatures of `cbook.deprecated` and `cbook.warn_deprecated`
2+
```````````````````````````````````````````````````````````````````````````
3+
4+
All arguments to the `cbook.deprecated` decorator and `cbook.warn_deprecated`
5+
function, except the first one (the version where the deprecation occurred),
6+
are now keyword-only. The goal is to avoid accidentally setting the "message"
7+
argument when the "name" (or "alternative") argument was intended, as this has
8+
repeatedly occurred in the past.

‎lib/matplotlib/__init__.py

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -172,11 +172,11 @@ def compare_versions(a, b):
172172
"return True if a is greater than or equal to b"
173173
if isinstance(a, bytes):
174174
cbook.warn_deprecated(
175-
"3.0", "compare_versions arguments should be strs.")
175+
"3.0", message="compare_versions arguments should be strs.")
176176
a = a.decode('ascii')
177177
if isinstance(b, bytes):
178178
cbook.warn_deprecated(
179-
"3.0", "compare_versions arguments should be strs.")
179+
"3.0", message="compare_versions arguments should be strs.")
180180
b = b.decode('ascii')
181181
if a:
182182
a = distutils.version.LooseVersion(a)
@@ -819,7 +819,7 @@ def __setitem__(self, key, val):
819819
if key in _deprecated_map:
820820
version, alt_key, alt_val, inverse_alt = _deprecated_map[key]
821821
cbook.warn_deprecated(
822-
version, key, obj_type="rcparam", alternative=alt_key)
822+
version, name=key, obj_type="rcparam", alternative=alt_key)
823823
key = alt_key
824824
val = alt_val(val)
825825
elif key in _deprecated_remain_as_none and val is not None:
@@ -839,8 +839,9 @@ def __setitem__(self, key, val):
839839
return
840840
elif key == 'examples.directory':
841841
cbook.warn_deprecated(
842-
"3.0", "{} is deprecated; in the future, examples will be "
843-
"found relative to the 'datapath' directory.".format(key))
842+
"3.0", name=key, obj_type="rcparam", addendum="In the "
843+
"future, examples will be found relative to the "
844+
"'datapath' directory.")
844845
elif key == 'backend':
845846
if val is rcsetup._auto_backend_sentinel:
846847
if 'backend' in self:
@@ -859,19 +860,19 @@ def __getitem__(self, key):
859860
if key in _deprecated_map:
860861
version, alt_key, alt_val, inverse_alt = _deprecated_map[key]
861862
cbook.warn_deprecated(
862-
version, key, obj_type="rcparam", alternative=alt_key)
863+
version, name=key, obj_type="rcparam", alternative=alt_key)
863864
return inverse_alt(dict.__getitem__(self, alt_key))
864865

865866
elif key in _deprecated_ignore_map:
866867
version, alt_key = _deprecated_ignore_map[key]
867868
cbook.warn_deprecated(
868-
version, key, obj_type="rcparam", alternative=alt_key)
869+
version, name=key, obj_type="rcparam", alternative=alt_key)
869870
return dict.__getitem__(self, alt_key) if alt_key else None
870871

871872
elif key == 'examples.directory':
872873
cbook.warn_deprecated(
873-
"3.0", "{} is deprecated; in the future, examples will be "
874-
"found relative to the 'datapath' directory.".format(key))
874+
"3.0", name=key, obj_type="rcparam", addendum="In the future, "
875+
"examples will be found relative to the 'datapath' directory.")
875876

876877
elif key == "backend":
877878
val = dict.__getitem__(self, key)
@@ -1019,7 +1020,7 @@ def _rc_params_in_file(fname, fail_on_error=False):
10191020
elif key in _deprecated_ignore_map:
10201021
version, alt_key = _deprecated_ignore_map[key]
10211022
cbook.warn_deprecated(
1022-
version, key, alternative=alt_key,
1023+
version, name=key, alternative=alt_key,
10231024
addendum="Please update your matplotlibrc.")
10241025
else:
10251026
print("""

‎lib/matplotlib/afm.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -357,7 +357,7 @@ def _parse_optional(fh):
357357
return d[b'StartKernData'], d[b'StartComposites']
358358

359359

360-
@deprecated("3.0", "Use the class AFM instead.")
360+
@deprecated("3.0", alternative="the AFM class")
361361
def parse_afm(fh):
362362
return _parse_afm(fh)
363363

‎lib/matplotlib/animation.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1692,10 +1692,10 @@ def gen():
16921692
pass
16931693
else:
16941694
cbook.warn_deprecated(
1695-
"2.2", "FuncAnimation.save has truncated your "
1696-
"animation to 100 frames. In the future, no such "
1697-
"truncation will occur; please pass 'save_count' "
1698-
"accordingly.")
1695+
"2.2", message="FuncAnimation.save has truncated "
1696+
"your animation to 100 frames. In the future, no "
1697+
"such truncation will occur; please pass "
1698+
"'save_count' accordingly.")
16991699

17001700
return gen()
17011701

‎lib/matplotlib/artist.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -533,7 +533,7 @@ def get_picker(self):
533533
"""
534534
return self._picker
535535

536-
@cbook.deprecated("2.2", "artist.figure is not None")
536+
@cbook.deprecated("2.2", alternative="artist.figure is not None")
537537
def is_figure_set(self):
538538
"""Returns whether the artist is assigned to a `.Figure`."""
539539
return self.figure is not None

‎lib/matplotlib/axes/_base.py

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -374,8 +374,9 @@ def _plot_args(self, tup, kwargs):
374374

375375
ncx, ncy = x.shape[1], y.shape[1]
376376
if ncx > 1 and ncy > 1 and ncx != ncy:
377-
cbook.warn_deprecated("2.2", "cycling among columns of inputs "
378-
"with non-matching shapes is deprecated.")
377+
cbook.warn_deprecated(
378+
"2.2", message="cycling among columns of inputs with "
379+
"non-matching shapes is deprecated.")
379380
for j in range(max(ncx, ncy)):
380381
seg = func(x[:, j % ncx], y[:, j % ncy], kw, kwargs)
381382
ret.append(seg)
@@ -1653,7 +1654,7 @@ def axis(self, *v, **kwargs):
16531654
if s == 'normal':
16541655
cbook.warn_deprecated(
16551656
"3.1", "Passing 'normal' to axis() is deprecated "
1656-
"since %(version)s; use 'auto' instead.")
1657+
"since %(since)s; use 'auto' instead.")
16571658
self.set_autoscale_on(True)
16581659
self.set_aspect('auto')
16591660
self.autoscale_view(tight=False)

‎lib/matplotlib/backend_bases.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1859,9 +1859,9 @@ def enter_notify_event(self, guiEvent=None, xy=None):
18591859
else:
18601860
x = None
18611861
y = None
1862-
cbook.warn_deprecated('3.0', 'enter_notify_event expects a '
1863-
'location but '
1864-
'your backend did not pass one.')
1862+
cbook.warn_deprecated(
1863+
'3.0', message='enter_notify_event expects a location but '
1864+
'your backend did not pass one.')
18651865

18661866
event = LocationEvent('figure_enter_event', self, x, y, guiEvent)
18671867
self.callbacks.process('figure_enter_event', event)

‎lib/matplotlib/backends/backend_wx.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -123,8 +123,8 @@ class TimerWx(TimerBase):
123123
def __init__(self, *args, **kwargs):
124124
if args and isinstance(args[0], wx.EvtHandler):
125125
cbook.warn_deprecated(
126-
"3.0", "Passing a wx.EvtHandler as first argument to the "
127-
"TimerWx constructor is deprecated since %(version)s.")
126+
"3.0", message="Passing a wx.EvtHandler as first argument to "
127+
"the TimerWx constructor is deprecated since %(since)s.")
128128
args = args[1:]
129129
TimerBase.__init__(self, *args, **kwargs)
130130
self._timer = wx.Timer()

‎lib/matplotlib/backends/tkagg.py

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,7 @@
66
from matplotlib.backends import _tkagg
77

88

9-
cbook.warn_deprecated(
10-
"3.0", "The matplotlib.backends.tkagg module is deprecated.")
9+
cbook.warn_deprecated("3.0", name=__name__, obj_type="module")
1110

1211

1312
def blit(photoimage, aggimage, bbox=None, colormode=1):

‎lib/matplotlib/backends/wx_compat.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
from .backend_wx import RendererWx
1313

1414

15-
cbook.warn_deprecated("3.0", "{} is deprecated.".format(__name__))
15+
cbook.warn_deprecated("3.0", name=__name__, obj_type="module")
1616

1717
backend_version = wx.VERSION_STRING
1818
is_phoenix = 'phoenix' in wx.PlatformInfo

‎lib/matplotlib/cbook/__init__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -361,7 +361,7 @@ def file_requires_unicode(x):
361361
return False
362362

363363

364-
@deprecated('3.0', 'isinstance(..., numbers.Number)')
364+
@deprecated('3.0', alternative='isinstance(..., numbers.Number)')
365365
def is_numlike(obj):
366366
"""return true if *obj* looks like a number"""
367367
return isinstance(obj, (numbers.Number, np.number))

‎lib/matplotlib/cbook/deprecation.py

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ def _generate_deprecation_message(
2525
obj_type='attribute', addendum='', *, removal=''):
2626

2727
if removal == "":
28-
removal = {"2.2": "in 3.1", "3.0": "in 3.2"}.get(
28+
removal = {"2.2": "in 3.1", "3.0": "in 3.2", "3.1": "in 3.3"}.get(
2929
since, "two minor releases later")
3030
elif removal:
3131
if pending:
@@ -52,8 +52,8 @@ def _generate_deprecation_message(
5252

5353

5454
def warn_deprecated(
55-
since, message='', name='', alternative='', pending=False,
56-
obj_type='attribute', addendum='', *, removal=''):
55+
since, *, message='', name='', alternative='', pending=False,
56+
obj_type='attribute', addendum='', removal=''):
5757
"""
5858
Used to display deprecation in a standard way.
5959
@@ -113,8 +113,8 @@ def warn_deprecated(
113113
_warn_external(message, category)
114114

115115

116-
def deprecated(since, message='', name='', alternative='', pending=False,
117-
obj_type=None, addendum='', *, removal=''):
116+
def deprecated(since, *, message='', name='', alternative='', pending=False,
117+
obj_type=None, addendum='', removal=''):
118118
"""
119119
Decorator to mark a function, a class, or a property as deprecated.
120120

‎lib/matplotlib/collections.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -270,8 +270,8 @@ def draw(self, renderer):
270270
except AttributeError:
271271
# if we end up with a GC that does not have this method
272272
cbook.warn_deprecated(
273-
"3.1", "Your backend does not support setting the hatch "
274-
"color; such backends will become unsupported in "
273+
"3.1", message="Your backend does not support setting the "
274+
"hatch color; such backends will become unsupported in "
275275
"Matplotlib 3.3.")
276276

277277
if self.get_sketch_params() is not None:

‎lib/matplotlib/figure.py

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -89,11 +89,12 @@ def get(self, key):
8989
return None
9090
cbook.warn_deprecated(
9191
"2.1",
92-
"Adding an axes using the same arguments as a previous axes "
93-
"currently reuses the earlier instance. In a future version, "
94-
"a new instance will always be created and returned. Meanwhile, "
95-
"this warning can be suppressed, and the future behavior ensured, "
96-
"by passing a unique label to each axes instance.")
92+
message="Adding an axes using the same arguments as a previous "
93+
"axes currently reuses the earlier instance. In a future "
94+
"version, a new instance will always be created and returned. "
95+
"Meanwhile, this warning can be suppressed, and the future "
96+
"behavior ensured, by passing a unique label to each axes "
97+
"instance.")
9798
return item[1]
9899

99100
def _entry_from_axes(self, e):
@@ -1745,7 +1746,7 @@ def legend(self, *args, **kwargs):
17451746
if len(extra_args):
17461747
# cbook.warn_deprecated(
17471748
# "2.1",
1748-
# "Figure.legend will accept no more than two "
1749+
# message="Figure.legend will accept no more than two "
17491750
# "positional arguments in the future. Use "
17501751
# "'fig.legend(handles, labels, loc=location)' "
17511752
# "instead.")

‎lib/matplotlib/markers.py

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -375,16 +375,16 @@ def _set_tuple_marker(self):
375375
self._joinstyle = 'bevel'
376376
elif symstyle == 3:
377377
cbook.warn_deprecated(
378-
"3.0", "Setting a circle marker using `(..., 3)` is "
379-
"deprecated since Matplotlib 3.0, and support for it will "
380-
"be removed in 3.2. Directly pass 'o' instead.")
378+
"3.0", message="Setting a circle marker using `(..., 3)` "
379+
"is deprecated since Matplotlib 3.0, and support for it "
380+
"will be removed in 3.2. Directly pass 'o' instead.")
381381
self._path = Path.unit_circle()
382382
self._transform = Affine2D().scale(0.5).rotate_deg(rotation)
383383
else:
384384
cbook.warn_deprecated(
385-
"3.0", "Passing vertices as `(verts, 0)` is deprecated since "
386-
"Matplotlib 3.0, and support for it will be removed in 3.2. "
387-
"Directly pass `verts` instead.")
385+
"3.0", message="Passing vertices as `(verts, 0)` is "
386+
"deprecated since Matplotlib 3.0, and support for it will be "
387+
"removed in 3.2. Directly pass `verts` instead.")
388388
verts = np.asarray(marker[0])
389389
path = Path(verts)
390390
self._set_custom_marker(path)

‎lib/matplotlib/patches.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -522,8 +522,8 @@ def _bind_draw_path_function(self, renderer):
522522
except AttributeError:
523523
# if we end up with a GC that does not have this method
524524
cbook.warn_deprecated(
525-
"3.1", "Your backend does not support setting the hatch "
526-
"color; such backends will become unsupported in "
525+
"3.1", message="Your backend does not support setting the "
526+
"hatch color; such backends will become unsupported in "
527527
"Matplotlib 3.3.")
528528

529529
if self.get_sketch_params() is not None:

‎lib/mpl_toolkits/mplot3d/art3d.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -533,8 +533,8 @@ def set_zsort(self, zsort):
533533
"""
534534
if zsort is True:
535535
cbook.warn_deprecated(
536-
"3.1", "Passing True to mean 'average' for set_zsort is "
537-
"deprecated and support will be removed in Matplotlib 3.3; "
536+
"3.1", message="Passing True to mean 'average' for set_zsort "
537+
"is deprecated and support will be removed in Matplotlib 3.3; "
538538
"pass 'average' instead.")
539539
zsort = 'average'
540540
self._zsortfunc = self._zsort_functions[zsort]

0 commit comments

Comments
 (0)