/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to bzrlib/symbol_versioning.py

  • Committer: Andrew Bennetts
  • Date: 2008-08-12 14:53:26 UTC
  • mto: This revision was merged to the branch mainline in revision 3624.
  • Revision ID: andrew.bennetts@canonical.com-20080812145326-yx693x2jc4rcovb7
Move the notes on writing tests out of HACKING into a new file, and improve
them.

Many of the testing notes in the HACKING file were in duplicated in two places
in that file!  This change removes that duplication.  It also adds new sections
on “Where should I put a new test?” and “TestCase and its subclasses”, and
others like “Test feature dependencies” have been expanded.  The whole document
has generally been edited to be a bit more coherent. 

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/symbol_versioning.py
1
 
# Copyright (C) 2006, 2007, 2008, 2009 Canonical Ltd
 
1
# Copyright (C) 2006, 2007, 2008 Canonical Ltd
 
2
#   Authors: Robert Collins <robert.collins@canonical.com> and others
2
3
#
3
4
# This program is free software; you can redistribute it and/or modify
4
5
# it under the terms of the GNU General Public License as published by
12
13
#
13
14
# You should have received a copy of the GNU General Public License
14
15
# along with this program; if not, write to the Free Software
15
 
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
16
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
17
 
17
18
"""Symbol versioning
18
19
 
27
28
           'deprecated_passed',
28
29
           'set_warning_method',
29
30
           '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',
30
54
           ]
31
55
 
32
56
from warnings import warn
35
59
 
36
60
 
37
61
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."
38
85
 
39
86
 
40
87
def deprecated_in(version_tuple):
41
88
    """Generate a message that something was deprecated in a release.
42
89
 
43
90
    >>> deprecated_in((1, 4, 0))
44
 
    '%s was deprecated in version 1.4.0.'
 
91
    '%s was deprecated in version 1.4.'
45
92
    """
46
93
    return ("%%s was deprecated in version %s."
47
94
            % bzrlib._format_version_tuple(version_tuple))
88
135
 
89
136
    def function_decorator(callable):
90
137
        """This is the function python calls to perform the decoration."""
91
 
 
 
138
        
92
139
        def decorated_function(*args, **kwargs):
93
140
            """This is the decorated function."""
94
141
            from bzrlib import trace
105
152
def deprecated_method(deprecation_version):
106
153
    """Decorate a method so that use of it will trigger a warning.
107
154
 
108
 
    To deprecate a static or class method, use
 
155
    To deprecate a static or class method, use 
109
156
 
110
157
        @staticmethod
111
158
        @deprecated_function
112
159
        def ...
113
 
 
 
160
    
114
161
    To deprecate an entire class, decorate __init__.
115
162
    """
116
163
 
117
164
    def method_decorator(callable):
118
165
        """This is the function python calls to perform the decoration."""
119
 
 
 
166
        
120
167
        def decorated_method(self, *args, **kwargs):
121
168
            """This is the decorated method."""
122
169
            from bzrlib import trace
140
187
 
141
188
def deprecated_passed(parameter_value):
142
189
    """Return True if parameter_value was used."""
143
 
    # FIXME: it might be nice to have a parameter deprecation decorator.
 
190
    # FIXME: it might be nice to have a parameter deprecation decorator. 
144
191
    # it would need to handle positional and *args and **kwargs parameters,
145
192
    # which means some mechanism to describe how the parameter was being
146
193
    # passed before deprecation, and some way to deprecate parameters that
166
213
    if len(docstring_lines) == 0:
167
214
        decorated_callable.__doc__ = deprecation_version % ("This " + label)
168
215
    elif len(docstring_lines) == 1:
169
 
        decorated_callable.__doc__ = (callable.__doc__
 
216
        decorated_callable.__doc__ = (callable.__doc__ 
170
217
                                    + "\n"
171
218
                                    + "\n"
172
219
                                    + deprecation_version % ("This " + label)
220
267
            typically from deprecated_in()
221
268
        :param initial_value: The contents of the dict
222
269
        :param variable_name: This allows better warnings to be printed
223
 
        :param advice: String of advice on what callers should do instead
 
270
        :param advice: String of advice on what callers should do instead 
224
271
            of using this variable.
225
272
        """
226
273
        self._deprecation_version = deprecation_version
262
309
        def _warn_deprecated(self, func, *args, **kwargs):
263
310
            warn(msg, DeprecationWarning, stacklevel=3)
264
311
            return func(self, *args, **kwargs)
265
 
 
 
312
            
266
313
        def append(self, obj):
267
314
            """appending to %s is deprecated""" % (variable_name,)
268
315
            return self._warn_deprecated(list.append, obj)
280
327
            return self._warn_deprecated(list.remove, value)
281
328
 
282
329
        def pop(self, index=None):
283
 
            """pop'ing from %s is deprecated""" % (variable_name,)
 
330
            """pop'ing from from %s is deprecated""" % (variable_name,)
284
331
            if index:
285
332
                return self._warn_deprecated(list.pop, index)
286
333
            else:
292
339
 
293
340
def _check_for_filter(error_only):
294
341
    """Check if there is already a filter for deprecation warnings.
295
 
 
 
342
    
296
343
    :param error_only: Only match an 'error' filter
297
344
    :return: True if a filter is found, False otherwise
298
345
    """