API Reference

class pluggy.PluginManager(project_name: str)

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

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

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

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

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

is_blocked(name: str) → bool

Return whether the given plugin name is blocked.

unblock(name: str) → bool

Unblocks a name.

Returns whether the name was actually blocked.

add_hookspecs(module_or_class: ModuleType | type) → None

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: ModuleType | type, name: str) → HookspecOpts | None

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]

Return a set of all registered plugin objects.

is_registered(plugin: object) → bool

Return whether the plugin is already registered.

get_canonical_name(plugin: object) → str

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

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

has_plugin(name: str) → bool

Return whether a plugin with the given name is registered.

get_name(plugin: object) → str | None

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

check_pending() → None

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

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

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

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

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

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

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]

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]

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

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)

Bases: Exception

Plugin failed validation.

Parameters:

• plugin – The plugin which failed validation.

• message – Error message.

plugin

The plugin which failed validation.

@pluggy.HookspecMarker

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

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

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

A caller of all registered implementations of a hook specification.

name: Final

Name of the hook getting called.

is_historic() → bool

Whether this caller is historic.

get_hookimpls() → list[HookImpl]

Get all registered hook implementations for this hook.

__call__(**kwargs: object) → Any

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

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

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

class pluggy.HookCallError

Bases: Exception

Hook was called incorrectly.

final class pluggy.Result

Bases: Generic[ResultType]

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

force_result(result: ResultType) → None

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

Force the result to fail with exception.

This overrides any previous result or exception.

Added in version 1.1.0.

get_result() → ResultType

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

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

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.

warn_on_impl_args: Mapping[str, Warning] | None

Whether the hook warns when certain arguments are requested.

Added in version 1.5.

class pluggy.HookimplOpts

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.