Errors and Lifecycle Events¶
Two policies¶
Plushy 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 plushy 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. Pass strict=True:
from plushy 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)
try:
pm.load_all(strict=True)
except ExceptionGroup as group:
for error in group.exceptions:
print(error) # acme.plugins:bad failed to load: RuntimeError('misconfigured')
assert pm.state("good") is PluginState.LOADED
load_all(strict=True) still loads every plugin it can, then raises an ExceptionGroup holding one PluginError per failed plugin. Each names its plugin and has the plugin's own exception as its __cause__. Disabled plugins, and plugins that decline in should_load(), are not failures. Handle the group with except ExceptionGroup or except* PluginError.
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 plushy 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.
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 Plushy'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, requirements that failed, and generator load() methods that do not yield exactly once |
Exceptions raised by plugins themselves are passed through unchanged.