napari.plugins.NapariPluginManager

class napari.plugins.NapariPluginManager

Bases: napari_plugin_engine.manager.PluginManager

PluginManager subclass for napari-specific functionality.

Notes

The events emitted by the plugin include:

• 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()
list_plugin_metadata()	Return list of standard metadata dicts for every registered plugin.
plugin_info(plugin)
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: Callable[[str, List[napari_plugin_engine.implementation.HookImplementation], dict], None], after: Callable[[napari_plugin_engine.callers.HookResult, str, List[napari_plugin_engine.implementation.HookImplementation], dict], None]) → Callable[[], None]

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.

add_hookspecs(namespace: Any)

Add new hook specifications defined in the given namespace.

Functions are recognized if they have been decorated accordingly.

assign_reader_to_extensions(reader: str, extensions: Union[str, Iterable[str]]) → None

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

assign_writer_to_extensions(writer: str, extensions: Union[str, Iterable[str]]) → None

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

available_samples() → Tuple[Tuple[str, str], ...]

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) → Dict[str, List[napari.plugins._plugin_manager.PluginHookOption]]

Returns the call order from the plugin manager.

Returns

call_order – mapping of hook_specification name, to a list of dicts with keys: {‘plugin’, ‘hook_impl’, ‘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: Optional[str] = None, entry_point: Optional[str] = None, prefix: Optional[str] = None, ignore_errors: bool = True) → Tuple[int, List[napari_plugin_engine.exceptions.PluginError]]

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()

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()

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() → Generator

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: Union[Any, napari_plugin_engine.exceptions.Empty] = Empty.token, error_type: Union[Type[napari_plugin_engine.exceptions.PluginError], napari_plugin_engine.exceptions.Empty] = Empty.token) → List[napari_plugin_engine.exceptions.PluginError]

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.

get_hookcallers(plugin: Any) → Optional[List[napari_plugin_engine.hooks.HookCaller]]

get all hook callers for the specified plugin.

get_metadata(plugin: Any, *values) → Optional[Union[str, Dict[str, Optional[str]]]]

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.

get_name(plugin)

Return name for registered plugin or None if not registered.

get_reader_for_extension(extension: str) → Optional[str]

Return reader plugin assigned to extension, or None.

get_standard_metadata(plugin: Any)

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: str, widget_name: Optional[str] = None) → Tuple[Callable[[...], Union[FunctionGui, QWidget]], Dict[str, Any]]

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: str) → Optional[str]

Return writer plugin assigned to extension, or None.

property hooks: napari_plugin_engine.manager._HookRelay

An alias for PluginManager.hook

is_blocked(plugin_name: str) → bool

Return True if the given plugin name is blocked.

is_registered(obj: Any) → bool

Return True if the plugin is already registered.

iter_available(path: Optional[str] = None, entry_point: Optional[str] = None, prefix: Optional[str] = None) → Iterator[Tuple[str, str, Optional[str]]]

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

list_plugin_metadata() → List[Dict[str, Optional[str]]]

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: Any, name: Optional[str] = None) → Optional[str]

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: Dict[str, Union[str, Callable[[...], Iterable[Union[Tuple[Any], Tuple[Any, Dict], Tuple[Any, Dict, str]]]]]], hookimpl: napari_plugin_engine.implementation.HookImplementation)

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: Dict[str, Dict[str, Union[str, Tuple, List]]], hookimpl: napari_plugin_engine.implementation.HookImplementation)

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: str, 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: Dict[str, List[napari.plugins._plugin_manager.PluginHookOption]])

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: Any) → Optional[Any]

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: str)

Unregister theme data from napari.

previous

napari.plugins

next

napari.plugins.PackageMetadata