Skip to content

Commit d4c1e72

Browse files
dstansbydstansby
authored
Merge pull request #12440 from anntzer/deprecatekwargonly
Make arguments to @deprecated/warn_deprecated keyword-only.
2 parents d0deb47 + 3f12eae commit d4c1e72

File tree

17 files changed

+60
-50
lines changed

17 files changed

+60
-50
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)
@@ -810,7 +810,7 @@ def __setitem__(self, key, val):
810810
if key in _deprecated_map:
811811
version, alt_key, alt_val, inverse_alt = _deprecated_map[key]
812812
cbook.warn_deprecated(
813-
version, key, obj_type="rcparam", alternative=alt_key)
813+
version, name=key, obj_type="rcparam", alternative=alt_key)
814814
key = alt_key
815815
val = alt_val(val)
816816
elif key in _deprecated_remain_as_none and val is not None:
@@ -830,8 +830,9 @@ def __setitem__(self, key, val):
830830
return
831831
elif key == 'examples.directory':
832832
cbook.warn_deprecated(
833-
"3.0", "{} is deprecated; in the future, examples will be "
834-
"found relative to the 'datapath' directory.".format(key))
833+
"3.0", name=key, obj_type="rcparam", addendum="In the "
834+
"future, examples will be found relative to the "
835+
"'datapath' directory.")
835836
elif key == 'backend':
836837
if val is rcsetup._auto_backend_sentinel:
837838
if 'backend' in self:
@@ -850,19 +851,19 @@ def __getitem__(self, key):
850851
if key in _deprecated_map:
851852
version, alt_key, alt_val, inverse_alt = _deprecated_map[key]
852853
cbook.warn_deprecated(
853-
version, key, obj_type="rcparam", alternative=alt_key)
854+
version, name=key, obj_type="rcparam", alternative=alt_key)
854855
return inverse_alt(dict.__getitem__(self, alt_key))
855856

856857
elif key in _deprecated_ignore_map:
857858
version, alt_key = _deprecated_ignore_map[key]
858859
cbook.warn_deprecated(
859-
version, key, obj_type="rcparam", alternative=alt_key)
860+
version, name=key, obj_type="rcparam", alternative=alt_key)
860861
return dict.__getitem__(self, alt_key) if alt_key else None
861862

862863
elif key == 'examples.directory':
863864
cbook.warn_deprecated(
864-
"3.0", "{} is deprecated; in the future, examples will be "
865-
"found relative to the 'datapath' directory.".format(key))
865+
"3.0", name=key, obj_type="rcparam", addendum="In the future, "
866+
"examples will be found relative to the 'datapath' directory.")
866867

867868
elif key == "backend":
868869
val = dict.__getitem__(self, key)
@@ -1008,7 +1009,7 @@ def _rc_params_in_file(fname, fail_on_error=False):
10081009
elif key in _deprecated_ignore_map:
10091010
version, alt_key = _deprecated_ignore_map[key]
10101011
cbook.warn_deprecated(
1011-
version, key, alternative=alt_key,
1012+
version, name=key, alternative=alt_key,
10121013
addendum="Please update your matplotlibrc.")
10131014
else:
10141015
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
@@ -1678,10 +1678,10 @@ def gen():
16781678
pass
16791679
else:
16801680
cbook.warn_deprecated(
1681-
"2.2", "FuncAnimation.save has truncated your "
1682-
"animation to 100 frames. In the future, no such "
1683-
"truncation will occur; please pass 'save_count' "
1684-
"accordingly.")
1681+
"2.2", message="FuncAnimation.save has truncated "
1682+
"your animation to 100 frames. In the future, no "
1683+
"such truncation will occur; please pass "
1684+
"'save_count' accordingly.")
16851685

16861686
return gen()
16871687

‎lib/matplotlib/artist.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -536,7 +536,7 @@ def get_picker(self):
536536
"""
537537
return self._picker
538538

539-
@cbook.deprecated("2.2", "artist.figure is not None")
539+
@cbook.deprecated("2.2", alternative="artist.figure is not None")
540540
def is_figure_set(self):
541541
"""Returns whether the artist is assigned to a `.Figure`."""
542542
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
@@ -373,8 +373,9 @@ def _plot_args(self, tup, kwargs):
373373

374374
ncx, ncy = x.shape[1], y.shape[1]
375375
if ncx > 1 and ncy > 1 and ncx != ncy:
376-
cbook.warn_deprecated("2.2", "cycling among columns of inputs "
377-
"with non-matching shapes is deprecated.")
376+
cbook.warn_deprecated(
377+
"2.2", message="cycling among columns of inputs with "
378+
"non-matching shapes is deprecated.")
378379
for j in range(max(ncx, ncy)):
379380
seg = func(x[:, j % ncx], y[:, j % ncy], kw, kwargs)
380381
ret.append(seg)
@@ -1645,7 +1646,7 @@ def axis(self, *v, **kwargs):
16451646
if s == 'normal':
16461647
cbook.warn_deprecated(
16471648
"3.1", "Passing 'normal' to axis() is deprecated "
1648-
"since %(version)s; use 'auto' instead.")
1649+
"since %(since)s; use 'auto' instead.")
16491650
self.set_autoscale_on(True)
16501651
self.set_aspect('auto')
16511652
self.autoscale_view(tight=False)

‎lib/matplotlib/backend_bases.py

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

18671867
event = LocationEvent('figure_enter_event', self, x, y, guiEvent)
18681868
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
@@ -124,8 +124,8 @@ class TimerWx(TimerBase):
124124
def __init__(self, *args, **kwargs):
125125
if args and isinstance(args[0], wx.EvtHandler):
126126
cbook.warn_deprecated(
127-
"3.0", "Passing a wx.EvtHandler as first argument to the "
128-
"TimerWx constructor is deprecated since %(version)s.")
127+
"3.0", message="Passing a wx.EvtHandler as first argument to "
128+
"the TimerWx constructor is deprecated since %(since)s.")
129129
args = args[1:]
130130
TimerBase.__init__(self, *args, **kwargs)
131131
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

0 commit comments

Comments
 (0)