Skip to content

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 marked ERRORED, its exception is kept, and the other plugins load. A plugin that is disabled, or declines in should_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.