API Reference

class pluggy.PluginManager(project_name: str)[source]

Core 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 hook implementations) by calling register(plugin).

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

Parameters:

project_name – The short project name. Prefer snake case. Make sure it’s unique!

project_name: Final

The project name.

hook: Final

The “hook relay”, used to call a hook on all registered plugins. See Calling hooks.

trace: Final[TagTracerSub]

The tracing entry point. See Built-in tracing.

register(plugin: object, name: str | None = None) str | None[source]

Register a plugin and return its name.

Parameters:

name – The name under which to register the plugin. If not specified, a name is generated using get_canonical_name().

Returns:

The plugin name. If the name is blocked from registering, returns None.

If the plugin is already registered, raises a ValueError.

parse_hookimpl_opts(plugin: object, name: str) HookimplOpts | None[source]

Try to obtain a hook implementation from an item with the given name in the given plugin which is being searched for hook impls.

Returns:

The parsed hookimpl options, or None to skip the given item.

This method can be overridden by PluginManager subclasses to customize how hook implementation are picked up. By default, returns the options for items decorated with HookimplMarker.

unregister(plugin: object | None = None, name: str | None = None) Any | None[source]

Unregister a plugin and all of its hook implementations.

The plugin can be specified either by the plugin object or the plugin name. If both are specified, they must agree.

Returns the unregistered plugin, or None if not found.

set_blocked(name: str) None[source]

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

is_blocked(name: str) bool[source]

Return whether the given plugin name is blocked.

unblock(name: str) bool[source]

Unblocks a name.

Returns whether the name was actually blocked.

add_hookspecs(module_or_class: module | type) None[source]

Add new hook specifications defined in the given module_or_class.

Functions are recognized as hook specifications if they have been decorated with a matching HookspecMarker.

parse_hookspec_opts(module_or_class: module | type, name: str) HookspecOpts | None[source]

Try to obtain a hook specification from an item with the given name in the given module or class which is being searched for hook specs.

Returns:

The parsed hookspec options for defining a hook, or None to skip the given item.

This method can be overridden by PluginManager subclasses to customize how hook specifications are picked up. By default, returns the options for items decorated with HookspecMarker.

get_plugins() set[Any][source]

Return a set of all registered plugin objects.

is_registered(plugin: object) bool[source]

Return whether the plugin is already registered.

get_canonical_name(plugin: object) str[source]

Return a canonical name for a plugin object.

Note that a plugin may be registered under a different name specified by the caller of register(plugin, name). To obtain the name of a registered plugin use get_name(plugin) instead.

get_plugin(name: str) Any | None[source]

Return the plugin registered under the given name, if any.

has_plugin(name: str) bool[source]

Return whether a plugin with the given name is registered.

get_name(plugin: object) str | None[source]

Return the name the plugin is registered under, or None if is isn’t.

check_pending() None[source]

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

load_setuptools_entrypoints(group: str, name: str | None = None) int[source]

Load modules from querying the specified setuptools group.

Parameters:
  • group – Entry point group to load plugins.

  • name – If given, loads only plugins with the given name.

Returns:

The number of plugins loaded by this call.

list_plugin_distinfo() list[tuple[object, DistFacade]][source]

Return a list of (plugin, distinfo) pairs for all setuptools-registered plugins.

list_name_plugin() list[tuple[str, object]][source]

Return a list of (name, plugin) pairs for all registered plugins.

get_hookcallers(plugin: object) list[HookCaller] | None[source]

Get all hook callers for the specified plugin.

Returns:

The hook callers, or None if plugin is not registered in this plugin manager.

add_hookcall_monitoring(before: Callable[[str, Sequence[HookImpl], Mapping[str, Any]], None], after: Callable[[Result[Any], str, Sequence[HookImpl], Mapping[str, Any]], None]) Callable[[], None][source]

Add before/after tracing functions for all hooks.

Returns an undo function which, when called, removes 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.

enable_tracing() Callable[[], None][source]

Enable tracing of hook calls.

Returns an undo function which, when called, removes the added tracing.

