1 """
2 This module contains various Python decorators.
3 """
4
5 __docformat__ = "restructuredtext en"
6
7
8
9
10
11
12
13
14
15 __all__ = ['deprecated', 'abstract']
16
17
18
19
20
21 -def deprecated(since=None, message=None):
22 """
23 Decorator for marking a function deprecated. Generates a warning on
24 standard output if the function is called.
25
26 Usage:
27
28 .. python::
29
30 from grizzled.decorators import deprecated
31
32 class MyClass(object):
33
34 @deprecated()
35 def oldMethod(self):
36 pass
37
38 Given the above declaration, the following code will cause a
39 warning to be printed (though the method call will otherwise succeed):
40
41 .. python::
42
43 obj = MyClass()
44 obj.oldMethod()
45
46 You may also specify a ``since`` argument, used to display a deprecation
47 message with a version stamp (e.g., 'deprecated since ...'):
48
49 .. python::
50
51 from grizzled.decorators import deprecated
52
53 class MyClass(object):
54
55 @deprecated(since='1.2')
56 def oldMethod(self):
57 pass
58
59 :Parameters:
60 since : str
61 version stamp, or ``None`` for none
62 message : str
63 optional additional message to print
64 """
65 def decorator(func):
66 if since is None:
67 buf = 'Method %s is deprecated.' % func.__name__
68 else:
69 buf = 'Method %s has been deprecated since version %s.' %\
70 (func.__name__, since)
71
72 if message:
73 buf += ' ' + message
74
75 def wrapper(*__args, **__kw):
76 import warnings
77 warnings.warn(buf, category=DeprecationWarning, stacklevel=2)
78 return func(*__args,**__kw)
79
80 wrapper.__name__ = func.__name__
81 wrapper.__dict__ = func.__dict__
82 wrapper.__doc__ = func.__doc__
83 return wrapper
84
85 return decorator
86
88 """
89 Decorator for marking a method abstract. Throws a ``NotImplementedError``
90 if an abstract method is called.
91
92 Usage:
93
94 .. python::
95
96 from grizzled.decorators import abstract
97
98 class MyAbstractClass(object):
99
100 @abstract
101 def abstractMethod(self):
102 pass
103
104 class NotReallyConcrete(MyAbstractClass):
105 # Class doesn't define abstractMethod().
106
107 Given the above declaration, the following code will cause an
108 ``NotImplementedError``:
109
110 .. python::
111
112 obj = NotReallyConcrete()
113 obj.abstractMethod()
114 """
115 def wrapper(*__args, **__kw):
116 raise NotImplementedError('Missing required %s() method' %\
117 func.__name__)
118 wrapper.__name__ = func.__name__
119 wrapper.__dict__ = func.__dict__
120 wrapper.__doc__ = func.__doc__
121 return wrapper
122
124 """
125 Decorator for marking a function or method unimplemented. Throws a
126 ``NotImplementedError`` if called. Note that this decorator is
127 conceptually different from ``@abstract``. With ``@abstract``, the method
128 is intended to be implemented by a subclass. With ``@unimplemented``, the
129 method should never be implemented.
130
131 Usage:
132
133 .. python::
134
135 from grizzled.decorators import unimplemented
136
137 class ReadOnlyDict(dict):
138
139 @unimplemented
140 def __setitem__(self, key, value):
141 pass
142 """
143 def wrapper(*__args, **__kw):
144 raise NotImplementedError('Method or function "%s" is not implemented',
145 func.__name__)
146 wrapper.__name__ = func.__name__
147 wrapper.__dict__ = func.__dict__
148 wrapper.__doc__ = func.__doc__
149 return wrapper
150
151
152
153
154
155
156 if __name__ == '__main__':
157 @deprecated()
160
161 @deprecated(since='1.2')
164
165 func1(100)
166 func2()
167
168 - class Foo(object):
172
175
176 b = Bar()
177 try:
178 b.foo()
179 assert False
180 except NotImplementedError, ex:
181 print ex.message
182