Decorum is a library which aims to make it easier to write flexible and simple decorators:
- use decorators just like you need: don't bother with parentheses, pass options when you need them.
- write decorators just like you think: they get initialized with or without options, they wrap a function, they are callables.
- test decorators: it's really easy, you have no excuse!
In order to write your own decorators, just subclass decorum.Decorum
:
>>> from decorum import Decorum
>>> class empty_decorator(Decorum):
... """Just inherit from Decorum's builtins."""
Of course you will want to customize decorator's behaviour! There are only three methods to be aware of:
init()
setups the decorator itself;wraps()
decorates the function;call()
runs the wrapped function and returns result.
Here is a simple decorator to illustrate Decorum usage:
>>> from __future__ import print_function
>>> class verbose_decorator(Decorum):
... """Print info about decoration process."""
... def init(self, *args, **kwargs):
... print('Initializing decorator with args={} and kwargs={}'
... .format(args, kwargs))
... return super(verbose_decorator, self).init(*args, **kwargs)
...
... def wraps(self, f):
... print('Wrapping function "{}"'.format(f.__name__))
... return super(verbose_decorator, self).wraps(f)
...
... def call(self, *args, **kwargs):
... print('Running wrapped function with args={} and kwargs={}'
... .format(args, kwargs))
... return super(verbose_decorator, self).call(*args, **kwargs)
Then you can use it as any decorator:
>>> @verbose_decorator
... def foo(x):
... print(x)
Initializing decorator with args=() and kwargs={}
Wrapping function "foo"
>>> foo('bar')
Running wrapped function with args=('bar',) and kwargs={}
bar
Note
You can also use decorum.decorator
to turn classes into decorators.
>>> from decorum import decorator
>>> @decorator
... class noop:
... """Override init(), wraps() or call() if you like."""
>>> @noop
... def foo():
... """Do nothing."""
The result is a class that inherits from the original class and Decorum:
>>> isinstance(foo, noop)
True
>>> isinstance(foo, Decorum)
True
Decorum lets you write decorators with and without arguments in a unified way. Then your decorator can be used with or without arguments, called or not, and it will work the same way:
>>> @verbose_decorator
... def foo(x):
... print(x)
Initializing decorator with args=() and kwargs={}
Wrapping function "foo"
Is identical to:
>>> @verbose_decorator()
... def foo(x):
... print(x)
Initializing decorator with args=() and kwargs={}
Wrapping function "foo"
To implement a decorator that accepts a custom options, just change init()
:
>>> class configurable_decorator(Decorum):
... def init(self, custom_option='default', *args, **kwargs):
... print('Initializing decorator with custom_option="{}"'
... .format(custom_option))
... # Remember the option, typically for use in wraps() or call().
... self.custom_option = custom_option
... # Call super().init() with remaining arguments.
... return super(configurable_decorator, self).init(*args, **kwargs)
As we used a keyword argument, it is optional:
>>> @configurable_decorator
... def foo(x):
... print(x)
Initializing decorator with custom_option="default"
>>> foo.custom_option
'default'
And we can pass this option when decorating a function. Either as positional argument...
>>> @configurable_decorator('positional')
... def foo(x):
... print(x)
Initializing decorator with custom_option="positional"
>>> foo.custom_option
'positional'
... or keyword argument:
>>> @configurable_decorator(custom_option='keyword')
... def foo(x):
... print(x)
Initializing decorator with custom_option="keyword"
>>> foo.custom_option
'keyword'
Of course, you cannot pass arguments that are not declared as init()
options:
>>> @configurable_decorator(wrong_option=True) # doctest: +ELLIPSIS
... def foo(x):
... print(x)
Traceback (most recent call last):
...
TypeError: init() got an unexpected keyword argument 'wrong_option'
Note
In most cases, init()
should accept additional arguments and and proxy
them to parent via super(...).init(*args, **kwargs)
. This way, options
of ancestor classes are supported.
As an example, Decorum
base class declares assigned
keyword argument
in init()
(see section wrap function below).
The wraps()
method allows you to handle the decorated function. It receives
the function to decorate as single positional argument, and returns a callable
(typically self
).
In most cases, wraps()
function will return super(..., self).wraps(f)
.
By default, the base Decorum.wraps()
will try to keep assign certain
attributes to the wrapped function for you, namely __doc__
and
__name__
. This feature uses functools.wraps
.
>>> class identity(Decorum):
... """Noop decorator: does nothing!"""
>>> @identity
... def my_function():
... """My function's docstring."""
>>> print(my_function.__name__)
my_function
>>> print(my_function.__doc__)
My function's docstring.
The optional assigned
keyword argument can be used to specify which
attributes of the original function are assigned directly to the matching
attributes on the wrapper function. This defaults to
functools.WRAPPER_ASSIGNMENTS
. You can specify False
or None
to
disable this.
>>> @identity(assigned=None)
... def my_function():
... """My function's docstring."""
>>> print(my_function.__name__)
identity
>>> print(my_function.__doc__)
Noop decorator: does nothing!
Decorum.call()
method receives *args
and **kwargs
as input. It runs
the wrapped function, and returns the result.
Here is a simple decorator that repeats the result of decorated function:
>>> class repeat(Decorum):
... def call(self, *args, **kwargs):
... result = super(repeat, self).call(*args, **kwargs)
... return ' '.join([result] * 2)
>>> @repeat
... def parrot(word):
... return word
>>> parrot('hello')
'hello hello'
Decorum makes it easy to test custom decorators.
Decorators are defined as classes, so you have fine-grained control over what you test. And your tests can focus on what you customized.
Let's check repeat
decorator from the section before. Since we just
overrode call()
, let's focus on it:
>>> decorator = repeat(lambda x: x.upper())
>>> result = decorator.call('input')
>>> assert result == 'INPUT INPUT'
That's quite useful to unit test decorators.
Decorators are instances of Decorum
or subclasses. So you can inspect
decorated functions.
Let's inspect my_function
from the examples above:
>>> assert isinstance(my_function, Decorum)
>>> assert isinstance(my_function, identity)
Decorum has little known limitations:
- your decorator's
init()
cannot receive a single positional argument that is a callable. Decorum will try triggerwraps()
instead ofinit()
in such a case.
Decorum project is free software, published under MIT license.
- PyPI: https://pypi.python.org/pypi/Decorum
- Code repository: https://github.com/zeekay/decorum
- Bugtracker: https://github.com/zeekay/decorum/issues
- Continuous integration: https://travis-ci.org/zeekay/decorum