/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: John Arbash Meinel
  • Date: 2006-07-21 17:52:22 UTC
  • mto: This revision was merged to the branch mainline in revision 1882.
  • Revision ID: john@arbash-meinel.com-20060721175222-bf7499a71473f2f0
Entries in locations.conf should prefer local paths if available (bug #53653)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/symbol_versioning.py
 
1
# Copyright (C) 2006 by Canonical Ltd
 
2
#   Authors: Robert Collins <robert.collins@canonical.com>
 
3
#
 
4
# This program is free software; you can redistribute it and/or modify
 
5
# it under the terms of the GNU General Public License as published by
 
6
# the Free Software Foundation; either version 2 of the License, or
 
7
# (at your option) any later version.
 
8
#
 
9
# This program is distributed in the hope that it will be useful,
 
10
# but WITHOUT ANY WARRANTY; without even the implied warranty of
 
11
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
12
# GNU General Public License for more details.
 
13
#
 
14
# You should have received a copy of the GNU General Public License
 
15
# along with this program; if not, write to the Free Software
 
16
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
17
 
 
18
"""Symbol versioning
 
19
 
 
20
The methods here allow for api symbol versioning.
 
21
"""
 
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
           ]
 
32
 
 
33
from warnings import warn
 
34
 
 
35
 
 
36
DEPRECATED_PARAMETER = "A deprecated parameter marker."
 
37
zero_seven = "%s was deprecated in version 0.7."
 
38
zero_eight = "%s was deprecated in version 0.8."
 
39
zero_nine = "%s was deprecated in version 0.9."
 
40
 
 
41
 
 
42
def set_warning_method(method):
 
43
    """Set the warning method to be used by this module.
 
44
 
 
45
    It should take a message and a warning category as warnings.warn does.
 
46
    """
 
47
    global warn
 
48
    warn = method
 
49
 
 
50
 
 
51
# TODO - maybe this would be easier to use as one 'smart' method that
 
52
# guess if it is a method or a class or an attribute ? If so, we can
 
53
# add that on top of the primitives, once we have all three written
 
54
# - RBC 20050105
 
55
 
 
56
def deprecated_function(deprecation_version):
 
57
    """Decorate a function so that use of it will trigger a warning."""
 
58
 
 
59
    def function_decorator(callable):
 
60
        """This is the function python calls to perform the decoration."""
 
61
        
 
62
        def decorated_function(*args, **kwargs):
 
63
            """This is the decorated function."""
 
64
            symbol = "%s.%s" % (callable.__module__, 
 
65
                                callable.__name__
 
66
                                )
 
67
            warn(deprecation_version % symbol, DeprecationWarning, stacklevel=2)
 
68
            return callable(*args, **kwargs)
 
69
        _populate_decorated(callable, deprecation_version, "function",
 
70
                            decorated_function)
 
71
        return decorated_function
 
72
    return function_decorator
 
73
 
 
74
 
 
75
def deprecated_method(deprecation_version):
 
76
    """Decorate a method so that use of it will trigger a warning.
 
77
    
 
78
    To deprecate an entire class, decorate __init__.
 
79
    """
 
80
 
 
81
    def method_decorator(callable):
 
82
        """This is the function python calls to perform the decoration."""
 
83
        
 
84
        def decorated_method(self, *args, **kwargs):
 
85
            """This is the decorated method."""
 
86
            symbol = "%s.%s.%s" % (self.__class__.__module__, 
 
87
                                   self.__class__.__name__,
 
88
                                   callable.__name__
 
89
                                   )
 
90
            warn(deprecation_version % symbol, DeprecationWarning, stacklevel=2)
 
91
            return callable(self, *args, **kwargs)
 
92
        _populate_decorated(callable, deprecation_version, "method",
 
93
                            decorated_method)
 
94
        return decorated_method
 
95
    return method_decorator
 
96
 
 
97
 
 
98
def deprecated_passed(parameter_value):
 
99
    """Return True if parameter_value was used."""
 
100
    # FIXME: it might be nice to have a parameter deprecation decorator. 
 
101
    # it would need to handle positional and *args and **kwargs parameters,
 
102
    # which means some mechanism to describe how the parameter was being
 
103
    # passed before deprecation, and some way to deprecate parameters that
 
