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 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:

from pluxeo 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 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.