Skip to content

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, a name, a should_load() method and a load() method. It may also carry hook implementations. Write one as a subclass of Plugin, 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.Protocol that 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 two channels. Pulling one plugin's load result and pushing a call to every plugin's hooks are independent.

The lifecycle

Plugin states. Only a loaded, enabled plugin takes part in dispatch; unload() and refresh() return a plugin to its discovered state.

  1. Discovered. The manager knows the plugin's name and how to create it. No plugin code has been imported.
  2. Instantiated. The plugin's factory has run: its module is imported and an instance exists. The contract, if any, is checked here.
  3. Loaded. should_load() returned true and load() 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.