Decorators

Use these decorators to automatically analyse functions arguments passed to functions.

hoft.core.decorators.analyse_sig(*parse_args, **parse_kwargs)

Decorator for methods (to analyse) the args and kwargs of the decorated callable. This method does not modify the args or kwargs in any way.

Preferred method over analyse_in.

Parameters:

• parse_args – A list of callables which accept two values only: These callables will be passed the target function’s argument at the same position as - the callable is in the decorator’s arguments list and the index of the argument. If callable==`IGNORE`, then the decorated function’s arg is not parsed.
• parse_kwargs – A dictionary of name, callables. The name represents the target function’s kwarg that will be passed to the callable. The callable receives the name, value and a boolean representing if the name is present in the kwargs: ie: def my_func(name, value, name_in_decorated_funcs_passed_kwargs).
• parse_kwargs['_fail_fast_'] (bool) – True: Fail on the first exception raised by any supplied callable.
• parse_kwargs['_on_error_'] (bool) – Callable or type to be called when an exception is found in a supplied callable, if the type is an exception or subclass-of, it will be raised (the exception constructor should take the same signature as my_func below): ie: def my_func(exc, list_of_excs). If the type is not an exception or subclass-of it will be called, it is up to this callable to raise an exception if required.
• parse_kwargs['_strict_'] (bool) – True=Error if all params are not analysed.
• parse_kwargs['_default_'] (callable) – Default handler for all not previously analysed arguments.

Returns:

Decorated function.

Note:

Any exception raised by a supplied callable will have an additional field: _errors_. This is always a list of one or all of the errors encountered during the supplied callables (depending on the value of the _fail_fast_ kwargs).

Example:

>>> @hoft.analyse_sig(
    _a_func(z=1), None, bar=_b_func(x=1, y=2), baz=_validate_baz(), x=None,
    _fail_fast_=True, _on_error_=my_func, _strict_=False, _default_=_default_func,
)
def _validate_something_decorated(foo, ignored, bar=hoft.IGNORE, baz=None, x=None):
    ...

hoft.core.decorators.analyse_in(*parse_args, **parse_kwargs)

Decorator for methods (to analyse) the args and kwargs of the decorated callable. This method does not modify the args or kwargs in any way.

Deprecated. Will be removed in a future version, use analyse_sig instead.

Parameters:

• parse_args – A list of callables which accept two values only: These callables will be passed the target function’s argument at the same position as - the callable is in the decorator’s arguments list and the index of the argument. If callable==`IGNORE`, then the decorated function’s arg is not parsed.
• parse_kwargs – A dictionary of name, callables. The name represents the target function’s kwarg that will be passed to the callable. The callable receives the name, value and a boolean representing if the name is present in the kwargs: ie: def my_func(name, value, name_in_decorated_funcs_passed_kwargs).
• parse_kwargs['_fail_fast_'] (bool) – True: Fail on the first exception raised by any supplied callable.
• parse_kwargs['_on_error_'] (bool) – Callable or type to be called when an exception is found in a supplied callable, if the type is an exception or subclass-of, it will be raised (the exception constructor should take the same signature as my_func below): ie: def my_func(exc, list_of_excs). If the type is not an exception or subclass-of it will be called, it is up to this callable to raise an exception if required.

Returns:

Decorated function.

Note:

Any exception raised by a supplied callable will have an additional field: _errors_. This is always a list of one or all of the errors encountered during the supplied callables (depending on the value of the _fail_fast_ kwargs).

Example:

>>> @hoft.analyse_in(
    _a_func(z=1), None, bar=_b_func(x=1, y=2), baz=_validate_baz(), x=None,
    _fail_fast_=True, _on_error_=my_func,
)
def _validate_something_decorated(foo, ignored, bar=hoft.IGNORE, baz=None, x=None):
    ...