Concepts¶
The vocabulary¶
- Namespace
- A string naming a group of plugins, such as
"acme.renderers". It is also the entry-point group plugins declare themselves in. Everything in pluxeo is scoped to one namespace. - Plugin
- An object with a
namespace, aname, ashould_load()method and aload()method. It may also carry hook implementations. Write one as a subclass ofPlugin, or as a function decorated with@plugin. - PluginManager
- Owns exactly one namespace. It discovers the plugins of that namespace, loads them, keeps their state, and calls their hooks. An application with several kinds of plugins has one manager per kind.
- Hook
- A named extension point. The host declares a hookspec (the signature, and how results combine); plugins provide hookimpls. One call from the host reaches every active plugin.
- Contract
- An optional
typing.Protocolthat every plugin of a namespace must satisfy, checked when each plugin loads.
Two ways a host uses a plugin¶
pluxeo supports two styles, which can be mixed freely, even on one plugin:
- Pull: the host asks for one plugin by name and uses what its
load()returns.backend = pm.load("s3"). See Selecting a Backend. - Push: the host calls a hook, and every loaded, enabled plugin that implements it answers.
pm.hook.render_block(block=b). See Hooks.
The lifecycle¶
- Discovered. The manager knows the plugin's name and how to create it. No plugin code has been imported.
- Instantiated. The plugin's factory has run: its module is imported and an instance exists. The contract, if any, is checked here.
- Loaded.
should_load()returned true andload()ran. Its hooks are now live.
From there, disable() takes the plugin out of dispatch without destroying it, and unload() runs its cleanup and returns it to discovered. A failure at any stage marks it ERRORED.
One rule ties the lifecycle to hooks, and pluxeo guarantees it at every step:
The dispatch rule
A plugin's hooks are called if and only if the plugin is loaded and enabled.
A plugin that was only discovered, that opted out, that failed, or that the host disabled is never called. And nothing is loaded behind your back: calling a hook does not load plugins. You call load_all() (or pass eager=True).
Order¶
Plugins are discovered and loaded in name order, so a given set of plugins behaves the same on every machine. A plugin's declared requirements are loaded before it, whatever their names. Hooks are called in reverse load order, as in Pluggy (the most recently registered implementation first), adjusted by tryfirst, trylast and wrappers.