napari.plugins.PluginManager

class napari.plugins.PluginManager(project_name, *, discover_entry_point=None, discover_prefix=None, discover_path=None)

Bases: object

Core class which manages registration of plugin objects and hook calls.

You can register new hooks by calling add_hookspecs(). You can register plugin objects (which contain hooks) by calling register(). The PluginManager is initialized with a project_name that is used when discovering hook specifications and hook implementations.

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

Parameters

• project_name (str) – The name of the host project. All HookImplementationMarker and HookSpecificationMarker instances must be created using the same project_name to be detected by this plugin manager.

• discover_entry_point (str, optional) – The default entry_point group to search when discovering plugins with PluginManager.discover(), by default None

• discover_prefix (str, optional) – The default module prefix to use when discovering plugins with PluginManager.discover(), by default None

• discover_path (str or list of str, optional) – A path or paths to include when discovering plugins with PluginManager.discover(), by default None

Examples

from napari_plugin_engine import PluginManager
import my_hookspecs

plugin_manager = PluginManager(
    'my_project',
    discover_entry_point='app.plugin',
    discover_prefix='app_',
)
plugin_manager.add_hookspecs(my_hookspecs)
plugin_manager.discover()

# hooks now live in plugin_manager.hook
# plugin dict is at plugin_manager.plugins

Methods

Attributes

add_hookcall_monitoring(before, after)

Add before/after tracing functions for all hooks.

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

Return type

Callable[[], None]

add_hookspecs(namespace)

Add new hook specifications defined in the given namespace.

Functions are recognized if they have been decorated accordingly.

check_pending()

Make sure all hooks have a specification, or are optional.

Raises

PluginValidationError – If a hook implementation that was not marked as optionalhook has been registered for a non-existent hook specification.

discover(path=None, entry_point=None, prefix=None, ignore_errors=True)

Discover and load plugins.

Parameters

• path (str, optional) – If a string is provided, it is added to sys.path (and self.discover_path) before importing, and removed at the end.

• entry_point (str, optional) – An entry_point group to search for, by default self.discover_entry_point is used

• prefix (str, optional) – If provided, modules in the environment starting with prefix will be imported and searched for hook implementations by default self.discover_prefix is used

• ignore_errors (bool, optional) – If True, errors will be gathered and returned at the end. Otherwise, they will be raised immediately. by default True

Returns

(count, errs) – The number of succefully loaded modules, and a list of errors that occurred (if ignore_errors was True)

Return type

Tuple[int, List[PluginError]]

discovery_blocked()

A context manager that temporarily blocks discovery of new plugins.

Return type

Generator

enable_tracing()

Enable tracing of hook calls and return an undo function.

get_errors(plugin=<Empty.token: 0>, error_type=<Empty.token: 0>)

Return a list of PluginErrors associated with plugin.

Parameters

• plugin (Any) – If provided, will restrict errors to those that were raised by plugin. If a string is provided, it will be interpreted as the name of the plugin, otherwise it is assumed to be the actual plugin object itself.

• error_type (PluginError) – If provided, will restrict errors to instances of error_type.

Return type

List[PluginError]

get_hookcallers(plugin)

get all hook callers for the specified plugin.

Return type

Optional[List[HookCaller]]

get_metadata(plugin, *values)

Return metadata values for a given plugin

Parameters

• plugin (Any) – Either a string (in which case it is interpreted as a plugin name), or a non-string object (in which case it is assumed to be a plugin module or class).

• *values (str) – key(s) to lookup in the plugin object distribution metadata. At least one value must be supplied.

Raises

• TypeError – If no values are supplied.

• KeyError – If the plugin does not exist.

Return type

Union[str, Dict[str, Optional[str]], None]

get_name(plugin)

Return name for registered plugin or None if not registered.

get_standard_metadata(plugin)

Return a standard metadata dict for plugin.

Parameters

plugin (Any) – A plugin name or any object. If it is a plugin name, it must be a registered plugin.

Returns

metadata – A dicts with plugin metadata. The dict is guaranteed to have the following keys:

• plugin_name: The name of the plugin as registered

• package: The name of the package

• version: The version of the plugin package

• summary: A one-line summary of what the distribution does

• author: The author’s name

• email: The author’s (or maintainer’s) e-mail address.

• license: The license covering the distribution

• url: The home page for the package, or dowload url if N/A.

• hooks: A list of hookspec names that this plugin implements.

Return type

dict

Raises

KeyError – If plugin is a string, but is not a registered plugin_name.

property hooks

An alias for PluginManager.hook

Return type

_HookRelay

is_blocked(plugin_name)

Return True if the given plugin name is blocked.

Return type

bool

is_registered(obj)

Return True if the plugin is already registered.

Return type

bool

iter_available(path=None, entry_point=None, prefix=None)

Iterate over available plugins.

Parameters

• path (str, optional) – If a string is provided, it is added to sys.path (and self.discover_path) before importing, and removed at the end.

• entry_point (str, optional) – An entry_point group to search for, by default self.discover_entry_point is used

• prefix (str, optional) – If provided, modules in the environment starting with prefix will be imported and searched for hook implementations by default self.discover_prefix is used

:param See docstring of iter_available_plugins() for details.:

Return type

Generator[Tuple[str, str, Optional[str]], None, None]

list_plugin_metadata()

Return list of standard metadata dicts for every registered plugin.

Returns

metadata – A list of dicts with plugin metadata. Every dict in the list is guaranteed to have the following keys mentioned in get_standard_metadata()

Return type

dict

plugins: Dict[str, Any]

mapping of plugin_name → plugin (object)

Plugins get added to this dict in register()

Type

dict

prune()

Unregister modules that can no longer be imported.

Useful if pip uninstall has been run during the session.

register(namespace, name=None)

Register a plugin and return its canonical name or None.

Parameters

• plugin (Any) – The namespace (class, module, dict, etc…) to register

• name (str, optional) – Optional name for plugin, by default get_canonical_name(plugin)

Returns

canonical plugin name, or None if the name is blocked from registering.

Return type

str or None

Raises

• TypeError – If namespace is a string.

• ValueError – if the plugin name or namespace is already registered.

set_blocked(plugin_name, blocked=True)

Block registrations of plugin_name, unregister if registered.

Parameters

• plugin_name (str) – A plugin name to block.

• blocked (bool, optional) – Whether to block the plugin. If False will “unblock” plugin_name. by default True

unregister(name_or_object)

Unregister a plugin object or plugin_name.

Parameters

name_or_object (str or Any) – A module/class object or a plugin name (string).

Returns

module – The module object, or None if the name_or_object was not found.

Return type

Any or None