Api Reference

class pluggy.PluginManager(project_name)[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_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)[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 pluggy._callers._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 given plugin name is blocked.


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_setuptools_entrypoints(group, name=None)[source]

Load modules from querying the specified setuptools group.

  • group (str) – entry point group to load plugins
  • name (str) – if given, loads only plugins with the given name.
Return type:



return the number of loaded plugins by this call.

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 _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)[source]

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

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

Bases: 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: 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.

class pluggy._callers._Result(result, excinfo)[source]

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.

class pluggy._hooks._HookCaller(name, hook_execute, specmodule_or_class=None, spec_opts=None)[source]
_HookCaller.call_extra(methods, kwargs)[source]

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

_HookCaller.call_historic(result_callback=None, kwargs=None)[source]

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

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