API Reference¶
Core class which manages registration of plugin objects and hook calls. |
|
The primary hook-calling object. |
|
A class to store/modify results from a |
|
A class to encapsulate hook implementations. |
|
A class to encapsulate hook specifications. |
|
Decorator helper class for marking functions as hook specifications. |
|
Decorator helper class for marking functions as hook implementations. |
PluginManager¶
-
class
napari_plugin_engine.
PluginManager
(project_name, *, discover_entry_point=None, discover_prefix=None, discover_path=None)[source]¶ 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 callingregister()
. ThePluginManager
is initialized with aproject_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
andHookSpecificationMarker
instances must be created using the sameproject_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 Nonediscover_prefix (str, optional) – The default module prefix to use when discovering plugins with
PluginManager.discover()
, by default Nonediscover_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
-
_ensure_plugin
(name_or_object)[source]¶ Return plugin object given a name or object. Or raise an exception.
- Parameters
name_or_object (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).
- Returns
The plugin object, if found.
- Return type
Any
- Raises
KeyError – If the plugin does not exist.
-
_hookexec
(caller, methods, kwargs)[source]¶ Returns a function that will call a set of hookipmls with a caller.
This function will be passed to
HookCaller
instances that are created during hookspec and plugin registration.If
enable_tracing()
is used, it will set it’s own wrapper function at self._inner_hookexec to enable tracing of hook calls.- Parameters
caller (HookCaller) – The HookCaller instance that will call the HookImplementations.
methods (List[HookImplementation]) – A list of
HookImplementation
objects whose functions will be called during the hook call loop.kwargs (dict) – Keyword arguments to pass when calling the
HookImplementation
.
- Returns
The result object produced by the multicall loop.
- Return type
-
_plugin2hookcallers
: Dict[Any, List[HookCaller]] = None¶ mapping of
plugin
(object) → list ofHookCaller
HookCaller
s get added inregister()
- Type
-
_register_dict
(dct, name=None, **kwargs)[source]¶ Register a dict as a mapping of method name -> method.
-
_verify_hook
(hook_caller, hookimpl)[source]¶ Check validity of a
hookimpl
- Parameters
hook_caller (HookCaller) – A
HookCaller
instance.hookimpl (HookImplementation) – A
HookImplementation
instance, implementing the hook inhook_caller
.
- Raises
PluginValidationError – If hook_caller is historic and the hookimpl is a hookwrapper.
PluginValidationError – If there are any argument names in the
hookimpl
that are not in thehook_caller.spec
.
- Warns
Warning – If the hookspec has
warn_on_impl
flag (usually a deprecation).
-
add_hookcall_monitoring
(before, after)[source]¶ 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 asbefore
but also anapari_plugin_engine.callers._Result
object which represents the result of the overall hook call.
-
add_hookspecs
(namespace)[source]¶ Add new hook specifications defined in the given
namespace
.Functions are recognized if they have been decorated accordingly.
-
check_pending
()[source]¶ 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)[source]¶ Discover and load plugins.
- Parameters
path (str, optional) – If a string is provided, it is added to
sys.path
(andself.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 usedprefix (str, optional) – If
provided
, modules in the environment starting withprefix
will be imported and searched for hook implementations by defaultself.discover_prefix
is usedignore_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
wasTrue
)- Return type
Tuple[int, List[PluginError]]
-
discovery_blocked
()[source]¶ A context manager that temporarily blocks discovery of new plugins.
- Return type
-
get_errors
(plugin=<Empty.token: 0>, error_type=<Empty.token: 0>)[source]¶ 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_metadata
(plugin, *values)[source]¶ 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
- Return type
-
get_standard_metadata
(plugin)[source]¶ 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
- Raises
KeyError – If
plugin
is a string, but is not a registered plugin_name.
-
property
hooks
¶ An alias for PluginManager.hook
- Return type
_HookRelay
-
iter_available
(path=None, entry_point=None, prefix=None)[source]¶ Iterate over available plugins.
- Parameters
path (str, optional) – If a string is provided, it is added to
sys.path
(andself.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 usedprefix (str, optional) – If
provided
, modules in the environment starting withprefix
will be imported and searched for hook implementations by defaultself.discover_prefix
is used
:param See docstring of
iter_available_plugins()
for details.:
-
list_plugin_metadata
()[source]¶ 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
-
plugins
: Dict[str, Any] = None¶ mapping of
plugin_name
→plugin
(object)Plugins get added to this dict in
register()
- Type
-
prune
()[source]¶ 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
- Raises
TypeError – If
namespace
is a string.ValueError – if the plugin
name
ornamespace
is already registered.
HookCaller¶
-
class
napari_plugin_engine.
HookCaller
(name, hook_execute, namespace=None, spec_opts=None)[source]¶ The primary hook-calling object.
A
PluginManager
may have multipleHookCaller
objects and they are stored in theplugin_manager.hook
namespace, named after the hook specification that they represent. For instance:pm = PluginManager("demo") pm.add_hookspec(some_module) # assuming `some_module` had an @hookspec named `my specification` assert isinstance(pm.hook.my_specification, HookCaller)
Each
HookCaller
instance stores all of theHookImplementation
objects discovered duringplugin registration
(each of which capture the implementation of a specific plugin for this hook specification).The
HookCaller
instance also usually creates and stores a reference to theHookSpecification
instance that encapsulates information about the hook specification, (atHookCaller.spec
)- Parameters
name (str) – The name of the hook specification that this
HookCaller
represents.hook_execute (Callable) – A
HookExecFunc
function. In almost every case, this will be provided by thePluginManager
during hook registration asPluginManager._hookexec()
… which is, in turn, mostly just a wrapper around_multicall()
.namespace (Any, optional) – An namespace (such as a module or class) to search during HookSpecification creation for functions decorated with
@hookspec
named with the stringname
.spec_opts (Optional[dict], optional) – keyword arguments to be passed when creating the
HookSpecification
instance atself.spec
.
-
__call__
(*args, _plugin=None, _skip_impls=[], **kwargs)[source]¶ Call hook implementation(s) for this spec and return result(s).
This is the primary way to call plugin hook implementations.
Note
Parameters are prefaced by underscores to reduce potential conflicts with argument names in hook specifications. There is a test in
test_hook_specifications.test_annotation_on_hook_specification()
to ensure that these argument names are never used in one of our hookspecs.- Parameters
_plugin (str, optional) – The name of a specific plugin to use. By default all implementations will be called (though if
firstresult==True
, only the first non-None result will be returned)._skip_impls (List[HookImplementation], optional) – A list of HookImplementation instances that should be skipped when calling hook implementations, by default None
**kwargs – keys should match the names of arguments in the corresponding hook specification, values will be passed as arguments to the hook implementations.
- Raises
HookCallError – If one or more of the keys in
kwargs
is not present in one of thehook_impl.argnames
.PluginCallError – If
firstresult == True
and a plugin raises an Exception.
- Returns
If the hookspec was declared with
firstresult==True
, a single result will be returned. Otherwise will return a list of results from all hook implementations for this hook caller.If
_plugin
is provided, will return the single result from the specified plugin.- Return type
result
-
_call_plugin
(plugin_name, *args, **kwargs)[source]¶ Call the hook implementation for a specific plugin
Note
This method is not intended to be called directly. Instead, just call the instance directly, specifing the
_plugin
argument. See the__call__()
method.- Parameters
plugin_name (str) – Name of the plugin
- Returns
Result of implementation call provided by plugin
- Return type
Any
- Raises
TypeError – If the implementation is a hook wrapper (cannot be called directly)
TypeError – If positional arguments are provided
HookCallError – If one of the required arguments in the hook specification is not present in
kwargs
.PluginCallError – If an exception is raised when calling the plugin
-
_set_plugin_enabled
(plugin_name, enabled)[source]¶ Enable or disable the hook implementation for a specific plugin.
-
bring_to_front
(new_order)[source]¶ Move items in
new_order
to the front of the call order.By default, hook implementations are called in last-in-first-out order of registration, and pluggy does not provide a built-in way to rearrange the call order of hook implementations.
This function accepts a
HookCaller
instance and the desirednew_order
of the hook implementations (in the form of list of plugin names, or a list of actualHookImplementation
instances) and reorders the implementations in the hook caller accordingly.Note
Hook implementations are actually stored in two separate list attributes in the hook caller:
HookCaller._wrappers
andHookCaller._nonwrappers
, according to whether the correspondingHookImplementation
instance was marked as a wrapper or not. This method only sorts _nonwrappers.- Parameters
new_order (list of str or list of
HookImplementation
) – instances The desired CALL ORDER of the hook implementations. The list does not need to include every hook implementation inget_hookimpls()
, but those that are not included will be left at the end of the call order.- Raises
TypeError – If any item in
new_order
is neither a string (plugin_name) or aHookImplementation
instance.ValueError – If any item in
new_order
is neither the name of a plugin or aHookImplementation
instance that is present in self._nonwrappers.ValueError – If
new_order
argument has multiple entries for the same implementation.
Examples
Imagine you had a hook specification named
print_plugin_name
, that expected plugins to simply print their own name. An implementation might look like:>>> # hook implementation for ``plugin_1`` >>> @hook_implementation ... def print_plugin_name(): ... print("plugin_1")
If three different plugins provided hook implementations. An example call for that hook might look like:
>>> plugin_manager.hook.print_plugin_name() plugin_1 plugin_2 plugin_3
If you wanted to rearrange their call order, you could do this:
>>> new_order = ["plugin_2", "plugin_3", "plugin_1"] >>> plugin_manager.hook.print_plugin_name.bring_to_front(new_order) >>> plugin_manager.hook.print_plugin_name() plugin_2 plugin_3 plugin_1
You can also just specify one or more item to move them to the front of the call order: >>> plugin_manager.hook.print_plugin_name.bring_to_front([“plugin_3”]) >>> plugin_manager.hook.print_plugin_name() plugin_3 plugin_2 plugin_1
-
call_extra
(methods, kwargs)[source]¶ Call the hook with some additional temporarily participating methods using the specified
kwargs
as call parameters.
-
call_historic
(result_callback=None, kwargs=None, with_impl=False)[source]¶ Call the hook with given
kwargs
for all registered plugins and for all plugins which will be registered afterwards.If
result_callback
is notNone
it will be called for for each non-None
result obtained from a hook implementation.If
with_impl
isTrue
, the caller is indicating thatresult_callback
has a signature ofcallback(result, hookimpl)
, and will be called as such.
-
call_with_result_obj
(*, _skip_impls=[], **kwargs)[source]¶ Call hook implementation(s) for this spec and return HookResult.
The
HookResult
object carries the result (in itsresult
property) but also additional information about the hook call, such as the implementation that returned each result and any call errors.- Parameters
_skip_impls (List[HookImplementation], optional) – A list of HookImplementation instances that should be skipped when calling hook implementations, by default None
**kwargs – keys should match the names of arguments in the corresponding hook specification, values will be passed as arguments to the hook implementations.
- Returns
result – A
HookResult
object that contains the results returned by plugins along with other metadata about the call.- Return type
- Raises
HookCallError – If one or more of the keys in
kwargs
is not present in one of thehook_impl.argnames
.PluginCallError – If
firstresult == True
and a plugin raises an Exception.
HookResult¶
-
class
napari_plugin_engine.
HookResult
(result, excinfo, firstresult=False, plugin_errors=None)[source]¶ A class to store/modify results from a
_multicall()
hook loop.Results are accessed in
.result
property, which will also raise any exceptions that occured during the hook loop.- Parameters
results (List[Tuple[Any, HookImplementation]]) – A list of (result, HookImplementation) tuples, with the result and HookImplementation object responsible for each result collected during a _multicall loop.
excinfo (tuple) – The output of sys.exc_info() if raised during the multicall loop.
firstresult (bool, optional) – Whether the hookspec had
firstresult == True
, by default False. If True, self._result, and self.implementation will be single values, otherwise they will be lists.plugin_errors (list) – A list of any
PluginCallError
instances that were created during the multicall loop.
-
force_result
(result)[source]¶ Force the result(s) to
result
.This may be used by hookwrappers to alter this result object.
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.
-
implementation
: Optional[Union[HookImplementation, List[HookImplementation]]] = None¶ The HookImplementation(s) that were responsible for each result in
result
-
is_firstresult
: bool = None¶ Whether this HookResult came from a
firstresult
multicall.
HookSpecification¶
HookImplementation¶
Decorators & Markers¶
HookSpecificationMarker¶
-
class
napari_plugin_engine.
HookSpecificationMarker
(project_name)[source]¶ Decorator helper class for marking functions as hook specifications.
You can instantiate it with a project_name to get a decorator. Calling
PluginManager.add_hookspecs()
later will discover all marked functions if thePluginManager
uses the same project_name.-
__call__
(function=None, firstresult=False, historic=False, warn_on_impl=None)[source]¶ if passed a function, directly sets attributes on the function which will make it discoverable to
PluginManager.add_hookspecs()
. If passed no function, returns a decorator which can be applied to a function later using the attributes supplied.If
firstresult
isTrue
the 1:N hook call (N being the number of registered hook implementation functions) will stop at I<=N when the I’th function returns a non-None
result.If
historic
isTrue
calls to a hook will be memorized and replayed on later registered plugins.
-
HookImplementationMarker¶
-
class
napari_plugin_engine.
HookImplementationMarker
(project_name)[source]¶ Decorator helper class for marking functions as hook implementations.
You can instantiate with a
project_name
to get a decorator. CallingPluginManager.register()
later will discover all marked functions if thePluginManager
uses the same project_name.- Parameters
project_name (str) – A namespace for plugin implementations. Implementations decorated with this class will be discovered by
PluginManager.register
if and only ifproject_name
matches theproject_name
of thePluginManager
.
-
__call__
(function=None, *, hookwrapper=False, optionalhook=False, tryfirst=False, trylast=False, specname='')[source]¶ Call the marker instance.
If passed a function, directly sets attributes on the function which will make it discoverable to
PluginManager.register()
. If passed no function, returns a decorator which can be applied to a function later using the attributes supplied.- Parameters
function (callable, optional) – A function to decorate as a hook implementation, If
function
is None, this method returns a function that can be used to decorate other functions.hookwrapper (bool, optional) – Whether this hook implementation behaves as a hookwrapper. by default False
optionalhook (bool, optional) – If
True
, a missing matching hook specification will not result in an error (by default it is an error if no matching spec is found), by default False.tryfirst (bool, optional) – If
True
this hook implementation will run as early as possible in the chain of N hook implementations for a specification, by default Falsetrylast (bool, optional) – If
True
this hook implementation will run as late as possible in the chain of N hook implementations, by default Falsespecname (str, optional) – If provided,
specname
will be used instead of the function name when matching this hook implementation to a hook specification during registration, by default the implementation function name must match the name of the corresponding hook specification.
- Returns
If
function
is notNone
, will decorate the function with attributes, and return the function. Iffunction
is None, will return a decorator that can be used to decorate functions.- Return type
Callable
Exceptions¶
Base class for exceptions relating to plugins. |
|
Plugin module is unimportable. |
|
If an unexpected error occurs during registration. |
|
Base class for errors pertaining to a specific hook implementation. |
|
When a plugin implementation fails validation. |
|
Raised when an error is raised when calling a plugin implementation. |
|
If a hook is called incorrectly. |
PluginError¶
-
class
napari_plugin_engine.
PluginError
(message='', *, plugin=None, plugin_name=None, cause=None)[source]¶ Bases:
Exception
Base class for exceptions relating to plugins.
- Parameters
-
classmethod
get
(*, plugin=<Empty.token: 0>, plugin_name=<Empty.token: 0>, error_type=<Empty.token: 0>)[source]¶ Return errors that have been logged, filtered by parameters.
- Parameters
manager (PluginManager, optional) – If provided, will restrict errors to those that are owned by
manager
.plugin_name (str) – If provided, will restrict errors to those that were raised by
plugin_name
.error_type (Exception) – If provided, will restrict errors to instances of
error_type
.
- Returns
A list of PluginErrors that have been instantiated during this session that match the provided parameters.
- Return type
list of PluginError
- Raises
TypeError – If
error_type
is provided and is not an exception class.
-
log
(package_info=True, logger=None, level=40)[source]¶ Log this error with metadata, optionally provide logger and level.
- Parameters
package_info (bool, optional) – If true, will include package metadata in log, by default True
logger (logging.Logger or str, optional) – A Logger instance or name of a logger to use, by default None
level (int, optional) – The logging level to use, by default logging.ERROR
PluginImportError¶
-
class
napari_plugin_engine.
PluginImportError
(message='', *, plugin=None, plugin_name=None, cause=None)[source]¶ Bases:
napari_plugin_engine.exceptions.PluginError
,ImportError
Plugin module is unimportable.
PluginRegistrationError¶
PluginImplementationError¶
PluginValidationError¶
PluginCallError¶
HookCallError¶
Extra Functions¶
-
napari_plugin_engine.hooks.
_multicall
(hook_impls, caller_kwargs, firstresult=False)[source]¶ The primary
HookImplementation
call loop.- Parameters
hook_impls (list) – A sequence of hook implementation (HookImplementation) objects
caller_kwargs (dict) – Keyword:value pairs to pass to each
hook_impl.function
. Every key in the dict must be present in theargnames
property for eachhook_impl
inhook_impls
.firstresult (bool, optional) – If
True
, return the first non-null result found, otherwise, return a list of results from all hook implementations, by default False
- Returns
outcome – A
HookResult
object that contains the results returned by plugins along with other metadata about the call.- Return type
- Raises
HookCallError – If one or more of the keys in
caller_kwargs
is not present in one of thehook_impl.argnames
.PluginCallError – If
firstresult == True
and a plugin raises an Exception.
-
napari_plugin_engine.manager.
ensure_namespace
(obj, name='orphan')[source]¶ Convert a
dict
to an object that providesgetattr
.- Parameters
obj (Any) – An object, may be a
dict
, or a regular namespace object.name (str, optional) – A name to use for the new namespace, if created. by default ‘orphan’
- Returns
A namespace object. If
obj
is adict
, creates a newtype
namedname
, prepopulated with the key:value pairs fromobj
. Otherwise, ifobj
is not adict
, will return the originalobj
.- Return type
- Raises
ValueError – If
obj
is adict
that contains keys that are not valid identifiers.
-
napari_plugin_engine.manager.
temp_path_additions
(path)[source]¶ A context manager that temporarily adds
path
to sys.path.
-
napari_plugin_engine.dist.
get_dist
(obj)[source]¶ Return a
importlib.metadata.Distribution
for any python object.- Parameters
obj (Any) – A python object. If a string, will be interpreted as a dist name.
- Returns
dist – The distribution object for the corresponding package, if found.
- Return type
Distribution
Types¶
-
napari_plugin_engine.hooks.
HookExecFunc
= typing.Callable[[ForwardRef('HookCaller'), typing.List[napari_plugin_engine.implementation.HookImplementation], dict], napari_plugin_engine.callers.HookResult]¶ A function that loops calling a list of
HookImplementation
s and returns aHookResult
.- Parameters
hook_caller (HookCaller) – a
HookCaller
instance.hook_impls (List[HookImplementation]) – a list of
HookImplementation
instances to call.kwargs (dict) – a mapping of keyword arguments to provide to the implementation.
- Returns
result – The
HookResult
object resulting from the call loop.- Return type