14
13
# You should have received a copy of the GNU General Public License
15
14
# along with this program; if not, write to the Free Software
16
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18
17
"""Symbol versioning
23
22
__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
33
35
from warnings import warn
36
40
DEPRECATED_PARAMETER = "A deprecated parameter marker."
37
zero_seven = "%s was deprecated in version 0.7."
38
zero_eight = "%s was deprecated in version 0.8."
39
zero_nine = "%s was deprecated in version 0.9."
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))
42
53
def set_warning_method(method):
53
64
# 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
56
89
def deprecated_function(deprecation_version):
57
90
"""Decorate a function so that use of it will trigger a warning."""
59
92
def function_decorator(callable):
60
93
"""This is the function python calls to perform the decoration."""
62
95
def decorated_function(*args, **kwargs):
63
96
"""This is the decorated function."""
64
symbol = "%s.%s" % (callable.__module__,
67
warn(deprecation_version % symbol, DeprecationWarning, stacklevel=2)
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
101
return callable(*args, **kwargs)
69
102
_populate_decorated(callable, deprecation_version, "function",
70
103
decorated_function)
75
108
def deprecated_method(deprecation_version):
76
109
"""Decorate a method so that use of it will trigger a warning.
111
To deprecate a static or class method, use
78
117
To deprecate an entire class, decorate __init__.
81
120
def method_decorator(callable):
82
121
"""This is the function python calls to perform the decoration."""
84
123
def decorated_method(self, *args, **kwargs):
85
124
"""This is the decorated method."""
86
symbol = "%s.%s.%s" % (self.__class__.__module__,
87
self.__class__.__name__,
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
136
warn(deprecation_version % symbol, DeprecationWarning, stacklevel=2)
91
137
return callable(self, *args, **kwargs)
92
138
_populate_decorated(callable, deprecation_version, "method",
98
144
def deprecated_passed(parameter_value):
99
145
"""Return True if parameter_value was used."""
100
# FIXME: it might be nice to have a parameter deprecation decorator.
146
# FIXME: it might be nice to have a parameter deprecation decorator.
101
147
# it would need to handle positional and *args and **kwargs parameters,
102
148
# which means some mechanism to describe how the parameter was being
103
149
# passed before deprecation, and some way to deprecate parameters that
105
151
# we cannot just forward to a new method name.I.e. in the following
106
152
# examples we would want to have callers that pass any value to 'bad' be
107
153
# given a warning - because we have applied:
108
# @deprecated_parameter('bad', zero_seven)
154
# @deprecated_parameter('bad', deprecated_in((1, 5, 0))
110
156
# def __init__(self, bad=None)
111
157
# def __init__(self, bad, other)
148
194
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__)
151
244
def deprecated_list(deprecation_version, variable_name,
152
245
initial_value, extra=None):
153
246
"""Create a list that warns when modified
155
:param deprecation_version: something like zero_nine
248
:param deprecation_version: string for the warning format to raise,
249
typically from deprecated_in()
156
250
:param initial_value: The contents of the list
157
251
:param variable_name: This allows better warnings to be printed
158
252
:param extra: Extra info to print when printing a warning
171
265
def _warn_deprecated(self, func, *args, **kwargs):
172
266
warn(msg, DeprecationWarning, stacklevel=3)
173
267
return func(self, *args, **kwargs)
175
269
def append(self, obj):
176
270
"""appending to %s is deprecated""" % (variable_name,)
177
271
return self._warn_deprecated(list.append, obj)
197
291
return self._warn_deprecated(list.pop)
199
293
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
