Easily create multi-purpose decorators that have access to the FQN of the original function.
Project description
FQN Decorators
==============
.. image:: https://secure.travis-ci.org/kpn-digital/py-fqn-decorators.svg?branch=master
:target: http://travis-ci.org/kpn-digital/py-fqn-decorators?branch=master
.. image:: https://img.shields.io/codecov/c/github/kpn-digital/py-fqn-decorators/master.svg
:target: http://codecov.io/github/kpn-digital/py-fqn-decorators?branch=master
.. image:: https://img.shields.io/pypi/v/fqn-decorators.svg
:target: https://pypi.python.org/pypi/fqn-decorators
.. image:: https://readthedocs.org/projects/fqn-decorators/badge/?version=latest
:target: http://fqn-decorators.readthedocs.org/en/latest/?badge=latest
Installation
------------
.. start_installation
At the command line::
$ pip install fqn-decorators
.. end_installation
Usage
-----
.. start_usage
.. py:currentmodule:: fqn_decorators.decorators
Introduction
------------
By extending the :class:`~Decorator` class you can create simple decorators.
Implement the :meth:`~Decorator.before` and/or :meth:`~Decorator.after` methods to perform actions before or after execution of the decorated item.
The :meth:`~Decorator.before` method can access the arguments of the decorated item by changing the :attr:`~Decorator.args` and :attr:`~Decorator.kwargs` attributes.
The :meth:`~Decorator.after` method can access or change the result using the :attr:`~Decorator.result` attribute.
The :meth:`~Decorator.exception` method can be used for do something with an Exception that has been raised.
In all three methods the :attr:`~Decorator.fqn` and :attr:`~Decorator.func` attributes are available.
Simple decorator
----------------
Create a simple decorator::
import fqn_decorators
import time
class time_it(fqn_decorators.Decorator):
def before(self):
self.start = time.time()
def after(self):
duration = time.time() - self.start
print("{0} took {1} seconds".format(self.fqn, duration))
@time_it
def my_function():
time.sleep(1)
>>>my_function()
__main__.my_function took 1.00293397903 seconds
Decorator with arguments
------------------------
It is also very easy to create a decorator with arguments.
.. note::
It is not possible to create decorators with *non-keyworded* arguments.
To create a decorator that supports non-keyworded arguments see the :ref:`Advanced Usage <usage_advanced_non_keyword_decorators>` section.
Example::
import fqn_decorators
import time
class threshold(fqn_decorators.Decorator):
def before(self):
self.start = time.time()
def after(self):
duration = time.time() - self.start
treshold = self.params.get('threshold')
if threshold and duration > threshold:
raise Exception('Execution took longer than the threshold')
@threshold(threshold=2)
def my_function():
time.sleep(3)
>>> my_function()
Exception: Execution took longer than the threshold
Async Decorator
---------------
There's also support for decorating coroutines (or any awaitable), for Python >=3.5 only.
The implementation is the same as with the sync version, just inherit from
:class:`~fqn_decorators.async.AsyncDecorator` instead.
Example::
import asyncio
import time
from fqn_decorators.async import AsyncDecorator
class time_it_async(AsyncDecorator):
def before(self):
self.start = time.time()
def after(self):
duration = time.time() - self.start
print("{0} took {1} seconds".format(self.fqn, duration))
@time_it_async
async def coro():
await asyncio.sleep(1)
>>> loop = asyncio.get_event_loop()
>>> loop.run_until_complete(coro())
__main__.coro took 1.001493215560913 seconds
.. end_usage
==============
.. image:: https://secure.travis-ci.org/kpn-digital/py-fqn-decorators.svg?branch=master
:target: http://travis-ci.org/kpn-digital/py-fqn-decorators?branch=master
.. image:: https://img.shields.io/codecov/c/github/kpn-digital/py-fqn-decorators/master.svg
:target: http://codecov.io/github/kpn-digital/py-fqn-decorators?branch=master
.. image:: https://img.shields.io/pypi/v/fqn-decorators.svg
:target: https://pypi.python.org/pypi/fqn-decorators
.. image:: https://readthedocs.org/projects/fqn-decorators/badge/?version=latest
:target: http://fqn-decorators.readthedocs.org/en/latest/?badge=latest
Installation
------------
.. start_installation
At the command line::
$ pip install fqn-decorators
.. end_installation
Usage
-----
.. start_usage
.. py:currentmodule:: fqn_decorators.decorators
Introduction
------------
By extending the :class:`~Decorator` class you can create simple decorators.
Implement the :meth:`~Decorator.before` and/or :meth:`~Decorator.after` methods to perform actions before or after execution of the decorated item.
The :meth:`~Decorator.before` method can access the arguments of the decorated item by changing the :attr:`~Decorator.args` and :attr:`~Decorator.kwargs` attributes.
The :meth:`~Decorator.after` method can access or change the result using the :attr:`~Decorator.result` attribute.
The :meth:`~Decorator.exception` method can be used for do something with an Exception that has been raised.
In all three methods the :attr:`~Decorator.fqn` and :attr:`~Decorator.func` attributes are available.
Simple decorator
----------------
Create a simple decorator::
import fqn_decorators
import time
class time_it(fqn_decorators.Decorator):
def before(self):
self.start = time.time()
def after(self):
duration = time.time() - self.start
print("{0} took {1} seconds".format(self.fqn, duration))
@time_it
def my_function():
time.sleep(1)
>>>my_function()
__main__.my_function took 1.00293397903 seconds
Decorator with arguments
------------------------
It is also very easy to create a decorator with arguments.
.. note::
It is not possible to create decorators with *non-keyworded* arguments.
To create a decorator that supports non-keyworded arguments see the :ref:`Advanced Usage <usage_advanced_non_keyword_decorators>` section.
Example::
import fqn_decorators
import time
class threshold(fqn_decorators.Decorator):
def before(self):
self.start = time.time()
def after(self):
duration = time.time() - self.start
treshold = self.params.get('threshold')
if threshold and duration > threshold:
raise Exception('Execution took longer than the threshold')
@threshold(threshold=2)
def my_function():
time.sleep(3)
>>> my_function()
Exception: Execution took longer than the threshold
Async Decorator
---------------
There's also support for decorating coroutines (or any awaitable), for Python >=3.5 only.
The implementation is the same as with the sync version, just inherit from
:class:`~fqn_decorators.async.AsyncDecorator` instead.
Example::
import asyncio
import time
from fqn_decorators.async import AsyncDecorator
class time_it_async(AsyncDecorator):
def before(self):
self.start = time.time()
def after(self):
duration = time.time() - self.start
print("{0} took {1} seconds".format(self.fqn, duration))
@time_it_async
async def coro():
await asyncio.sleep(1)
>>> loop = asyncio.get_event_loop()
>>> loop.run_until_complete(coro())
__main__.coro took 1.001493215560913 seconds
.. end_usage
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
fqn-decorators-1.1.0.tar.gz
(15.8 kB
view hashes)