napari.plugins.NapariPluginManager

class napari.plugins.NapariPluginManager[source]¶

Bases: napari_plugin_engine.manager.PluginManager

PluginManager subclass for napari-specific functionality.

registered (value: str): Emitted after plugin named value has been registered.
unregistered (value: str): Emitted after plugin named value has been unregistered.
enabled (value: str): Emitted after plugin named value has been removed from the block list.
disabled (value: str): Emitted after plugin named value has been added to the block list.

Methods

`add_hookcall_monitoring`(before, after)	Add before/after tracing functions for all hooks.
`add_hookspecs`(namespace)	Add new hook specifications defined in the given `namespace`.
`assign_reader_to_extensions`(reader, extensions)	Assign a specific reader plugin to extensions.
`assign_writer_to_extensions`(writer, extensions)	Assign a specific writer plugin to extensions.
`available_samples`()	Return a tuple of sample data keys provided by plugins.
`call_order`([first_result_only])	Returns the call order from the plugin manager.
`check_pending`()	Make sure all hooks have a specification, or are optional.
`discover`([path, entry_point, prefix, …])	Discover and load plugins.
`discover_sample_data`()
`discover_themes`()	Trigger discovery of theme plugins.
`discover_widgets`()	Trigger discovery of dock_widgets plugins.
`discovery_blocked`()	A context manager that temporarily blocks discovery of new plugins.
`enable_tracing`()	Enable tracing of hook calls and return an undo function.
`get_errors`([plugin, error_type])	Return a list of PluginErrors associated with `plugin`.
`get_hookcallers`(plugin)	get all hook callers for the specified plugin.
`get_metadata`(plugin, *values)	Return metadata values for a given plugin
`get_name`(plugin)	Return name for registered plugin or `None` if not registered.
`get_reader_for_extension`(extension)	Return reader plugin assigned to extension, or None.
`get_standard_metadata`(plugin)	Return a standard metadata dict for `plugin`.
`get_widget`(plugin_name[, widget_name])	Get widget widget_name provided by plugin plugin_name.
`get_writer_for_extension`(extension)	Return writer plugin assigned to extension, or None.
`is_blocked`(plugin_name)	Return `True` if the given plugin name is blocked.
`is_registered`(obj)	Return `True` if the plugin is already registered.
`iter_available`([path, entry_point, prefix])	Iterate over available plugins.
`iter_widgets`()	rtype `Iterator`[`Tuple`[`str`, `Tuple`[`str`, `Dict`]]]
`list_plugin_metadata`()	Return list of standard metadata dicts for every registered plugin.
`plugin_info`(plugin)	rtype `str`
`prune`()	Unregister modules that can no longer be imported.
`register`(namespace[, name])	Register a plugin and return its canonical name or `None`.
`register_dock_widget`(args, hookimpl)
`register_function_widget`(args, hookimpl)
`register_sample_data`(data, hookimpl)	Register sample data dict returned by napari_provide_sample_data.
`register_theme_colors`(data, hookimpl)	Register theme data dict returned by napari_experimental_provide_theme.
`set_blocked`(plugin_name[, blocked])	Block registrations of `plugin_name`, unregister if registered.
`set_call_order`(new_order)	Sets the plugin manager call order to match settings plugin values.
`unregister`(name_or_object)	Unregister a plugin object or `plugin_name`.
`unregister_theme_colors`(plugin_name)	Unregister theme data from napari.

Attributes

`ENTRY_POINT`
`hooks`	An alias for PluginManager.hook

Details

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.

assign_reader_to_extensions(reader, extensions)[source]¶

Assign a specific reader plugin to extensions.

Parameters

reader (str) – Name of a plugin offering a reader hook.
extensions (Union[str, Iterable[str]]) – Name(s) of extensions to always write with reader

Return type

None

assign_writer_to_extensions(writer, extensions)[source]¶

Assign a specific writer plugin to extensions.

Parameters

writer (str) – Name of a plugin offering a writer hook.
extensions (Union[str, Iterable[str]]) – Name(s) of extensions to always write with writer

Return type

None

available_samples()[source]¶

Return a tuple of sample data keys provided by plugins.

Returns: sample_keys – A sequence of 2-tuples (plugin_name, sample_name) showing available sample data provided by plugins. To load sample data into the viewer, use napari.Viewer.open_sample().
Return type: Tuple[Tuple[str, str], ..]

Examples

from napari.plugins import available_samples

sample_keys = available_samples()
if sample_keys:
    # load first available sample
    viewer.open_sample(*sample_keys[0])

call_order(first_result_only=True)[source]¶

Returns the call order from the plugin manager.

Returns: call_order – mapping of hook_specification name, to a list of dicts with keys: {‘plugin’, ‘enabled’}. Plugins earlier in the dict are called sooner.
Return type: CallOrderDict

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

discover_themes()[source]¶

Trigger discovery of theme plugins.

As a “historic” hook, this should only need to be called once. (historic here means that even plugins that are discovered after this is called will be added.)

discover_widgets()[source]¶

Trigger discovery of dock_widgets plugins.

As a “historic” hook, this should only need to be called once. (historic here means that even plugins that are discovered after this is called will be added.)

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_reader_for_extension(extension)[source]¶

Return reader plugin assigned to extension, or None.

Return type: Optional[str]

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.

get_widget(plugin_name, widget_name=None)[source]¶

Get widget widget_name provided by plugin plugin_name.

Note: it’s important that discover_dock_widgets() has been called first, otherwise plugins may not be found yet. (Typically, that is done in qt_main_window)

Parameters

plugin_name (str) – Name of a plugin providing a widget
widget_name (str, optional) – Name of a widget provided by plugin_name. If None, and the specified plugin provides only a single widget, that widget will be returned, otherwise a ValueError will be raised, by default None

Returns

plugin_widget – Tuple of (widget_class, options).

Return type

Tuple[Callable, dict]

Raises

KeyError – If plugin plugin_name does not provide any widgets
KeyError – If plugin does not provide a widget named widget_name.
ValueError – If widget_name is not provided, but plugin_name provides more than one widget

get_writer_for_extension(extension)[source]¶

Return writer plugin assigned to extension, or None.

Return type: Optional[str]

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

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.

register_sample_data(data, hookimpl)[source]¶

Register sample data dict returned by napari_provide_sample_data.

Each key in data is a sample_name (the string that will appear in the Open Sample menu), and the value is either a string, or a callable that returns an iterable of LayerData tuples, where each tuple is a 1-, 2-, or 3-tuple of (data,), (data, meta), or (data, meta, layer_type).

Parameters

data (Dict[str, Union[str, Callable[.., Iterable[LayerData]]]]) – A mapping of {sample_name->data}
hookimpl (HookImplementation) – The hook implementation that returned the dict

register_theme_colors(data, hookimpl)[source]¶

Register theme data dict returned by napari_experimental_provide_theme.

The theme data should be provided as an iterable containing dictionary of values, where the folder value will be used as theme name.

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

set_call_order(new_order)[source]¶

Sets the plugin manager call order to match settings plugin values.

Note: Run this after load_settings_plugin_defaults, which sets the default values in settings.

Parameters: new_order (CallOrderDict) – mapping of hook_specification name, to a list of dicts with keys: {‘plugin’, ‘enabled’}. Plugins earlier in the dict are called sooner.

unregister(name_or_object)[source]¶

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

unregister_theme_colors(plugin_name)[source]¶: Unregister theme data from napari.