`cement.core.hook`

Cement core hooks module.

class cement.core.hook.HookManager(app: App)[source]

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: str) → None[source]

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: str) → bool[source]

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[str][source]

List all defined hooks.

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

register(name: str, func: Callable, weight: int = 0) → bool[source]

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
*un-instantiated*
method (non-instance)
function. (simple)

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

Returns:: True if hook is registered successfully, False otherwise.
Return type:: bool

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: str, *args: Any, **kwargs: Any) → Generator[source]

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

cement.core.hook

`cement.core.hook`