← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/symbol_versioning.py

Fix BzrDir.create_workingtree for NULL_REVISION

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