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: it yields the load result, and cleans up in the code after the yield.

from plushy 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(), Plushy warns and continues 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 plushy 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 that fails for any other reason raises PluginError naming both, with the requirement's exception as its cause.

The dependent is marked ERRORED and pm.error(name) returns that exception; the requirement keeps its own state and error. In load_all() these failures are contained like any other: the rest of the plugins load.

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.