subset_hook_caller(name: str, remove_plugins: Iterable[object]) HookCaller[source]

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

class pluggy.PluginValidationError(plugin: object, message: str)[source]

Bases: Exception

Plugin failed validation.

Parameters:
  • plugin – The plugin which failed validation.

  • message – Error message.

plugin

The plugin which failed validation.

@pluggy.HookspecMarker[source]

Decorator for marking functions as hook specifications.

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.

@pluggy.HookimplMarker[source]

Decorator for marking functions as hook implementations.

Instantiate it 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.

final class pluggy.HookRelay[source]

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

<hook name>
Type:

HookCaller

The caller for the hook with the given name.

class pluggy.HookCaller[source]

A caller of all registered implementations of a hook specification.

name: Final

Name of the hook getting called.

is_historic() bool[source]

Whether this caller is historic.

get_hookimpls() list[HookImpl][source]

Get all registered hook implementations for this hook.

__call__(**kwargs: object) Any[source]

Call the hook.

Only accepts keyword arguments, which should match the hook specification.

Returns the result(s) of calling all registered plugins, see Calling hooks.

call_historic(result_callback: Callable[[Any], None] | None = None, kwargs: Mapping[str, object] | None = None) None[source]

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

Parameters:

result_callback – If provided, will be called for each non-None result obtained from a hook implementation.

call_extra(methods: Sequence[Callable[[...], object]], kwargs: Mapping[str, object]) Any[source]

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

class pluggy.HookCallError[source]

Bases: Exception

Hook was called incorrectly.

final class pluggy.Result[source]

Bases: Generic[ResultType]

An object used to inspect and set the result in a hook wrapper.

force_result(result: ResultType) None[source]

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.

This overrides any previous result or exception.

force_exception(exception: BaseException) None[source]

Force the result to fail with exception.

This overrides any previous result or exception.

New in version 1.1.0.

get_result() ResultType[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.

final class pluggy.HookImpl[source]

A hook implementation in a HookCaller.

function: Final

The hook implementation function.

argnames: Final

The positional parameter names of function`.

kwargnames: Final

The keyword parameter names of function`.

plugin: Final

The plugin which defined this hook implementation.

opts: Final

The HookimplOpts used to configure this hook implementation.

plugin_name: Final

The name of the plugin which defined this hook implementation.

wrapper: Final

Whether the hook implementation is a wrapper.

hookwrapper: Final

Whether the hook implementation is an old-style wrapper.

optionalhook: Final

Whether validation against a hook specification is optional.

tryfirst: Final

Whether to try to order this hook implementation first.

trylast: Final

Whether to try to order this hook implementation last.

class pluggy.HookspecOpts[source]

Bases: TypedDict

Options for a hook specification.

firstresult: bool

Whether the hook is first result only.

historic: bool

Whether the hook is historic.

warn_on_impl: Warning | None

Whether the hook warns when implemented.

class pluggy.HookimplOpts[source]

Bases: TypedDict

Options for a hook implementation.

wrapper: bool

Whether the hook implementation is a wrapper.

hookwrapper: bool

Whether the hook implementation is an old-style wrapper.

optionalhook: bool

Whether validation against a hook specification is optional.

tryfirst: bool

Whether to try to order this hook implementation first.

trylast: bool

Whether to try to order this hook implementation last.

specname: str | None

The name of the hook specification to match, see Hookspec name matching.

Warnings

Custom warnings generated in some situations such as improper usage or deprecated features.

class pluggy.PluggyWarning

Bases: UserWarning

Base class for all warnings emitted by pluggy.

class pluggy.PluggyTeardownRaisedWarning

Bases: PluggyWarning

A plugin raised an exception during an old-style hookwrapper teardown.

Such exceptions are not handled by pluggy, and may cause subsequent teardowns to be executed at unexpected times, or be skipped entirely.

This is an issue in the plugin implementation.

If the exception is unintended, fix the underlying cause.

If the exception is intended, switch to new-style hook wrappers, or use result.force_exception() to set the exception instead of raising.