Package grizzled :: Module decorators
[hide private]
[frames] | no frames]

Source Code for Module grizzled.decorators

  1  """ 
  2  This module contains various Python decorators. 
  3  """ 
  4   
  5  __docformat__ = "restructuredtext en" 
  6   
  7  # --------------------------------------------------------------------------- 
  8  # Imports 
  9  # --------------------------------------------------------------------------- 
 10   
 11  # --------------------------------------------------------------------------- 
 12  # Exports 
 13  # --------------------------------------------------------------------------- 
 14   
 15  __all__ = ['deprecated', 'abstract'] 
16 17 # --------------------------------------------------------------------------- 18 # Decorators 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
87 -def abstract(func):
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
123 -def unimplemented(func):
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 # Main program, for testing 154 # --------------------------------------------------------------------------- 155 156 if __name__ == '__main__': 157 @deprecated()
158 - def func1(a):
159 pass
160 161 @deprecated(since='1.2')
162 - def func2():
163 pass
164 165 func1(100) 166 func2()
167 168 - class Foo(object):
169 @abstract
170 - def foo(self):
171 pass
172
173 - class Bar(Foo):
174 pass
175 176 b = Bar() 177 try: 178 b.foo() 179 assert False 180 except NotImplementedError, ex: 181 print ex.message 182