# `cement.core.hook`

Cement core hooks module.

class `cement.core.hook.``HookManager`(use_backend_globals=False)

  Bases: `object`

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

  Parameters: | use_backend_globals – Whether to use backend globals (backward compatibility and deprecated).

  `define`(name)

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

    Parameters: | name – The name of the hook, stored as hooks[‘name’]
    Raises: | cement.core.exc.FrameworkError

    Usage:

        from cement.core.foundation import CementApp

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

  `defined`(hook_name)

    Test whether a hook name is defined.

    Parameters: | hook_name – The name of the hook. I.e. `my_hook_does_awesome_things`.
    Returns: | True if the hook is defined, False otherwise.
    Return type: | `boolean`

    Usage:

        from cement.core.foundation import CementApp

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

  `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 – The name of the hook to register too. I.e. `pre_setup`, `post_run`, etc.
    - func – The function to register to the hook. This is an un-instantiated, non-instance method, simple function.
    - weight (`int`) – The weight in which to order the hook function.

    Usage:

        from cement.core.foundation import CementApp

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

        with CementApp('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. Yields the result of each hook function run.

    Parameters:

    - name – The name of the hook function.
    - args – Additional arguments to be passed to the hook functions.
    - kwargs – Additional keyword arguments to be passed to the hook functions.

    Raises: | FrameworkError

    Usage:

        from cement.core.foundation import CementApp

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

        with CementApp('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', self):
                # do something with the result?
                pass

`cement.core.hook.``define`(name)

  DEPRECATION WARNING: This function is deprecated as of Cement 2.7.x and will be removed in future versions of Cement. Use `CementApp.hook.define()` instead.

  —

  Define a hook namespace that plugins can register hooks in.

  Parameters: | name – The name of the hook, stored as hooks[‘name’]
  Raises: | cement.core.exc.FrameworkError

  Usage:

      from cement.core import hook

      hook.define('myhookname_hook')

`cement.core.hook.``defined`(hook_name)

  DEPRECATION WARNING: This function is deprecated as of Cement 2.7.x and will be removed in future versions of Cement. Use `CementApp.hook.defined()` instead.

  —

  Test whether a hook name is defined.

  Parameters: | hook_name – The name of the hook. I.e. `my_hook_does_awesome_things`.
  Returns: | True if the hook is defined, False otherwise.
  Return type: | `boolean`

`cement.core.hook.``register`(name, func, weight=0)

  DEPRECATION WARNING: This function is deprecated as of Cement 2.7.x and will be removed in future versions of Cement. Use `CementApp.hook.register()` instead.

  —

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

  Parameters:

  - name – The name of the hook to register too. I.e. `pre_setup`, `post_run`, etc.
  - func – The function to register to the hook. This is an un-instantiated, non-instance method, simple function.
  - weight (`int`) – The weight in which to order the hook function.

  Usage:

      from cement.core import hook

      def my_hook(*args, **kwargs):
          # do something here
          res = 'Something to return'
          return res

      hook.register('post_setup', my_hook)

`cement.core.hook.``run`(name, *args, **kwargs)

  DEPRECATION WARNING: This function is deprecated as of Cement 2.7.x and will be removed in future versions of Cement. Use `CementApp.hook.run()` instead.

  —

  Run all defined hooks in the namespace. Yields the result of each hook function run.

  Parameters:

  - name – The name of the hook function.
  - args – Additional arguments to be passed to the hook functions.
  - kwargs – Additional keyword arguments to be passed to the hook functions.

  Raises: | FrameworkError

  Usage:

      from cement.core import hook

      for result in hook.run('hook_name'):
          # do something with result from each hook function
          ...