13
14
# You should have received a copy of the GNU General Public License
14
15
# along with this program; if not, write to the Free Software
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17
18
"""Symbol versioning
22
23
__all__ = ['deprecated_function',
25
25
'deprecated_method',
26
26
'DEPRECATED_PARAMETER',
27
27
'deprecated_passed',
28
'warn', 'set_warning_method', 'zero_seven',
34
# Import the 'warn' symbol so bzrlib can call it even if we redefine it
35
35
from warnings import warn
40
38
DEPRECATED_PARAMETER = "A deprecated parameter marker."
43
def deprecated_in(version_tuple):
44
"""Generate a message that something was deprecated in a release.
46
>>> deprecated_in((1, 4, 0))
47
'%s was deprecated in version 1.4.0.'
49
return ("%%s was deprecated in version %s."
50
% bzrlib._format_version_tuple(version_tuple))
39
zero_seven = "%s was deprecated in version 0.7."
40
zero_eight = "%s was deprecated in version 0.8."
41
zero_nine = "%s was deprecated in version 0.9."
42
zero_ten = "%s was deprecated in version 0.10."
43
zero_eleven = "%s was deprecated in version 0.11."
53
46
def set_warning_method(method):
64
57
# add that on top of the primitives, once we have all three written
68
def deprecation_string(a_callable, deprecation_version):
69
"""Generate an automatic deprecation string for a_callable.
71
:param a_callable: The callable to substitute into deprecation_version.
72
:param deprecation_version: A deprecation format warning string. This should
73
have a single %s operator in it. a_callable will be turned into a nice
74
python symbol and then substituted into deprecation_version.
76
# We also want to handle old-style classes, in particular exception, and
77
# they don't have an im_class attribute.
78
if getattr(a_callable, 'im_class', None) is None:
79
symbol = "%s.%s" % (a_callable.__module__,
82
symbol = "%s.%s.%s" % (a_callable.im_class.__module__,
83
a_callable.im_class.__name__,
86
return deprecation_version % symbol
89
60
def deprecated_function(deprecation_version):
90
61
"""Decorate a function so that use of it will trigger a warning."""
92
63
def function_decorator(callable):
93
64
"""This is the function python calls to perform the decoration."""
95
66
def decorated_function(*args, **kwargs):
96
67
"""This is the decorated function."""
97
from bzrlib import trace
98
trace.mutter_callsite(4, "Deprecated function called")
99
warn(deprecation_string(callable, deprecation_version),
100
DeprecationWarning, stacklevel=2)
68
symbol = "%s.%s" % (callable.__module__,
71
warn(deprecation_version % symbol, DeprecationWarning, stacklevel=2)
101
72
return callable(*args, **kwargs)
102
73
_populate_decorated(callable, deprecation_version, "function",
103
74
decorated_function)
108
79
def deprecated_method(deprecation_version):
109
80
"""Decorate a method so that use of it will trigger a warning.
111
To deprecate a static or class method, use
117
82
To deprecate an entire class, decorate __init__.
120
85
def method_decorator(callable):
121
86
"""This is the function python calls to perform the decoration."""
123
88
def decorated_method(self, *args, **kwargs):
124
89
"""This is the decorated method."""
125
from bzrlib import trace
126
if callable.__name__ == '__init__':
127
symbol = "%s.%s" % (self.__class__.__module__,
128
self.__class__.__name__,
131
symbol = "%s.%s.%s" % (self.__class__.__module__,
132
self.__class__.__name__,
135
trace.mutter_callsite(4, "Deprecated method called")
90
symbol = "%s.%s.%s" % (self.__class__.__module__,
91
self.__class__.__name__,
136
94
warn(deprecation_version % symbol, DeprecationWarning, stacklevel=2)
137
95
return callable(self, *args, **kwargs)
138
96
_populate_decorated(callable, deprecation_version, "method",
144
102
def deprecated_passed(parameter_value):
145
103
"""Return True if parameter_value was used."""
146
# FIXME: it might be nice to have a parameter deprecation decorator.
104
# FIXME: it might be nice to have a parameter deprecation decorator.
147
105
# it would need to handle positional and *args and **kwargs parameters,
148
106
# which means some mechanism to describe how the parameter was being
149
107
# passed before deprecation, and some way to deprecate parameters that
151
109
# we cannot just forward to a new method name.I.e. in the following
152
110
# examples we would want to have callers that pass any value to 'bad' be
153
111
# given a warning - because we have applied:
154
# @deprecated_parameter('bad', deprecated_in((1, 5, 0))
112
# @deprecated_parameter('bad', zero_seven)
156
114
# def __init__(self, bad=None)
157
115
# def __init__(self, bad, other)
194
152
decorated_callable.is_deprecated = True
197
def _dict_deprecation_wrapper(wrapped_method):
198
"""Returns a closure that emits a warning and calls the superclass"""
199
def cb(dep_dict, *args, **kwargs):
200
msg = 'access to %s' % (dep_dict._variable_name, )
201
msg = dep_dict._deprecation_version % (msg,)
203
msg += ' ' + dep_dict._advice
204
warn(msg, DeprecationWarning, stacklevel=2)
205
return wrapped_method(dep_dict, *args, **kwargs)
209
class DeprecatedDict(dict):
210
"""A dictionary that complains when read or written."""
220
"""Create a dict that warns when read or modified.
222
:param deprecation_version: string for the warning format to raise,
223
typically from deprecated_in()
224
:param initial_value: The contents of the dict
225
:param variable_name: This allows better warnings to be printed
226
:param advice: String of advice on what callers should do instead
227
of using this variable.
229
self._deprecation_version = deprecation_version
230
self._variable_name = variable_name
231
self._advice = advice
232
dict.__init__(self, initial_value)
234
# This isn't every possible method but it should trap anyone using the
235
# dict -- add more if desired
236
__len__ = _dict_deprecation_wrapper(dict.__len__)
237
__getitem__ = _dict_deprecation_wrapper(dict.__getitem__)
238
__setitem__ = _dict_deprecation_wrapper(dict.__setitem__)
239
__delitem__ = _dict_deprecation_wrapper(dict.__delitem__)
240
keys = _dict_deprecation_wrapper(dict.keys)
241
__contains__ = _dict_deprecation_wrapper(dict.__contains__)
244
155
def deprecated_list(deprecation_version, variable_name,
245
156
initial_value, extra=None):
246
157
"""Create a list that warns when modified
248
:param deprecation_version: string for the warning format to raise,
249
typically from deprecated_in()
159
:param deprecation_version: something like zero_nine
250
160
:param initial_value: The contents of the list
251
161
:param variable_name: This allows better warnings to be printed
252
162
:param extra: Extra info to print when printing a warning
265
175
def _warn_deprecated(self, func, *args, **kwargs):
266
176
warn(msg, DeprecationWarning, stacklevel=3)
267
177
return func(self, *args, **kwargs)
269
179
def append(self, obj):
270
180
"""appending to %s is deprecated""" % (variable_name,)
271
181
return self._warn_deprecated(list.append, obj)
291
201
return self._warn_deprecated(list.pop)
293
203
return _DeprecatedList(initial_value)
296
def _check_for_filter(error_only):
297
"""Check if there is already a filter for deprecation warnings.
299
:param error_only: Only match an 'error' filter
300
:return: True if a filter is found, False otherwise
302
for filter in warnings.filters:
303
if issubclass(DeprecationWarning, filter[2]):
304
# This filter will effect DeprecationWarning
305
if not error_only or filter[0] == 'error':
310
def _remove_filter_callable(filter):
311
"""Build and returns a callable removing filter from the warnings.
313
:param filter: The filter to remove (can be None).
315
:return: A callable that will remove filter from warnings.filters.
319
warnings.filters.remove(filter)
323
def suppress_deprecation_warnings(override=True):
324
"""Call this function to suppress all deprecation warnings.
326
When this is a final release version, we don't want to annoy users with
327
lots of deprecation warnings. We only want the deprecation warnings when
328
running a dev or release candidate.
330
:param override: If True, always set the ignore, if False, only set the
331
ignore if there isn't already a filter.
333
:return: A callable to remove the new warnings this added.
335
if not override and _check_for_filter(error_only=False):
336
# If there is already a filter effecting suppress_deprecation_warnings,
340
warnings.filterwarnings('ignore', category=DeprecationWarning)
341
filter = warnings.filters[0]
342
return _remove_filter_callable(filter)
345
def activate_deprecation_warnings(override=True):
346
"""Call this function to activate deprecation warnings.
348
When running in a 'final' release we suppress deprecation warnings.
349
However, the test suite wants to see them. So when running selftest, we
350
re-enable the deprecation warnings.
352
Note: warnings that have already been issued under 'ignore' will not be
353
reported after this point. The 'warnings' module has already marked them as
354
handled, so they don't get issued again.
356
:param override: If False, only add a filter if there isn't an error filter
357
already. (This slightly differs from suppress_deprecation_warnings, in
358
because it always overrides everything but -Werror).
360
:return: A callable to remove the new warnings this added.
362
if not override and _check_for_filter(error_only=True):
363
# DeprecationWarnings are already turned into errors, don't downgrade
367
warnings.filterwarnings('default', category=DeprecationWarning)
368
filter = warnings.filters[0]
369
return _remove_filter_callable(filter)
added
removed
bzrlib/symbol_versioning.py
