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 plushy 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 runs as the plugin's load(); its return value 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 plushy 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 plushy 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 plushy 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.