Metadata-Version: 1.1
Name: fqn-decorators
Version: 1.2.3
Summary: Easily create multi-purpose decorators that have access to the FQN of the original function.
Home-page: https://github.com/kpn-digital/py-fqn-decorators
Author: Mattias Sluis
Author-email: mattias.sluis@kpn.com
License: UNKNOWN
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
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Internet :: WWW/HTTP
