==========
decorators
==========

decorators provides all purpose decorators for QA.


log_time
========

This decorator takes 3 optional parameters:

- `treshold`: if given, will log functions which execution time is greater
  than the value. By default equals to 0.

- `logger`: if given, must be a callable that receives the message to log.
  By default equals to logging.info().

- `formatter`: if given, must be a callable that returns a formatted string
  to log. The formatter makes a default format otherwise. The callable
  receives 4 parameters:

  - total: execution time
  - function: function called
  - args: function arguments
  - kw: function named arguments

Examples of use ::

    >>> import time
    >>> from decorators import log_time
    >>> def info(msg):
    ...     print msg

Custom treshold and logger::

    >>> @log_time(treshold=0.1, logger=info)
    ... def func(param1, param2=2):
    ...     time.sleep(0.2)
    ...
    >>> func(1)
    log_time::...::0.200::function 'func', args: (1,), kw: {}

Just a custom logger::

    >>> @log_time(logger=info)
    ... def func(param1, param2=2):
    ...     time.sleep(0.2)
    ...
    >>> func(1)
    log_time::...::0.200::function 'func', args: (1,), kw: {}

    >>> @log_time()
    ... def func(param1, param2=2):
    ...     time.sleep(0.2)
    ...
    >>> func(1)

A custom formatter ::

    >>> def fm(total, func, args, kw):
    ...     return '%.2f ms for %s()' % (total, func.func_name)
    ...
    >>> @log_time(logger=info, formatter=fm)
    ... def func(param1, param2=2):
    ...     time.sleep(0.2)
    ...
    >>> func(1)
    0.20 ms for func()

Used over a class::

    >>> class MyClass(object):
    ...
    ...     @log_time(logger=info)
    ...     def go(self):
    ...         time.sleep(0.2)
    ...
    >>> my_instance = MyClass()
    >>> my_instance.go()
    log_time::...::0.200::function 'go', args: (<....MyClass object at 0x...>,), kw: {}


