cement.core.hook

Cement core hooks module.

class cement.core.hook.HookManager(app)

Bases: object

Manages the hook system to define, get, run, etc hooks within the the Cement Framework and applications Built on Cement (tm).

define(name)

Define a hook namespace that the application and plugins can register hooks in.

Parameters:name (str) – The name of the hook, stored as hooks[‘name’] Raises:cement.core.exc.FrameworkError – If the hook name is already defined

Example

from cement import App

with App('myapp') as app:
    app.hook.define('my_hook_name')

defined(hook_name)

Test whether a hook name is defined.

Parameters:hook_name (str) – The name of the hook. I.e. my_hook_does_awesome_things. Returns:True if the hook is defined, False otherwise. Return type:bool

Example

from cement import App

with App('myapp') as app:
    app.hook.defined('some_hook_name'):
        # do something about it
        pass

list()

List all defined hooks.

Returns:List of registered hook labels. Return type:hooks (list)

register(name, func, weight=0)

Register a function to a hook. The function will be called, in order of weight, when the hook is run.

Parameters:

• name (str) – The name of the hook to register too. I.e. pre_setup, post_run, etc.
• func (function) – The function to register to the hook. This is an
• non-instance method, simple function. (*un-instantiated*,) –

Keywork Args:

weight (int): The weight in which to order the hook function.

Example

from cement import App

def my_hook_func(app):
    # do something with app?
    return True

with App('myapp') as app:
    app.hook.define('my_hook_name')
    app.hook.register('my_hook_name', my_hook_func)

run(name, *args, **kwargs)

Run all defined hooks in the namespace.

Parameters:

• name (str) – The name of the hook function.
• args (tuple) – Additional arguments to be passed to the hook functions.
• kwargs (dict) – Additional keyword arguments to be passed to the hook functions.

Yields:

The result of each hook function executed.

Raises:

cement.core.exc.FrameworkError – If the hook name is not defined

Example

from cement import App

def my_hook_func(app):
    # do something with app?
    return True

with App('myapp') as app:
    app.hook.define('my_hook_name')
    app.hook.register('my_hook_name', my_hook_func)
    for res in app.hook.run('my_hook_name', app):
        # do something with the result?
        pass