douglib.decorators

Hello!

Created on Wed Jun 17 13:18:55 2015

@author: dthor

Contains a collection of decorators that I’ve created.

Decorators are supposed to have to following functionality:

The general thought is that a decorated function should act exactly like an undecorated function with respect to calling function properties such as __name__, __doc__, __dict__, etc.

A decorated function, method, or class has additional attributes: __decor__ Decorator name __decordoc__ Decorator docstring

Decorators should act the same way on class methods as they do on functions.

1. decorated_function.__name__ should return the function’s name, not the decorator name.
2. decorated_function.__doc__ should return the function’s docstring, not the decorator docstring
3. decorated_function.__decor__ should return the decorators by name
4. decoracted_function.__decordoc__ should return the decorator docstring

Decorator names should be verbs and past-tense whenever possible:

‘Timed’ not ‘time’ ‘Cached’ not ‘cache’ ‘CountCalls’ not ‘CountCall’ or ‘CallCounting’ ‘Logged’ not ‘logging’ or ‘log’

<decorator> on <function> should make sense: @CountCalls def my_function() —– reads like: “CountCalls on my_function” —–

<function> is <decorator> should make sense: @Timed @Cached def my_function —– reads like: “my_function is Timed and Cached” —–

Decorators should be classes whenever possible, and inherit from the abstract “decorator” class

class douglib.decorators.Cached(func)

Caches a function’s return value each time it is called. If called later with the same arguments, the cached value is returned (not reevaluated).

Taken from https://wiki.python.org/moin/PythonDecoratorLibrary under the name “Memoize”

class douglib.decorators.CountCalls(func)

Decorator. Keeps track of the number of times a function is called.

count()

Return the number of times the function f was called.

static counts()

Return a dict of {function: # of calls} for all registered functions.

class douglib.decorators.Decorator(func, *args)

Abstract Base Class: Decorator This stores the decorator information, such as the name (__decor__) and the docstring (__decordoc__)

__get__(obj, objtype)

Support instance methods.

_set_decor()

Sets the __decor__ attribute to the decorator name

_set_decordoc()

Sets the __decordoc__ attribute to the decorator docscring

_set_doc()

Sets the __doc__ attribute to the funcion’s docstring

class douglib.decorators.Deprecated(func)

Decorator. Prints out a warning that a function is deprecated.

class douglib.decorators.EnterExit(func)

Prints entry and exit from a function

class douglib.decorators.Incomplete(func)

Decorator

Prints out a warning that a function is incomplete - either it’s not yet finished or it needs more bug testing or there are pending feature requests or something else.

douglib.decorators.Memoize

alias of Cached

class douglib.decorators.MinPythonVersion(min_version)

Decorator. Raises an error if the current python version is lower than the minimum python version.

Uses the sys.hexversion for comparison.

Usage: @MinPythonVersion(0x03040000) # Min version 3.4.0 func(a):

return a

class douglib.decorators.OSRestricted(*valid_systems)

Decorator. Restricts the function to only run on the listed operating systems. Returns an error if the OS used is not in the list.

List of Systems: Windows, Java, Linux, MacOS

Usage: @OSRestricted(*systems) @OSRestricted(‘Windows’) # Runs on Windows only @OSRestricted(‘Linux’, ‘MacOS’) # Runs on Linux and Mac only

class douglib.decorators.Obsolete(func)

Decorator. Raises an error when an Obsolete function is called.

class douglib.decorators.Skipped(return_value=None)

Decorator. Skips the decorated function, optionally returning return_value.

Usage: @Skipped() # Skips with no return value @Skipped(return_value) # Skips and returns return_value

douglib.decorators.TimeCached

Decorator

Caches a function’s return value each time it’s called with a timeout on the cached return value. If called later with the same arguements, but within Timeout, the cached value is returned - the function is not reevaluated.

If called more than Timeout seconds later, the stored return value is considered stale and the function is reevaluated.

timeout defaults to 60s

class douglib.decorators.Timed(func)

Decorator. Times a given function execution.

__call__(*args, **kwargs)

Actually call the function

douglib.decorators.Timeout()

Decorator. Aborts a function call if it takes longer than a defined time.

Only works on Linux due to the SIGALRM signal number.

Usage: @Timeout(seconds, [message])

class douglib.decorators.Traced(func)

Decorator. Prints out the called function with arguments.