1
# Copyright (C) 2006-2010 Canonical Ltd
3
# This program is free software; you can redistribute it and/or modify
4
# it under the terms of the GNU General Public License as published by
5
# the Free Software Foundation; either version 2 of the License, or
6
# (at your option) any later version.
8
# This program is distributed in the hope that it will be useful,
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
# GNU General Public License for more details.
13
# You should have received a copy of the GNU General Public License
14
# along with this program; if not, write to the Free Software
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19
The methods here allow for api symbol versioning.
22
__all__ = ['deprecated_function',
26
'DEPRECATED_PARAMETER',
34
# Import the 'warn' symbol so bzrlib can call it even if we redefine it
35
from warnings import warn
40
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))
53
def set_warning_method(method):
54
"""Set the warning method to be used by this module.
56
It should take a message and a warning category as warnings.warn does.
62
# TODO - maybe this would be easier to use as one 'smart' method that
63
# guess if it is a method or a class or an attribute ? If so, we can
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
89
def deprecated_function(deprecation_version):
90
"""Decorate a function so that use of it will trigger a warning."""
92
def function_decorator(callable):
93
"""This is the function python calls to perform the decoration."""
95
def decorated_function(*args, **kwargs):
96
"""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)
101
return callable(*args, **kwargs)
102
_populate_decorated(callable, deprecation_version, "function",
104
return decorated_function
105
return function_decorator
108
def deprecated_method(deprecation_version):
109
"""Decorate a method so that use of it will trigger a warning.
111
To deprecate a static or class method, use
117
To deprecate an entire class, decorate __init__.
120
def method_decorator(callable):
121
"""This is the function python calls to perform the decoration."""
123
def decorated_method(self, *args, **kwargs):
124
"""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")
136
warn(deprecation_version % symbol, DeprecationWarning, stacklevel=2)
137
return callable(self, *args, **kwargs)
138
_populate_decorated(callable, deprecation_version, "method",
140
return decorated_method
141
return method_decorator
144
def deprecated_passed(parameter_value):
145
"""Return True if parameter_value was used."""
146
# FIXME: it might be nice to have a parameter deprecation decorator.
147
# it would need to handle positional and *args and **kwargs parameters,
148
# which means some mechanism to describe how the parameter was being
149
# passed before deprecation, and some way to deprecate parameters that
150
# were not at the end of the arg list. Thats needed for __init__ where
151
# we cannot just forward to a new method name.I.e. in the following
152
# examples we would want to have callers that pass any value to 'bad' be
153
# given a warning - because we have applied:
154
# @deprecated_parameter('bad', deprecated_in((1, 5, 0))
156
# def __init__(self, bad=None)
157
# def __init__(self, bad, other)
158
# def __init__(self, **kwargs)
160
return not parameter_value is DEPRECATED_PARAMETER
163
def _decorate_docstring(callable, deprecation_version, label,
166
docstring_lines = callable.__doc__.split('\n')
169
if len(docstring_lines) == 0:
170
decorated_callable.__doc__ = deprecation_version % ("This " + label)
171
elif len(docstring_lines) == 1:
172
decorated_callable.__doc__ = (callable.__doc__
175
+ deprecation_version % ("This " + label)
178
spaces = len(docstring_lines[-1])
179
new_doc = callable.__doc__
180
new_doc += "\n" + " " * spaces
181
new_doc += deprecation_version % ("This " + label)
182
new_doc += "\n" + " " * spaces
183
decorated_callable.__doc__ = new_doc
186
def _populate_decorated(callable, deprecation_version, label,
188
"""Populate attributes like __name__ and __doc__ on the decorated callable.
190
_decorate_docstring(callable, deprecation_version, label,
192
decorated_callable.__module__ = callable.__module__
193
decorated_callable.__name__ = callable.__name__
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__)
244
def deprecated_list(deprecation_version, variable_name,
245
initial_value, extra=None):
246
"""Create a list that warns when modified
248
:param deprecation_version: string for the warning format to raise,
249
typically from deprecated_in()
250
:param initial_value: The contents of the list
251
:param variable_name: This allows better warnings to be printed
252
:param extra: Extra info to print when printing a warning
255
subst_text = 'Modifying %s' % (variable_name,)
256
msg = deprecation_version % (subst_text,)
260
class _DeprecatedList(list):
261
__doc__ = list.__doc__ + msg
265
def _warn_deprecated(self, func, *args, **kwargs):
266
warn(msg, DeprecationWarning, stacklevel=3)
267
return func(self, *args, **kwargs)
269
def append(self, obj):
270
"""appending to %s is deprecated""" % (variable_name,)
271
return self._warn_deprecated(list.append, obj)
273
def insert(self, index, obj):
274
"""inserting to %s is deprecated""" % (variable_name,)
275
return self._warn_deprecated(list.insert, index, obj)
277
def extend(self, iterable):
278
"""extending %s is deprecated""" % (variable_name,)
279
return self._warn_deprecated(list.extend, iterable)
281
def remove(self, value):
282
"""removing from %s is deprecated""" % (variable_name,)
283
return self._warn_deprecated(list.remove, value)
285
def pop(self, index=None):
286
"""pop'ing from %s is deprecated""" % (variable_name,)
288
return self._warn_deprecated(list.pop, index)
291
return self._warn_deprecated(list.pop)
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
