Api Reference

class pluggy.PluginManager(project_name, implprefix=None)[source]

Bases: object

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

You can register new hooks by calling add_hookspec(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 enable_tracing() which will subsequently send debug information to the trace helper.

add_hookcall_monitoring(before, after)[source]

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 _Result` object which represents the result of the overall hook call.


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


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


enable tracing of hook calls and return an undo function.


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 all hook callers for the specified plugin.


Return name for registered plugin or None if not registered.


Return a plugin or None for the given name.


return the set of registered plugins.


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


return True if the name blogs registering plugins of that name.


Return True if the plugin is already registered.


return list of name/plugin pairs.


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


Load modules from querying the specified setuptools entrypoint name. Return the number of loaded plugins.

parse_hookimpl_opts(plugin, name)[source]
parse_hookspec_opts(module_or_class, name)[source]
register(plugin, name=None)[source]

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.


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

subset_hook_caller(name, remove_plugins)[source]

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

unregister(plugin=None, name=None)[source]

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

exception pluggy.PluginValidationError(plugin, message)[source]

Bases: exceptions.Exception

plugin failed validation.

Parameters:plugin (object) – the plugin which failed validation, may be a module or an arbitrary object.
exception pluggy.HookCallError[source]

Bases: exceptions.Exception

Hook was called wrongly.

class pluggy.HookspecMarker(project_name)[source]

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.HookimplMarker(project_name)[source]

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.


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.


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.

_HookCaller.call_extra(methods, kwargs)[source]

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