Skip to content

Cleanup and Dependencies

Releasing what a plugin holds

A plugin that opens a connection, starts a thread or creates a temporary directory should release it when it is unloaded. Write load() as a generator: what it yields is the load result, and the code after the yield is the cleanup.

from pluxeo import Plugin, PluginManager


class Database(Plugin):
    namespace = "acme.services"
    name = "db"

    def load(self):
        conn = {"open": True}  # stands for a real connection
        yield conn  # the load result
        conn["open"] = False  # runs on unload


pm = PluginManager("acme.services", discover=False)
pm.register(Database)
conn = pm.load("db")
assert conn["open"]
pm.unload("db")
assert not conn["open"]

Setup and cleanup sit next to each other, the same shape as contextlib.contextmanager, so there is no separate uninstall method to keep in sync. The generator must yield exactly once; yielding never or twice raises PluginError.

pm.unload(name):

  1. unloads first the loaded plugins that require this one (see below), latest loaded first;
  2. takes the plugin out of hook dispatch, so it is no longer called while it cleans up;
  3. runs the code after the yield;
  4. forgets the instance and returns the plugin to DISCOVERED, so the next load() starts afresh.

pm.refresh() unloads every loaded plugin, in reverse load order, before discovering again. If a cleanup raises during refresh(), pluxeo warns and carries on with the others; unload() called directly lets the exception propagate.

unload() is not disable()

disable() only takes a plugin out of dispatch: the instance stays alive, nothing is cleaned up, and enable() puts it back as it was. unload() is the inverse of load(). See Enabling and Disabling.

Depending on another plugin

A plugin that needs another plugin of the same namespace to be loaded first lists it in requires:

from pluxeo import Plugin, PluginManager

log = []


class Cache(Plugin):
    namespace = "acme.services"
    name = "cache"
    requires = ("db",)

    def load(self):
        log.append("cache")


class Db(Plugin):
    namespace = "acme.services"
    name = "db"

    def load(self):
        log.append("db")


pm = PluginManager("acme.services", discover=False)
pm.register(Cache)
pm.register(Db)
pm.load_all()
assert log == ["db", "cache"]  # "cache" sorts first, but needs "db"

Requirements are loaded depth first and are transitive. load_all() still starts from name order; requirements pull their dependencies forward.

When a requirement cannot be loaded, loading the dependent fails:

  • a requirement that is not registered raises PluginNotFoundError, naming both plugins;
  • a requirement that is disabled, or declines in should_load(), raises PluginDisabledError, naming both;
  • a cycle raises PluginError with the chain, such as acme.services: plugin dependency cycle a -> b -> a;
  • a requirement whose own load() raises propagates that exception unchanged; the requirement is marked ERRORED.

In load_all(), these failures are contained: the rest of the plugins load. The dependent itself is currently left INSTANTIATED, with no error recorded on it (Known Limitations); check the requirement's state to find the cause.

Unloading respects dependencies

Unloading a plugin first unloads every loaded plugin that requires it, directly or not, latest loaded first. No plugin is left loaded holding something its dependency has already released. Plugins that do not depend on it stay loaded.

Unloading a plugin first unloads the plugins that depend on it, latest loaded first.