fqn-decorators 1.2.0

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