← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/symbol_versioning.py

https://launchpad.net/bugs/524184
NEWS section template into a separate file

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/symbol_versioning.py
1
 
# Copyright (C) 2006, 2007, 2008 Canonical Ltd
2
 
#   Authors: Robert Collins <robert.collins@canonical.com> and others
 
1
# Copyright (C) 2006, 2007, 2008, 2009 Canonical Ltd
3
2
#
4
3
# This program is free software; you can redistribute it and/or modify
5
4
# it under the terms of the GNU General Public License as published by
13
12
#
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
17
16
 
18
17
"""Symbol versioning
19
18
 
28
27
           'deprecated_passed',
29
28
           'set_warning_method',
30
29
           'warn',
31
 
           'zero_seven',
32
 
           'zero_eight',
33
 
           'zero_nine',
34
 
           'zero_ten',
35
 
           'zero_eleven',
36
 
           'zero_twelve',
37
 
           'zero_thirteen',
38
 
           'zero_fourteen',
39
 
           'zero_fifteen',
40
 
           'zero_sixteen',
41
 
           'zero_seventeen',
42
 
           'zero_eighteen',
43
 
           'zero_ninety',
44
 
           'zero_ninetyone',
45
 
           'zero_ninetytwo',
46
 
           'zero_ninetythree',
47
 
           'one_zero',
48
 
           'one_one',
49
 
           'one_two',
50
 
           'one_three',
51
 
           'one_four',
52
 
           'one_five',
53
 
           'one_six',
54
30
           ]
55
31
 
56
32
from warnings import warn
59
35
 
60
36
 
61
37
DEPRECATED_PARAMETER = "A deprecated parameter marker."
62
 
zero_seven = "%s was deprecated in version 0.7."
63
 
zero_eight = "%s was deprecated in version 0.8."
64
 
zero_nine = "%s was deprecated in version 0.9."
65
 
zero_ten = "%s was deprecated in version 0.10."
66
 
zero_eleven = "%s was deprecated in version 0.11."
67
 
zero_twelve = "%s was deprecated in version 0.12."
68
 
zero_thirteen = "%s was deprecated in version 0.13."
69
 
zero_fourteen = "%s was deprecated in version 0.14."
70
 
zero_fifteen = "%s was deprecated in version 0.15."
71
 
zero_sixteen = "%s was deprecated in version 0.16."
72
 
zero_seventeen = "%s was deprecated in version 0.17."
73
 
zero_eighteen = "%s was deprecated in version 0.18."
74
 
zero_ninety = "%s was deprecated in version 0.90."
75
 
zero_ninetyone = "%s was deprecated in version 0.91."
76
 
zero_ninetytwo = "%s was deprecated in version 0.92."
77
 
one_zero = "%s was deprecated in version 1.0."
78
 
zero_ninetythree = one_zero # Maintained for backwards compatibility
79
 
one_one = "%s was deprecated in version 1.1."
80
 
one_two = "%s was deprecated in version 1.2."
81
 
one_three = "%s was deprecated in version 1.3."
82
 
one_four = "%s was deprecated in version 1.4."
83
 
one_five = "%s was deprecated in version 1.5."
84
 
one_six = "%s was deprecated in version 1.6."
85
38
 
86
39
 
87
40
def deprecated_in(version_tuple):
88
41
    """Generate a message that something was deprecated in a release.
89
42
 
90
43
    >>> deprecated_in((1, 4, 0))
91
 
    '%s was deprecated in version 1.4.'
 
44
    '%s was deprecated in version 1.4.0.'
