docs/documentation/benefits.rst
.. _utilipy-why:
===================
Benefits of utilipy
===================
>>> import utilipy
Decorators
==========
``utilipy``-built decorators are better than normal decorators.
This decorator **does**:
* anything to the function input and output
* make a function that looks exactly like the input function for quality introspection.
* work when created with parenthesis
* accept (kw)arguments on application
* add any extra (kw)arguments to control the `wrapper` also make the defaults be dynamically set on function creation.
* document what the wrapper is doing.
>>> def template_decorator(function=None, *, kw1=None, kw2=None):
... ''''Docstring for decorator.
...
... Description of this decorator
...
... Parameters
... ----------
... function : types.FunctionType or None, optional
... the function to be decoratored
... if None, then returns decorator to apply.
... kw1, kw2 : any, optional
... key-word only arguments
... sets the wrappeer's default values.
...
... Returns
... -------
... wrapper : types.FunctionType
... wrapper for function
... does a few things
... includes the original function in a method `.__wrapped__`
...
... '''
... if function is None: # allowing for optional arguments
... return functools.partial(template_decorator, kw1=k1, kw2=kw2)
...
... @utilipy.wraps(function)
... def wrapper(*args, kw1=kw1, kw2=kw2, kw3='not in decorator factory', **kw):
... """wrapper docstring.
...
... Decorator
... ---------
... prints information about function
... kw1, kw2: defaults {kw1}, {kw2}
...
... """
... # do stuff here
... return_ = function(*args, **kw)
... # and here
... return return_
... # /def
... return wrapper
... # /def