API

This document brings the public API of bender-hooks.

exception bender_hooks.HookError

Error raised for expected and known cases of bender-hooks.

bender_hooks.call(hook, **kwargs)

Responsible for invoking given hook. As hooks not necessarily defines all arguments, this function will make sure that the given one will satisfy the hook. Example:

def foo(a, b):
    """
    My decorator definition.
    """

# Creating decorator.
dec = bender_hooks.make_decorator(foo)

# Decorating. Only one parameter defined.
@foo
def bar(b):
    print(b)

# Invoking.
bender_hooks.call(bar, a=1) # Invalid: ``a`` is not defined at ``bar``
bender_hooks.call(bar, b=2) # Valid
bender_hooks.call(bar, c=3) # Invalid: ``c`` is not defined at ``bar`` neither ``foo``
bender_hooks.call(bar, a=1, b=2) # Valid: ``a`` is defined at ``foo`` but will be ignored.
bender_hooks.call(bar, b=2, c=3) # Invalid
bender_hooks.call(bar, a=1, b=2, c=3) # Invalid

Parameters:hook (callable) – Already decorated function. Returns:It depends on what will be returned by given hook. Raises HookError:  if given hook is not decorated.

bender_hooks.call_all_hooks(obj, hook_name, **kwargs)

Responsible for search and invoke all hooks with the given hook_name under obj.

See also

find_hooks()

See also

call()

bender_hooks.call_unique_hook(obj, hook_name, **kwargs)

Responsible for search and invoke a hook with the given hook_name under obj, making sure that only one hook exists.

Raises HookError:  if more than one hooks are found.

See also

find_hooks()

See also

call()

bender_hooks.find_hooks(obj, hook_name)

Responsible for search at obj hooks with the given hook_name.

Parameters:

• obj – Object (can be a module or instance) to search for hooks.
• hook_name (unicode) – Name of hook to search.

Return type:

list(callable)

Returns:

All hooks found into the given obj.

bender_hooks.make_decorator(hook_decl, inputs=())

Responsible for turning a hook declaration into a decorator.

Parameters:

• hook_decl (callable) –

  The definition that will be turn into a decorator. Example:

  def grettings(greet, name):
      """
      Called in scripts that want to print greetings.
  
      :param greet: unicode
      :param name: unicode
      """
  

  If any code is placed inside the given definition it will be ignored.

• inputs (tuple | list) –

  Parameters that must be given to decorator. Example:

  dec = bender_hooks.make_decorator(foo, inputs=('alpha', 'bravo'))
  
  @dec('A', 'B')
  def my_func():
      pass
  
  my_func.inputs['alpha'] == 'A'
  my_func.inputs['bravo'] == 'B'
  

Return type:

callable

Returns:

The created decorator.

Raises HookError:  

when given arguments are not valid.