Plugin Classes and Functions¶
A plugin has an identity (namespace and name), a gate (should_load()) and an action (load()). It may also implement hooks. There are two ways to write one.
As a class¶
Subclass Plugin and set namespace and name as class attributes:
from pluxeo import Plugin
class JsonLogging(Plugin):
namespace = "acme.configurators"
name = "json_logging"
def load(self, app):
import logging
handler = logging.StreamHandler()
handler.setFormatter(logging.Formatter('{"msg": "%(message)s"}'))
app.logger.addHandler(handler)
name must be unique within the namespace. The manager creates the instance itself, by calling the class with no arguments, so __init__ must not require any.
As a function¶
For a plugin that only does something when loaded, decorate a function:
The plugin's name defaults to the function's name; pass name= to choose another. The function is called as the plugin's load(), and what it returns is the load result. The decorator returns the function unchanged, so it can still be called directly.
@plugin takes the same options a class can set:
from pluxeo import plugin
@plugin("acme.configurators", name="debug_toolbar", should_load=False, requires=("json_logging",))
def debug_toolbar(app): ...
should_load is a boolean or a function of no arguments returning one.
load(): the plugin's action¶
load() runs once when the plugin is loaded. It receives the arguments the host gave the manager:
from types import SimpleNamespace
from pluxeo import Plugin, PluginManager
class Banner(Plugin):
namespace = "acme.configurators"
name = "banner"
def load(self, app, *, verbose=False):
app.banner = "Welcome" + (" (verbose)" if verbose else "")
return app.banner
app = SimpleNamespace()
pm = PluginManager("acme.configurators", load_args=(app,), load_kwargs={"verbose": True}, discover=False)
pm.register(Banner)
assert pm.load("banner") == "Welcome (verbose)"
What load() returns is the plugin's load result: pm.load(name) hands it back to the host, which is how a plugin provides an object such as a storage backend (Selecting a Backend). Returning nothing is fine.
load() may also be a generator, yielding its result and cleaning up after the yield: see Cleanup and Dependencies.
should_load(): the plugin's gate¶
Override should_load() to let a plugin decline to load, for example when the configuration it needs is missing:
import os
from pluxeo import Plugin
class Sentry(Plugin):
namespace = "acme.configurators"
name = "sentry"
def should_load(self):
return "SENTRY_DSN" in os.environ
def load(self, app):
import sentry_sdk
sentry_sdk.init(os.environ["SENTRY_DSN"])
should_load() runs after the plugin is instantiated and before load(). A plugin that declines is marked DISABLED; load_all() skips it silently, and pm.load(name) raises PluginDisabledError.
should_load() is the plugin's own decision. When the host or its operator decides, use enablement instead.
Keep imports inside¶
Discovery never imports a plugin's module; loading does. But once a plugin is loaded, everything its module imports at the top is imported too. A plugin that pulls in a web framework or a database driver at module level makes every host that loads it pay for that, including a command-line tool that only needed one of its hooks. Import heavy dependencies inside load() or inside the hook that uses them, as the examples above do.
Hooks¶
A plugin implements hooks by marking methods with @hookimpl. See Hooks.