Api Reference

exception pluggy.HookCallError

Bases: Exception

Hook was called wrongly.

class pluggy.HookimplMarker(project_name)

Bases: object

Decorator helper class for marking functions as hook implementations.

You can instantiate with a project_name to get a decorator. Calling PluginManager.register() later will discover all marked functions if the PluginManager uses the same project_name.

class pluggy.HookspecMarker(project_name)

Bases: object

Decorator helper class for marking functions as hook specifications.

You can instantiate it with a project_name to get a decorator. Calling PluginManager.add_hookspecs() later will discover all marked functions if the PluginManager uses the same project_name.

class pluggy.PluginManager(project_name)

Bases: object

Core PluginManager class which manages registration of plugin objects and 1:N hook calling.

You can register new hooks by calling add_hookspecs(module_or_class). You can register plugin objects (which contain hooks) by calling register(plugin). The PluginManager is initialized with a prefix that is searched for in the names of the dict of registered plugin objects.

For debugging purposes you can call PluginManager.enable_tracing() which will subsequently send debug information to the trace helper.

add_hookcall_monitoring(before, after)

add before/after tracing functions for all hooks and return an undo function which, when called, will remove the added tracers.

before(hook_name, hook_impls, kwargs) will be called ahead of all hook calls and receive a hookcaller instance, a list of HookImpl instances and the keyword arguments for the hook call.

after(outcome, hook_name, hook_impls, kwargs) receives the same arguments as before but also a pluggy._callers._Result object which represents the result of the overall hook call.

add_hookspecs(module_or_class)

add new hook specifications defined in the given module_or_class. Functions are recognized if they have been decorated accordingly.

check_pending()

Verify that all hooks which have not been verified against a hook specification are optional, otherwise raise PluginValidationError.

enable_tracing()

enable tracing of hook calls and return an undo function.

get_canonical_name(plugin)

Return canonical name for a plugin object. Note that a plugin may be registered under a different name which was specified by the caller of register(plugin, name). To obtain the name of an registered plugin use get_name(plugin) instead.

get_hookcallers(plugin)

get all hook callers for the specified plugin.

get_name(plugin)

Return name for registered plugin or None if not registered.

get_plugin(name)

Return a plugin or None for the given name.

get_plugins()

return the set of registered plugins.

has_plugin(name)

Return True if a plugin with the given name is registered.

is_blocked(name)

return True if the given plugin name is blocked.

is_registered(plugin)

Return True if the plugin is already registered.

list_name_plugin()

return list of name/plugin pairs.

list_plugin_distinfo()

return list of distinfo/plugin tuples for all setuptools registered plugins.

load_setuptools_entrypoints(group, name=None)

Load modules from querying the specified setuptools group.

Parameters:

• group (str) – entry point group to load plugins

• name (str) – if given, loads only plugins with the given name.

Return type:

int

Returns:

return the number of loaded plugins by this call.

parse_hookimpl_opts(plugin, name)

parse_hookspec_opts(module_or_class, name)

register(plugin, name=None)

Register a plugin and return its canonical name or None if the name is blocked from registering. Raise a ValueError if the plugin is already registered.

set_blocked(name)

block registrations of the given name, unregister if already registered.

subset_hook_caller(name, remove_plugins)

Return a new _hooks._HookCaller instance for the named method which manages calls to all registered plugins except the ones from remove_plugins.

unregister(plugin=None, name=None)

unregister a plugin object and all its contained hook implementations from internal data structures.

exception pluggy.PluginValidationError(plugin, message)

Bases: Exception

plugin failed validation.

Parameters:

plugin (object) – the plugin which failed validation, may be a module or an arbitrary object.

class pluggy._callers._Result(result, excinfo)

_Result.get_result()

Get the result(s) for this hook call.

If the hook was marked as a firstresult only a single value will be returned otherwise a list of results.

_Result.force_result(result)

Force the result(s) to result.

If the hook was marked as a firstresult a single value should be set otherwise set a (modified) list of results. Any exceptions found during invocation will be deleted.

class pluggy._hooks._HookCaller(name, hook_execute, specmodule_or_class=None, spec_opts=None)

_HookCaller.call_extra(methods, kwargs)

Call the hook with some additional temporarily participating methods using the specified kwargs as call parameters.

_HookCaller.call_historic(result_callback=None, kwargs=None)

Call the hook with given kwargs for all registered plugins and for all plugins which will be registered afterwards.

If result_callback is not None it will be called for for each non-None result obtained from a hook implementation.

class pluggy._hooks._HookRelay

hook holder object for performing 1:N hook calls where N is the number of registered plugins.