8000 Merge pull request #12440 from anntzer/deprecatekwargonly · matplotlib/matplotlib@d4c1e72 · GitHub
[go: up one dir, main page]
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

‎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: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,8 @@ def _generate_deprecation_message(
5151

5252

5353
def warn_deprecated(
54-
since, message='', name='', alternative='', pending=False,
55-
obj_type='attribute', addendum='', *, removal=''):
54+
since, *, message='', name='', alternative='', pending=False,
55+
obj_type='attribute', addendum='', removal=''):
5656
"""
5757
Used to display deprecation in a standard way.
5858
@@ -112,8 +112,8 @@ def warn_deprecated(
112112
_warn_external(message, category)
113113

114114

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

‎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
@@ -88,11 +88,12 @@ def get(self, key):
8888
return None
8989
cbook.warn_deprecated(
9090
"2.1",
91-
"Adding an axes using the same arguments as a previous axes "
92-
"currently reuses the earlier instance. In a future version, "
93-
"a new instance will always be created and returned. Meanwhile 10000 , "
94-
"this warning can be suppressed, and the future behavior ensured, "
95-
"by passing a unique label to each axes instance.")
91+
message="Adding an axes using the same arguments as a previous "
92+
"axes currently reuses the earlier instance. In a future "
93+
"version, a new instance will always be created and returned. "
94+
"Meanwhile, this warning can be suppressed, and the future "
95+
"behavior ensured, by passing a unique label to each axes "
96+
"instance.")
9697
return item[1]
9798

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

‎lib/matplotlib/markers.py

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -370,16 +370,16 @@ def _set_tuple_marker(self):
370370
self._joinstyle = 'bevel'
371371
elif symstyle == 3:
372372
cbook.warn_deprecated(
373-
"3.0", "Setting a circle marker using `(..., 3)` is "
374-
"deprecated since Matplotlib 3.0, and support for it will "
375-
"be removed in 3.2. Directly pass 'o' instead.")
373+
"3.0", message="Setting a circle marker using `(..., 3)` "
374+
"is deprecated since Matplotlib 3.0, and support for it "
375+
"will be removed in 3.2. Directly pass 'o' instead.")
376376
self._path = Path.unit_circle()
377377
self._transform = Affine2D().scale(0.5).rotate_deg(rotation)
378378
else:
379379
cbook.warn_deprecated(
380-
"3.0", "Passing vertices as `(verts, 0)` is deprecated since "
381-
"Matplotlib 3.0, and support for it will be removed in 3.2. "
382-
"Directly pass `verts` instead.")
380+
"3.0", message="Passing vertices as `(verts, 0)` is "
381+
"deprecated since Matplotlib 3.0, and support for it will be "
382+
"removed in 3.2. Directly pass `verts` instead.")
383383
verts = np.asarray(marker[0])
384384
path = Path(verts)
385385
self._set_custom_marker(path)

‎lib/matplotlib/patches.py

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

530530
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)
0