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):
- unloads first the loaded plugins that require this one (see below), latest loaded first;
- takes the plugin out of hook dispatch, so it is no longer called while it cleans up;
- runs the code after the
yield; - forgets the instance and returns the plugin to
DISCOVERED, so the nextload()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(), raisesPluginDisabledError, naming both; - a cycle raises
PluginErrorwith the chain, such asacme.services: plugin dependency cycle a -> b -> a; - a requirement whose own
load()raises propagates that exception unchanged; the requirement is markedERRORED.
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.