Errors and Lifecycle Events¶
Two policies¶
pluxeo treats a failure differently depending on what the host asked for:
pm.load(name)propagates. The host asked for this plugin; if it cannot be loaded, the exception reaches the host.pm.load_all()contains. A plugin that fails is markedERRORED, its exception is kept, and the other plugins load. A plugin that is disabled, or declines inshould_load(), is skipped without error.
Failures can happen at each stage: importing the plugin's module (when its factory runs), checking its contract, should_load(), or load().
Inspecting failures¶
from pluxeo import Plugin, PluginManager, PluginState
class Good(Plugin):
namespace = "acme.plugins"
name = "good"
class Bad(Plugin):
namespace = "acme.plugins"
name = "bad"
def load(self):
raise RuntimeError("misconfigured")
pm = PluginManager("acme.plugins", discover=False)
pm.register(Good)
pm.register(Bad)
pm.load_all()
assert pm.state("good") is PluginState.LOADED
assert pm.state("bad") is PluginState.ERRORED
assert isinstance(pm.error("bad"), RuntimeError)
pm.error(name) returns the exception that put the plugin in ERRORED, or None. It is cleared when the plugin later loads successfully.
Failing fast¶
Some hosts prefer not to start at all when a plugin is broken, rather than run without it unnoticed. Check after load_all():
from pluxeo import PluginError
def load_or_fail(pm):
pm.load_all()
for name in pm.names():
if (error := pm.error(name)) is not None:
msg = f"plugin {name} failed to load ({error!r}): fix it, or disable it"
raise PluginError(msg) from error
return pm
Lifecycle listeners¶
To log, count or trace plugin events, pass listeners to the manager. A listener implements any of these methods; the others are simply not called:
| Method | Called |
|---|---|
on_resolve_after(spec) |
when a plugin is discovered or registered |
on_init_after(spec, plugin) |
after the plugin is instantiated |
on_init_error(spec, exc) |
when instantiating it (including importing its module) or its contract check fails |
on_load_before(spec, plugin) |
just before load() |
on_load_after(spec, plugin, result) |
after load() succeeds |
on_load_error(spec, plugin, exc) |
when should_load() or load() raises |
import logging
from pluxeo import PluginManager
log = logging.getLogger("plugins")
class LogPlugins:
def on_load_after(self, spec, plugin, result):
log.info("loaded %s", spec.name)
def on_load_error(self, spec, plugin, exc):
log.error("plugin %s failed: %r", spec.name, exc)
def on_init_error(self, spec, exc):
log.error("plugin %s could not be created: %r", spec.name, exc)
pm = PluginManager("acme.plugins", listeners=[LogPlugins()])
A listener that raises is reported with a warning and does not affect the plugin or the other listeners. The LifecycleListener protocol also declares on_resolve_error, which the current version never calls.
States¶
| State | Meaning |
|---|---|
DISCOVERED |
Known by name; no plugin code imported |
INSTANTIATED |
Created; not loaded yet |
LOADED |
load() ran; hooks live if enabled |
DISABLED |
Declined in should_load(), or disabled by the host after loading |
ERRORED |
Failed; see pm.error(name) |
Exceptions¶
All of pluxeo's exceptions derive from PluginError:
| Exception | Raised when |
|---|---|
PluginNotFoundError |
no plugin of that name is registered |
PluginDisabledError |
the plugin is disabled, or declined to load |
NamespaceMismatchError |
a plugin's namespace differs from its manager's |
ContractError |
a plugin does not satisfy the contract, or the contract is not runtime-checkable |
PluginError |
dependency cycles, and generator load() methods that do not yield exactly once |
Exceptions raised by plugins themselves are passed through unchanged.