1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
# ----------------------------------------------------------------------------
# Copyright (c) 2013--, scikit-bio development team.
#
# Distributed under the terms of the Modified BSD License.
#
# The full license is in the file LICENSE.txt, distributed with this software.
# ----------------------------------------------------------------------------
from warnings import warn, simplefilter
def _warn_once(func, warning, message, param=None):
r"""Warn once
Parameters
----------
func : callable
Function that triggers the warning.
warning : class
Warning type.
message : str
Warning message.
param : str, optional
Parameter of the function that triggers the warning.
Notes
-----
The warning is raised only at the first call of the function. Meanwhile, a "_warned"
attribute is added to the function, which prevents subsequent warnings.
If a parameter is given, the warning is raised at the first use of the particular
parameter, while not affect the host function or other parameters. Meanwhile, a
"_warned_params" attribute of the function will contain the parameter to prevent
subsequent warnings.
"""
if not param:
if not hasattr(func, "_warned"):
simplefilter("once", warning)
warn(message, warning)
func._warned = True
else:
if not hasattr(func, "_warned_params"):
func._warned_params = set()
if param not in func._warned_params:
simplefilter("once", warning)
warn(message, warning)
func._warned_params.add(param)
def _deprecation_message(name, ver=None, msg=None, append=True):
"""Create a message indicating deprecation."""
if msg and not append:
return msg
if ver:
message = f"{name} has been deprecated since {ver}."
else:
message = f"{name} is deprecated."
if msg:
message += " " + msg
return message
def _warn_deprecated(func, ver=None, msg=None, append=True):
r"""Warn of deprecated status of a function.
Parameters
----------
func : callable
Function that triggers the warning.
ver : str, optional
Version when deprecation became effective.
msg : str, optional
A custom warning message.
append : bool, optional
Append the custom message to the end of the default message (True, default),
or replace the entire default message with the custom message (False).
See Also
--------
_warn_param_deprecated
"""
msg = _deprecation_message(f"`{func.__name__}`", ver, msg, append)
_warn_once(func, DeprecationWarning, msg)
def _warn_param_deprecated(func, param, ver=None, msg=None, append=True):
r"""Warn of deprecated status of a parameter of a function.
Parameters
----------
func : callable
Function that hosts the parameter.
param : str
Parameter that triggers the warning.
ver : str, optional
msg : str, optional
append : bool, optional
Refer to :func:`_warn_deprecated`.
See Also
--------
_warn_deprecated
"""
msg = _deprecation_message(
f"`{func.__name__}`'s parameter `{param}`", ver, msg, append
)
_warn_once(func, DeprecationWarning, msg, param)
def _renaming_message(oldname, newname, ver=None):
"""Create a message indicating renaming."""
if ver:
message = f"{oldname} was renamed to {newname} in {ver}."
else:
message = f"{oldname} has been renamed to {newname}."
message += " The old name is kept as an alias but is deprecated."
return message
def _warn_renamed(func, oldname, ver=None):
"""Warn of renaming status of a function."""
msg = _renaming_message(f"`{oldname}`", f"`{func.__name__}`", ver)
_warn_once(func, DeprecationWarning, msg)
def _warn_param_renamed(func, param, oldname, ver=None):
"""Warn of renaming status of a parameter of a function."""
msg = _renaming_message(
f"`{func.__name__}`'s parameter `{oldname}`", f"`{param}`", ver
)
_warn_once(func, DeprecationWarning, msg, param)
|
