← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/symbol_versioning.py

[patch] Aaron Bentley: make revert work in a subdirectory.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/symbol_versioning.py
20
20
The methods here allow for api symbol versioning.
21
21
"""
22
22
 
23
 
__all__ = ['deprecated_function',
24
 
           'deprecated_list',
25
 
           'deprecated_method',
26
 
           'DEPRECATED_PARAMETER',
27
 
           'deprecated_passed',
28
 
           'warn', 'set_warning_method', 'zero_seven',
29
 
           'zero_eight',
30
 
           'zero_nine',
31
 
           'zero_ten',
32
 
           ]
 
23
__all__ = ['warn', 'set_warning_method', 'zero_seven']
33
24
 
34
25
from warnings import warn
35
26
 
36
27
 
37
 
DEPRECATED_PARAMETER = "A deprecated parameter marker."
38
28
zero_seven = "%s was deprecated in version 0.7."
39
 
zero_eight = "%s was deprecated in version 0.8."
40
 
zero_nine = "%s was deprecated in version 0.9."
41
 
zero_ten = "%s was deprecated in version 0.10."
42
29
 
43
30
 
44
31
def set_warning_method(method):
66
53
            symbol = "%s.%s" % (callable.__module__, 
67
54
                                callable.__name__
68
55
                                )
69
 
            warn(deprecation_version % symbol, DeprecationWarning, stacklevel=2)
 
56
            warn(deprecation_version % symbol, DeprecationWarning)
70
57
            return callable(*args, **kwargs)
71
58
        _populate_decorated(callable, deprecation_version, "function",
72
59
                            decorated_function)
89
76
                                   self.__class__.__name__,
90
77
                                   callable.__name__
91
78
                                   )
92
 
            warn(deprecation_version % symbol, DeprecationWarning, stacklevel=2)
 
79
            warn(deprecation_version % symbol, DeprecationWarning)
93
80
            return callable(self, *args, **kwargs)
94
81
        _populate_decorated(callable, deprecation_version, "method",
95
82
                            decorated_method)
97
84
    return method_decorator
98
85
 
99
86
 
100
 
def deprecated_passed(parameter_value):
101
 
    """Return True if parameter_value was used."""
102
 
    # FIXME: it might be nice to have a parameter deprecation decorator. 
103
 
    # it would need to handle positional and *args and **kwargs parameters,
104
 
    # which means some mechanism to describe how the parameter was being
105
 
    # passed before deprecation, and some way to deprecate parameters that
106
 
    # were not at the end of the arg list. Thats needed for __init__ where
107
 
    # we cannot just forward to a new method name.I.e. in the following
108
 
    # examples we would want to have callers that pass any value to 'bad' be
109
 
    # given a warning - because we have applied:
110
 
    # @deprecated_parameter('bad', zero_seven)
111
 
    #
112
 
    # def __init__(self, bad=None)
113
 
    # def __init__(self, bad, other)
114
 
    # def __init__(self, **kwargs)
115
 
    # RBC 20060116
116
 
    return not parameter_value is DEPRECATED_PARAMETER
117
 
 
118
 
 
119
87
def _decorate_docstring(callable, deprecation_version, label,
120
88
                        decorated_callable):
121
 
    if callable.__doc__:
122
 
        docstring_lines = callable.__doc__.split('\n')
123
 
    else:
124
 
        docstring_lines = []
 
89
    docstring_lines = callable.__doc__.split('\n')
125
90
    if len(docstring_lines) == 0:
126
91
        decorated_callable.__doc__ = deprecation_version % ("This " + label)
127
92
    elif len(docstring_lines) == 1:
147
112
                        decorated_callable)
148
113
    decorated_callable.__module__ = callable.__module__
149
114
    decorated_callable.__name__ = callable.__name__
150
 
    decorated_callable.is_deprecated = True
151
 
 
152
 
 
153
 
def deprecated_list(deprecation_version, variable_name,
154
 
                    initial_value, extra=None):
155
 
    """Create a list that warns when modified
156
 
 
157
 
    :param deprecation_version: something like zero_nine
158
 
    :param initial_value: The contents of the list
159
 
    :param variable_name: This allows better warnings to be printed
160
 
    :param extra: Extra info to print when printing a warning
161
 
    """
162
 
 
163
 
    subst_text = 'Modifying %s' % (variable_name,)
164
 
    msg = deprecation_version % (subst_text,)
165
 
    if extra:
166
 
        msg += ' ' + extra
167
 
 
168
 
    class _DeprecatedList(list):
169
 
        __doc__ = list.__doc__ + msg
170
 
 
171
 
        is_deprecated = True
172
 
 
173
 
        def _warn_deprecated(self, func, *args, **kwargs):
174
 
            warn(msg, DeprecationWarning, stacklevel=3)
175
 
            return func(self, *args, **kwargs)
176
 
            
177
 
        def append(self, obj):
178
 
            """appending to %s is deprecated""" % (variable_name,)
179
 
            return self._warn_deprecated(list.append, obj)
180
 
 
181
 
        def insert(self, index, obj):
182
 
            """inserting to %s is deprecated""" % (variable_name,)
183
 
            return self._warn_deprecated(list.insert, index, obj)
184
 
 
185
 
        def extend(self, iterable):
186
 
            """extending %s is deprecated""" % (variable_name,)
187
 
            return self._warn_deprecated(list.extend, iterable)
188
 
 
189
 
        def remove(self, value):
190
 
            """removing from %s is deprecated""" % (variable_name,)
191
 
            return self._warn_deprecated(list.remove, value)
192
 
 
193
 
        def pop(self, index=None):
194
 
            """pop'ing from from %s is deprecated""" % (variable_name,)
195
 
            if index:
196
 
                return self._warn_deprecated(list.pop, index)
197
 
            else:
198
 
                # Can't pass None
199
 
                return self._warn_deprecated(list.pop)
200
 
 
201
 
    return _DeprecatedList(initial_value)