104
    # were not at the end of the arg list. Thats needed for __init__ where
 
105
    # we cannot just forward to a new method name.I.e. in the following
 
106
    # examples we would want to have callers that pass any value to 'bad' be
 
107
    # given a warning - because we have applied:
 
108
    # @deprecated_parameter('bad', zero_seven)
 
109
    #
 
110
    # def __init__(self, bad=None)
 
111
    # def __init__(self, bad, other)
 
112
    # def __init__(self, **kwargs)
 
113
    # RBC 20060116
 
114
    return not parameter_value is DEPRECATED_PARAMETER
 
115
 
 
116
 
 
117
def _decorate_docstring(callable, deprecation_version, label,
 
118
                        decorated_callable):
 
119
    if callable.__doc__:
 
120
        docstring_lines = callable.__doc__.split('\n')
 
121
    else:
 
122
        docstring_lines = []
 
123
    if len(docstring_lines) == 0:
 
124
        decorated_callable.__doc__ = deprecation_version % ("This " + label)
 
125
    elif len(docstring_lines) == 1:
 
126
        decorated_callable.__doc__ = (callable.__doc__ 
 
127
                                    + "\n"
 
128
                                    + "\n"
 
129
                                    + deprecation_version % ("This " + label)
 
130
                                    + "\n")
 
131
    else:
 
132
        spaces = len(docstring_lines[-1])
 
133
        new_doc = callable.__doc__
 
134
        new_doc += "\n" + " " * spaces
 
135
        new_doc += deprecation_version % ("This " + label)
 
136
        new_doc += "\n" + " " * spaces
 
137
        decorated_callable.__doc__ = new_doc
 
138
 
 
139
 
 
140
def _populate_decorated(callable, deprecation_version, label,
 
141
                        decorated_callable):
 
142
    """Populate attributes like __name__ and __doc__ on the decorated callable.
 
143
    """
 
144
    _decorate_docstring(callable, deprecation_version, label,
 
145
                        decorated_callable)
 
146
    decorated_callable.__module__ = callable.__module__
 
147
    decorated_callable.__name__ = callable.__name__
 
148
    decorated_callable.is_deprecated = True
 
149
 
 
150
 
 
151
def deprecated_list(deprecation_version, variable_name,
 
152
                    initial_value, extra=None):
 
153
    """Create a list that warns when modified
 
154
 
 
155
    :param deprecation_version: something like zero_nine
 
156
    :param initial_value: The contents of the list
 
157
    :param variable_name: This allows better warnings to be printed
 
158
    :param extra: Extra info to print when printing a warning
 
159
    """
 
160
 
 
161
    subst_text = 'Modifying %s' % (variable_name,)
 
162
    msg = deprecation_version % (subst_text,)
 
163
    if extra:
 
164
        msg += ' ' + extra
 
165
 
 
166
    class _DeprecatedList(list):
 
167
        __doc__ = list.__doc__ + msg
 
168
 
 
169
        is_deprecated = True
 
170
 
 
171
        def _warn_deprecated(self, func, *args, **kwargs):
 
172
            warn(msg, DeprecationWarning, stacklevel=3)
 
173
            return func(self, *args, **kwargs)
 
174
            
 
175
        def append(self, obj):
 
176
            """appending to %s is deprecated""" % (variable_name,)
 
177
            return self._warn_deprecated(list.append, obj)
 
178
 
 
179
        def insert(self, index, obj):
 
180
            """inserting to %s is deprecated""" % (variable_name,)
 
181
            return self._warn_deprecated(list.insert, index, obj)
 
182
 
 
183
        def extend(self, iterable):
 
184
            """extending %s is deprecated""" % (variable_name,)
 
185
            return self._warn_deprecated(list.extend, iterable)
 
186
 
 
187
        def remove(self, value):
 
188
            """removing from %s is deprecated""" % (variable_name,)
 
189
            return self._warn_deprecated(list.remove, value)
 
190
 
 
191
        def pop(self, index=None):
 
192
            """pop'ing from from %s is deprecated""" % (variable_name,)
 
193
            if index:
 
194
                return self._warn_deprecated(list.pop, index)
 
195
            else:
 
196
                # Can't pass None
 
197
                return self._warn_deprecated(list.pop)
 
198
 
 
199
    return _DeprecatedList(initial_value)