1 def simple_decorator(decorator):
   2     '''This decorator can be used to turn simple functions
   3     into well-behaved decorators, so long as the decorators
   4     are fairly simple. If a decorator expects a function and
   5     returns a function (no descriptors), and if it doesn't
   6     modify function attributes or docstring, then it is
   7     eligible to use this. Simply apply @simple_decorator to
   8     your decorator and it will automatically preserve the
   9     docstring and function attributes of functions to which
  10     it is applied.'''
  11     def new_decorator(f):
  12         g = decorator(f)
  13         g.__name__ = f.__name__
  14         g.__doc__ = f.__doc__
  15         g.__dict__.update(f.__dict__)
  16         return g
  17     # Now a few lines needed to make simple_decorator itself
  18     # be a well-behaved decorator.
  19     new_decorator.__name__ = decorator.__name__
  20     new_decorator.__doc__ = decorator.__doc__
  21     new_decorator.__dict__.update(decorator.__dict__)
  22     return new_decorator
  23 
  24 #
  25 # Sample Use:
  26 #
  27 @simple_decorator
  28 def my_simple_logging_decorator(func):
  29     def you_will_never_see_this_name(*args, **kwargs):
  30         print 'calling {}'.format(func.__name__)
  31         return func(*args, **kwargs)
  32     return you_will_never_see_this_name
  33 
  34 @my_simple_logging_decorator
  35 def double(x):
  36     'Doubles a number.'
  37     return 2 * x
  38 
  39 assert double.__name__ == 'double'
  40 assert double.__doc__ == 'Doubles a number.'
  41 print double(155)

   1 import sys
   2 
   3 def propget(func):
   4     locals = sys._getframe(1).f_locals
   5     name = func.__name__
   6     prop = locals.get(name)
   7     if not isinstance(prop, property):
   8         prop = property(func, doc=func.__doc__)
   9     else:
  10         doc = prop.__doc__ or func.__doc__
  11         prop = property(func, prop.fset, prop.fdel, doc)
  12     return prop
  13 
  14 def propset(func):
  15     locals = sys._getframe(1).f_locals
  16     name = func.__name__
  17     prop = locals.get(name)
  18     if not isinstance(prop, property):
  19         prop = property(None, func, doc=func.__doc__)
  20     else:
  21         doc = prop.__doc__ or func.__doc__
  22         prop = property(prop.fget, func, prop.fdel, doc)
  23     return prop
  24 
  25 def propdel(func):
  26     locals = sys._getframe(1).f_locals
  27     name = func.__name__
  28     prop = locals.get(name)
  29     if not isinstance(prop, property):
  30         prop = property(None, None, func, doc=func.__doc__)
  31     else:
  32         prop = property(prop.fget, prop.fset, func, prop.__doc__)
  33     return prop
  34 
  35 # These can be used like this:
  36 
  37 class Example(object):
  38 
  39     @propget
  40     def myattr(self):
  41         return self._half * 2
  42 
  43     @propset
  44     def myattr(self, value):
  45         self._half = value / 2
  46 
  47     @propdel
  48     def myattr(self):
  49         del self._half

   1 class Example(object):
   2     @apply  # doesn't exist in Python 3
   3     def myattr():
   4         doc = '''This is the doc string.'''
   5 
   6         def fget(self):
   7             return self._half * 2
   8 
   9         def fset(self, value):
  10             self._half = value / 2
  11 
  12         def fdel(self):
  13             del self._half
  14 
  15         return property(**locals())
  16     #myattr = myattr()  # works in Python 2 and 3

   1 try:
   2     # Python 2
   3     import __builtin__ as builtins
   4 except ImportError:
   5     # Python 3
   6     import builtins
   7 
   8 def property(function):
   9     keys = 'fget', 'fset', 'fdel'
  10     func_locals = {'doc':function.__doc__}
  11     def probe_func(frame, event, arg):
  12         if event == 'return':
  13             locals = frame.f_locals
  14             func_locals.update(dict((k, locals.get(k)) for k in keys))
  15             sys.settrace(None)
  16         return probe_func
  17     sys.settrace(probe_func)
  18     function()
  19     return builtins.property(**func_locals)
  20 
  21 #====== Example =======================================================
  22 
  23 from math import radians, degrees, pi
  24 
  25 class Angle(object):
  26     def __init__(self, rad):
  27         self._rad = rad
  28 
  29     @property
  30     def rad():
  31         '''The angle in radians'''
  32         def fget(self):
  33             return self._rad
  34         def fset(self, angle):
  35             if isinstance(angle, Angle):
  36                 angle = angle.rad
  37             self._rad = float(angle)
  38 
  39     @property
  40     def deg():
  41         '''The angle in degrees'''
  42         def fget(self):
  43             return degrees(self._rad)
  44         def fset(self, angle):
  45             if isinstance(angle, Angle):
  46                 angle = angle.deg
  47             self._rad = radians(angle)

   1 import collections
   2 import functools
   3 
   4 class memoized(object):
   5    '''Decorator. Caches a function's return value each time it is called.
   6    If called later with the same arguments, the cached value is returned
   7    (not reevaluated).
   8    '''
   9    def __init__(self, func):
  10       self.func = func
  11       self.cache = {}
  12    def __call__(self, *args):
  13       if not isinstance(args, collections.Hashable):
  14          # uncacheable. a list, for instance.
  15          # better to not cache than blow up.
  16          return self.func(*args)
  17       if args in self.cache:
  18          return self.cache[args]
  19       else:
  20          value = self.func(*args)
  21          self.cache[args] = value
  22          return value
  23    def __repr__(self):
  24       '''Return the function's docstring.'''
  25       return self.func.__doc__
  26    def __get__(self, obj, objtype):
  27       '''Support instance methods.'''
  28       return functools.partial(self.__call__, obj)
  29 
  30 @memoized
  31 def fibonacci(n):
  32    "Return the nth fibonacci number."
  33    if n in (0, 1):
  34       return n
  35    return fibonacci(n-1) + fibonacci(n-2)
  36 
  37 print fibonacci(12)

   1 # note that this decorator ignores **kwargs
   2 def memoize(obj):
   3     cache = obj.cache = {}
   4 
   5     @functools.wraps(obj)
   6     def memoizer(*args, **kwargs):
   7         if args not in cache:
   8             cache[args] = obj(*args, **kwargs)
   9         return cache[args]
  10     return memoizer

   1 def memoize(obj):
   2     cache = obj.cache = {}
   3 
   4     @functools.wraps(obj)
   5     def memoizer(*args, **kwargs):
   6         key = str(args) + str(kwargs)
   7         if key not in cache:
   8             cache[key] = obj(*args, **kwargs)
   9         return cache[key]
  10     return memoizer

   1 class memoize(dict):
   2     def __init__(self, func):
   3         self.func = func
   4 
   5     def __call__(self, *args):
   6         return self[args]
   7 
   8     def __missing__(self, key):
   9         result = self[key] = self.func(*key)
  10         return result
  11 
  12 #
  13 # Sample use
  14 #
  15 
  16 >>> @memoize
  17 ... def foo(a, b):
  18 ...     return a * b
  19 >>> foo(2, 4)
  20 8
  21 >>> foo
  22 {(2, 4): 8}
  23 >>> foo('hi', 3)
  24 'hihihi'
  25 >>> foo
  26 {(2, 4): 8, ('hi', 3): 'hihihi'}

   1 import pickle
   2 import collections
   3 import functools
   4 import inspect
   5 import os.path
   6 import re
   7 import unicodedata
   8 
   9 class Memorize(object):
  10     '''
  11     A function decorated with @Memorize caches its return
  12     value every time it is called. If the function is called
  13     later with the same arguments, the cached value is
  14     returned (the function is not reevaluated). The cache is
  15     stored as a .cache file in the current directory for reuse
  16     in future executions. If the Python file containing the
  17     decorated function has been updated since the last run,
  18     the current cache is deleted and a new cache is created
  19     (in case the behavior of the function has changed).
  20     '''
  21     def __init__(self, func):
  22         self.func = func
  23         self.set_parent_file() # Sets self.parent_filepath and self.parent_filename
  24         self.__name__ = self.func.__name__
  25         self.set_cache_filename()
  26         if self.cache_exists():
  27             self.read_cache() # Sets self.timestamp and self.cache
  28             if not self.is_safe_cache():
  29                 self.cache = {}
  30         else:
  31             self.cache = {}
  32 
  33     def __call__(self, *args):
  34         if not isinstance(args, collections.Hashable):
  35             return self.func(*args)
  36         if args in self.cache:
  37             return self.cache[args]
  38         else:
  39             value = self.func(*args)
  40             self.cache[args] = value
  41             self.save_cache()
  42             return value
  43 
  44     def set_parent_file(self):
  45         """
  46         Sets self.parent_file to the absolute path of the
  47         file containing the memoized function.
  48         """
  49         rel_parent_file = inspect.stack()[-1].filename
  50         self.parent_filepath = os.path.abspath(rel_parent_file)
  51         self.parent_filename = _filename_from_path(rel_parent_file)
  52 
  53     def set_cache_filename(self):
  54         """
  55         Sets self.cache_filename to an os-compliant
  56         version of "file_function.cache"
  57         """
  58         filename = _slugify(self.parent_filename.replace('.py', ''))
  59         funcname = _slugify(self.__name__)
  60         self.cache_filename = filename+'_'+funcname+'.cache'
  61 
  62     def get_last_update(self):
  63         """
  64         Returns the time that the parent file was last
  65         updated.
  66         """
  67         last_update = os.path.getmtime(self.parent_filepath)
  68         return last_update
  69 
  70     def is_safe_cache(self):
  71         """
  72         Returns True if the file containing the memoized
  73         function has not been updated since the cache was
  74         last saved.
  75         """
  76         if self.get_last_update() > self.timestamp:
  77             return False
  78         return True
  79 
  80     def read_cache(self):
  81         """
  82         Read a pickled dictionary into self.timestamp and
  83         self.cache. See self.save_cache.
  84         """
  85         with open(self.cache_filename, 'rb') as f:
  86             data = pickle.loads(f.read())
  87             self.timestamp = data['timestamp']
  88             self.cache = data['cache']
  89 
  90     def save_cache(self):
  91         """
  92         Pickle the file's timestamp and the function's cache
  93         in a dictionary object.
  94         """
  95         with open(self.cache_filename, 'wb+') as f:
  96             out = dict()
  97             out['timestamp'] = self.get_last_update()
  98             out['cache'] = self.cache
  99             f.write(pickle.dumps(out))
 100 
 101     def cache_exists(self):
 102         '''
 103         Returns True if a matching cache exists in the current directory.
 104         '''
 105         if os.path.isfile(self.cache_filename):
 106             return True
 107         return False
 108 
 109     def __repr__(self):
 110         """ Return the function's docstring. """
 111         return self.func.__doc__
 112 
 113     def __get__(self, obj, objtype):
 114         """ Support instance methods. """
 115         return functools.partial(self.__call__, obj)
 116 
 117 def _slugify(value):
 118     """
 119     Normalizes string, converts to lowercase, removes
 120     non-alpha characters, and converts spaces to
 121     hyphens. From
 122     http://stackoverflow.com/questions/295135/turn-a-string-into-a-valid-filename-in-python
 123     """
 124     value = unicodedata.normalize('NFKD', value).encode('ascii', 'ignore')
 125     value = re.sub(r'[^\w\s-]', '', value.decode('utf-8', 'ignore'))
 126     value = value.strip().lower()
 127     value = re.sub(r'[-\s]+', '-', value)
 128     return value
 129 
 130 def _filename_from_path(filepath):
 131     return filepath.split('/')[-1]

   1 #
   2 # © 2011 Christopher Arndt, MIT License
   3 #
   4 
   5 import time
   6 
   7 class cached_property(object):
   8     '''Decorator for read-only properties evaluated only once within TTL period.
   9 
  10     It can be used to create a cached property like this::
  11 
  12         import random
  13 
  14         # the class containing the property must be a new-style class
  15         class MyClass(object):
  16             # create property whose value is cached for ten minutes
  17             @cached_property(ttl=600)
  18             def randint(self):
  19                 # will only be evaluated every 10 min. at maximum.
  20                 return random.randint(0, 100)
  21 
  22     The value is cached  in the '_cache' attribute of the object instance that
  23     has the property getter method wrapped by this decorator. The '_cache'
  24     attribute value is a dictionary which has a key for every property of the
  25     object which is wrapped by this decorator. Each entry in the cache is
  26     created only when the property is accessed for the first time and is a
  27     two-element tuple with the last computed property value and the last time
  28     it was updated in seconds since the epoch.
  29 
  30     The default time-to-live (TTL) is 300 seconds (5 minutes). Set the TTL to
  31     zero for the cached value to never expire.
  32 
  33     To expire a cached property value manually just do::
  34 
  35         del instance._cache[<property name>]
  36 
  37     '''
  38     def __init__(self, ttl=300):
  39         self.ttl = ttl
  40 
  41     def __call__(self, fget, doc=None):
  42         self.fget = fget
  43         self.__doc__ = doc or fget.__doc__
  44         self.__name__ = fget.__name__
  45         self.__module__ = fget.__module__
  46         return self
  47 
  48     def __get__(self, inst, owner):
  49         now = time.time()
  50         try:
  51             value, last_update = inst._cache[self.__name__]
  52             if self.ttl > 0 and now - last_update > self.ttl:
  53                 raise AttributeError
  54         except (KeyError, AttributeError):
  55             value = self.fget(inst)
  56             try:
  57                 cache = inst._cache
  58             except AttributeError:
  59                 cache = inst._cache = {}
  60             cache[self.__name__] = (value, now)
  61         return value

   1 import time
   2 import math
   3 
   4 # Retry decorator with exponential backoff
   5 def retry(tries, delay=3, backoff=2):
   6   '''Retries a function or method until it returns True.
   7 
   8   delay sets the initial delay in seconds, and backoff sets the factor by which
   9   the delay should lengthen after each failure. backoff must be greater than 1,
  10   or else it isn't really a backoff. tries must be at least 0, and delay
  11   greater than 0.'''
  12 
  13   if backoff <= 1:
  14     raise ValueError("backoff must be greater than 1")
  15 
  16   tries = math.floor(tries)
  17   if tries < 0:
  18     raise ValueError("tries must be 0 or greater")
  19 
  20   if delay <= 0:
  21     raise ValueError("delay must be greater than 0")
  22 
  23   def deco_retry(f):
  24     def f_retry(*args, **kwargs):
  25       mtries, mdelay = tries, delay # make mutable
  26 
  27       rv = f(*args, **kwargs) # first attempt
  28       while mtries > 0:
  29         if rv is True: # Done on success
  30           return True
  31 
  32         mtries -= 1      # consume an attempt
  33         time.sleep(mdelay) # wait...
  34         mdelay *= backoff  # make future wait longer
  35 
  36         rv = f(*args, **kwargs) # Try again
  37 
  38       return False # Ran out of tries :-(
  39 
  40     return f_retry # true decorator -> decorated function
  41   return deco_retry  # @retry(arg[, ...]) -> true decorator

   1 class curried(object):
   2   '''
   3   Decorator that returns a function that keeps returning functions
   4   until all arguments are supplied; then the original function is
   5   evaluated.
   6   '''
   7 
   8   def __init__(self, func, *a):
   9     self.func = func
  10     self.args = a
  11 
  12   def __call__(self, *a):
  13     args = self.args + a
  14     if len(args) < self.func.func_code.co_argcount:
  15       return curried(self.func, *args)
  16     else:
  17       return self.func(*args)
  18 
  19 
  20 @curried
  21 def add(a, b):
  22     return a + b
  23 
  24 add1 = add(1)
  25 
  26 print add1(2)

   1 import functools, inspect
   2 
   3 def decorator(func):
   4     ''' Allow to use decorator either with arguments or not. '''
   5 
   6     def isFuncArg(*args, **kw):
   7         return len(args) == 1 and len(kw) == 0 and (
   8             inspect.isfunction(args[0]) or isinstance(args[0], type))
   9 
  10     if isinstance(func, type):
  11         def class_wrapper(*args, **kw):
  12             if isFuncArg(*args, **kw):
  13                 return func()(*args, **kw) # create class before usage
  14             return func(*args, **kw)
  15         class_wrapper.__name__ = func.__name__
  16         class_wrapper.__module__ = func.__module__
  17         return class_wrapper
  18 
  19     @functools.wraps(func)
  20     def func_wrapper(*args, **kw):
  21         if isFuncArg(*args, **kw):
  22             return func(*args, **kw)
  23 
  24         def functor(userFunc):
  25             return func(userFunc, *args, **kw)
  26 
  27         return functor
  28 
  29     return func_wrapper

   1 @decorator
   2 def apply(func, *args, **kw):
   3     return func(*args, **kw)
   4 
   5 @decorator
   6 class apply:
   7     def __init__(self, *args, **kw):
   8         self.args = args
   9         self.kw   = kw
  10 
  11     def __call__(self, func):
  12         return func(*self.args, **self.kw)
  13 
  14 #
  15 # Usage in both cases:
  16 #
  17 @apply
  18 def test():
  19     return 'test'
  20 
  21 assert test == 'test'
  22 
  23 @apply(2, 3)
  24 def test(a, b):
  25     return a + b
  26 
  27 assert test is 5

   1 @decorator
   2 def my_property(getter, *, setter=None, deleter=None, doc=None):
   3     return property(getter, setter, deleter, doc)

   1 import sys
   2 
   3 WHAT_TO_DEBUG = set(['io', 'core'])  # change to what you need
   4 
   5 class debug:
   6     '''Decorator which helps to control what aspects of a program to debug
   7     on per-function basis. Aspects are provided as list of arguments.
   8     It DOESN'T slowdown functions which aren't supposed to be debugged.
   9     '''
  10     def __init__(self, aspects=None):
  11         self.aspects = set(aspects)
  12 
  13     def __call__(self, f):
  14         if self.aspects & WHAT_TO_DEBUG:
  15             def newf(*args, **kwds):
  16                 print >> sys.stderr, f.func_name, args, kwds
  17                 f_result = f(*args, **kwds)
  18                 print >> sys.stderr, f.func_name, "returned", f_result
  19                 return f_result
  20             newf.__doc__ = f.__doc__
  21             return newf
  22         else:
  23             return f
  24 
  25 @debug(['io'])
  26 def prn(x):
  27     print x
  28 
  29 @debug(['core'])
  30 def mult(x, y):
  31     return x * y
  32 
  33 prn(mult(2, 2))

   1 class Foo:
   2     def __init__(self):
   3         self.x = 42
   4 
   5 foo = Foo()
   6 
   7 def addto(instance):
   8     def decorator(f):
   9         import types
  10         f = types.MethodType(f, instance, instance.__class__)
  11         setattr(instance, f.func_name, f)
  12         return f
  13     return decorator
  14 
  15 @addto(foo)
  16 def print_x(self):
  17     print self.x
  18 
  19 # foo.print_x() would print "42"

   1 class countcalls(object):
   2    "Decorator that keeps track of the number of times a function is called."
   3 
   4    __instances = {}
   5 
   6    def __init__(self, f):
   7       self.__f = f
   8       self.__numcalls = 0
   9       countcalls.__instances[f] = self
  10 
  11    def __call__(self, *args, **kwargs):
  12       self.__numcalls += 1
  13       return self.__f(*args, **kwargs)
  14 
  15    @staticmethod
  16    def count(f):
  17       "Return the number of times the function f was called."
  18       return countcalls.__instances[f].__numcalls
  19 
  20    @staticmethod
  21    def counts():
  22       "Return a dict of {function: # of calls} for all registered functions."
  23       return dict([(f, countcalls.count(f)) for f in countcalls.__instances])

   1 class countcalls(object):
   2    "Decorator that keeps track of the number of times a function is called."
   3 
   4    __instances = {}
   5 
   6    def __init__(self, f):
   7       self.__f = f
   8       self.__numcalls = 0
   9       countcalls.__instances[f] = self
  10 
  11    def __call__(self, *args, **kwargs):
  12       self.__numcalls += 1
  13       return self.__f(*args, **kwargs)
  14 
  15    def count(self):
  16       "Return the number of times the function f was called."
  17       return countcalls.__instances[self.__f].__numcalls
  18 
  19    @staticmethod
  20    def counts():
  21       "Return a dict of {function: # of calls} for all registered functions."
  22       return dict([(f.__name__, countcalls.__instances[f].__numcalls) for f in countcalls.__instances])
  23 
  24 #example
  25 
  26 @countcalls
  27 def f():
  28    print 'f called'
  29 
  30 @countcalls
  31 def g():
  32    print 'g called'
  33 
  34 f()
  35 f()
  36 f()
  37 print f.count() # prints 3
  38 print countcalls.counts() # same as f.counts() or g.counts()
  39 g()
  40 print g.count() # prints 1

   1 import warnings
   2 
   3 def deprecated(func):
   4     '''This is a decorator which can be used to mark functions
   5     as deprecated. It will result in a warning being emitted
   6     when the function is used.'''
   7     def new_func(*args, **kwargs):
   8         warnings.warn("Call to deprecated function {}.".format(func.__name__),
   9                       category=DeprecationWarning)
  10         return func(*args, **kwargs)
  11     new_func.__name__ = func.__name__
  12     new_func.__doc__ = func.__doc__
  13     new_func.__dict__.update(func.__dict__)
  14     return new_func
  15 
  16 # === Examples of use ===
  17 
  18 @deprecated
  19 def some_old_function(x,y):
  20     return x + y
  21 
  22 class SomeClass:
  23     @deprecated
  24     def some_old_method(self, x,y):
  25         return x + y

   1 import warnings
   2 import functools
   3 
   4 
   5 def deprecated(func):
   6     '''This is a decorator which can be used to mark functions
   7     as deprecated. It will result in a warning being emitted
   8     when the function is used.'''
   9 
  10     @functools.wraps(func)
  11     def new_func(*args, **kwargs):
  12         warnings.warn_explicit(
  13             "Call to deprecated function {}.".format(func.__name__),
  14             category=DeprecationWarning,
  15             filename=func.func_code.co_filename,
  16             lineno=func.func_code.co_firstlineno + 1
  17         )
  18         return func(*args, **kwargs)
  19     return new_func
  20 
  21 
  22 ## Usage examples ##
  23 @deprecated
  24 def my_func():
  25     pass
  26 
  27 @other_decorators_must_be_upper
  28 @deprecated
  29 def my_func():
  30     pass

   1 import warnings
   2 
   3 def ignore_deprecation_warnings(func):
   4     '''This is a decorator which can be used to ignore deprecation warnings
   5     occurring in a function.'''
   6     def new_func(*args, **kwargs):
   7         with warnings.catch_warnings():
   8             warnings.filterwarnings("ignore", category=DeprecationWarning)
   9             return func(*args, **kwargs)
  10     new_func.__name__ = func.__name__
  11     new_func.__doc__ = func.__doc__
  12     new_func.__dict__.update(func.__dict__)
  13     return new_func
  14 
  15 # === Examples of use ===
  16 
  17 @ignore_deprecation_warnings
  18 def some_function_raising_deprecation_warning():
  19     warnings.warn("This is a deprecationg warning.",
  20                   category=DeprecationWarning)
  21 
  22 class SomeClass:
  23     @ignore_deprecation_warnings
  24     def some_method_raising_deprecation_warning():
  25         warnings.warn("This is a deprecationg warning.",
  26                       category=DeprecationWarning)

   1 def unchanged(func):
   2     "This decorator doesn't add any behavior"
   3     return func
   4 
   5 def disabled(func):
   6     "This decorator disables the provided function, and does nothing"
   7     def empty_func(*args,**kargs):
   8         pass
   9     return empty_func
  10 
  11 # define this as equivalent to unchanged, for nice symmetry with disabled
  12 enabled = unchanged
  13 
  14 #
  15 # Sample use
  16 #
  17 
  18 GLOBAL_ENABLE_FLAG = True
  19 
  20 state = enabled if GLOBAL_ENABLE_FLAG else disabled
  21 @state
  22 def special_function_foo():
  23     print "function was enabled"

   1 def dump_args(func):
   2     "This decorator dumps out the arguments passed to a function before calling it"
   3     argnames = func.func_code.co_varnames[:func.func_code.co_argcount]
   4     fname = func.func_name
   5 
   6     def echo_func(*args,**kwargs):
   7         print fname, ":", ', '.join(
   8             '%s=%r' % entry
   9             for entry in zip(argnames,args) + kwargs.items())
  10         return func(*args, **kwargs)
  11 
  12     return echo_func
  13 
  14 @dump_args
  15 def f1(a,b,c):
  16     print a + b + c
  17 
  18 f1(1, 2, 3)

   1 '''
   2 Provide pre-/postconditions as function decorators.
   3 
   4 Example usage:
   5 
   6   >>> def in_ge20(inval):
   7   ...    assert inval >= 20, 'Input value < 20'
   8   ...
   9   >>> def out_lt30(retval, inval):
  10   ...    assert retval < 30, 'Return value >= 30'
  11   ...
  12   >>> @precondition(in_ge20)
  13   ... @postcondition(out_lt30)
  14   ... def inc(value):
  15   ...   return value + 1
  16   ...
  17   >>> inc(5)
  18   Traceback (most recent call last):
  19     ...
  20   AssertionError: Input value < 20
  21   >>> inc(29)
  22   Traceback (most recent call last):
  23     ...
  24   AssertionError: Return value >= 30
  25   >>> inc(20)
  26   21
  27 
  28 You can define as many pre-/postconditions for a function as you
  29 like. It is also possible to specify both types of conditions at once:
  30 
  31   >>> @conditions(in_ge20, out_lt30)
  32   ... def add1(value):
  33   ...   return value + 1
  34   ...
  35   >>> add1(5)
  36   Traceback (most recent call last):
  37     ...
  38   AssertionError: Input value < 20
  39 
  40 An interesting feature is the ability to prevent the creation of
  41 pre-/postconditions at function definition time. This makes it
  42 possible to use conditions for debugging and then switch them off for
  43 distribution.
  44 
  45   >>> debug = False
  46   >>> @precondition(in_ge20, debug)
  47   ... def dec(value):
  48   ...   return value - 1
  49   ...
  50   >>> dec(5)
  51   4
  52 '''
  53 
  54 __all__ = ['precondition', 'postcondition', 'conditions']
  55 
  56 DEFAULT_ON = True
  57 
  58 def precondition(precondition, use_conditions=DEFAULT_ON):
  59     return conditions(precondition, None, use_conditions)
  60 
  61 def postcondition(postcondition, use_conditions=DEFAULT_ON):
  62     return conditions(None, postcondition, use_conditions)
  63 
  64 class conditions(object):
  65     __slots__ = ('__precondition', '__postcondition')
  66 
  67     def __init__(self, pre, post, use_conditions=DEFAULT_ON):
  68         if not use_conditions:
  69             pre, post = None, None
  70 
  71         self.__precondition  = pre
  72         self.__postcondition = post
  73 
  74     def __call__(self, function):
  75         # combine recursive wrappers (@precondition + @postcondition == @conditions)
  76         pres  = set((self.__precondition,))
  77         posts = set((self.__postcondition,))
  78 
  79         # unwrap function, collect distinct pre-/post conditions
  80         while type(function) is FunctionWrapper:
  81             pres.add(function._pre)
  82             posts.add(function._post)
  83             function = function._func
  84 
  85         # filter out None conditions and build pairs of pre- and postconditions
  86         conditions = map(None, filter(None, pres), filter(None, posts))
  87 
  88         # add a wrapper for each pair (note that 'conditions' may be empty)
  89         for pre, post in conditions:
  90             function = FunctionWrapper(pre, post, function)
  91 
  92         return function
  93 
  94 class FunctionWrapper(object):
  95     def __init__(self, precondition, postcondition, function):
  96         self._pre  = precondition
  97         self._post = postcondition
  98         self._func = function
  99 
 100     def __call__(self, *args, **kwargs):
 101         precondition  = self._pre
 102         postcondition = self._post
 103 
 104         if precondition:
 105             precondition(*args, **kwargs)
 106         result = self._func(*args, **kwargs)
 107         if postcondition:
 108             postcondition(result, *args, **kwargs)
 109         return result
 110 
 111 def __test():
 112     import doctest
 113     doctest.testmod()
 114 
 115 if __name__ == "__main__":
 116     __test()