Skip to content

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