92
45
    """
93
46
    return ("%%s was deprecated in version %s."
94
47
            % bzrlib._format_version_tuple(version_tuple))
135
88
 
136
89
    def function_decorator(callable):
137
90
        """This is the function python calls to perform the decoration."""
138
 
        
 
91
 
139
92
        def decorated_function(*args, **kwargs):
140
93
            """This is the decorated function."""
 
94
            from bzrlib import trace
 
95
            trace.mutter_callsite(4, "Deprecated function called")
141
96
            warn(deprecation_string(callable, deprecation_version),
142
97
                DeprecationWarning, stacklevel=2)
143
98
            return callable(*args, **kwargs)
150
105
def deprecated_method(deprecation_version):
151
106
    """Decorate a method so that use of it will trigger a warning.
152
107
 
153
 
    To deprecate a static or class method, use 
 
108
    To deprecate a static or class method, use
154
109
 
155
110
        @staticmethod
156
111
        @deprecated_function
157
112
        def ...
158
 
    
 
113
 
159
114
    To deprecate an entire class, decorate __init__.
160
115
    """
161
116
 
162
117
    def method_decorator(callable):
163
118
        """This is the function python calls to perform the decoration."""
164
 
        
 
119
 
165
120
        def decorated_method(self, *args, **kwargs):
166
121
            """This is the decorated method."""
 
122
            from bzrlib import trace
167
123
            if callable.__name__ == '__init__':
168
124
                symbol = "%s.%s" % (self.__class__.__module__,
169
125
                                    self.__class__.__name__,
173
129
                                       self.__class__.__name__,
174
130
                                       callable.__name__
175
131
                                       )
 
132
            trace.mutter_callsite(4, "Deprecated method called")
176
133
            warn(deprecation_version % symbol, DeprecationWarning, stacklevel=2)
177
134
            return callable(self, *args, **kwargs)
178
135
        _populate_decorated(callable, deprecation_version, "method",
183
140
 
184
141
def deprecated_passed(parameter_value):
185
142
    """Return True if parameter_value was used."""
186
 
    # FIXME: it might be nice to have a parameter deprecation decorator. 
 
143
    # FIXME: it might be nice to have a parameter deprecation decorator.
187
144
    # it would need to handle positional and *args and **kwargs parameters,
188
145
    # which means some mechanism to describe how the parameter was being
189
146
    # passed before deprecation, and some way to deprecate parameters that
209
166
    if len(docstring_lines) == 0:
210
167
        decorated_callable.__doc__ = deprecation_version % ("This " + label)
211
168
    elif len(docstring_lines) == 1:
212
 
        decorated_callable.__doc__ = (callable.__doc__ 
 
169
        decorated_callable.__doc__ = (callable.__doc__
213
170
                                    + "\n"
214
171
                                    + "\n"
215
172
                                    + deprecation_version % ("This " + label)
263
220
            typically from deprecated_in()
264
221
        :param initial_value: The contents of the dict
265
222
        :param variable_name: This allows better warnings to be printed
266
 
        :param advice: String of advice on what callers should do instead 
 
223
        :param advice: String of advice on what callers should do instead
267
224
            of using this variable.
268
225
        """
269
226
        self._deprecation_version = deprecation_version
305
262
        def _warn_deprecated(self, func, *args, **kwargs):
306
263
            warn(msg, DeprecationWarning, stacklevel=3)
307
264
            return func(self, *args, **kwargs)
308
 
            
 
265
 
309
266
        def append(self, obj):
310
267
            """appending to %s is deprecated""" % (variable_name,)
311
268
            return self._warn_deprecated(list.append, obj)
323
280
            return self._warn_deprecated(list.remove, value)
324
281
 
325
282
        def pop(self, index=None):
326
 
            """pop'ing from from %s is deprecated""" % (variable_name,)
 
283
            """pop'ing from %s is deprecated""" % (variable_name,)
327
284
            if index:
328
285
                return self._warn_deprecated(list.pop, index)
329
286
            else:
335
292
 
336
293
def _check_for_filter(error_only):
337
294
    """Check if there is already a filter for deprecation warnings.
338
 
    
 
295
 
339
296
    :param error_only: Only match an 'error' filter
340
297
    :return: True if a filter is found, False otherwise
341
298
    """