10000 Make arguments to @deprecated/warn_deprecated keyword-only. · thoo/matplotlib@3f12eae · GitHub
[go: up one dir, main page]
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

0 commit comments

Comments
 (0)
0