Skip to content

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:

from plushy import plugin


@plugin("acme.configurators")
def tracing(app):
    app.tracing = True

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.