Skip to content

Selecting a Backend

Some extension points need exactly one implementation, chosen by configuration: a storage backend, a mail transport, an authentication method. The host asks for that plugin by name and uses what its load() returns.

from pluxeo import Plugin, PluginManager


class MemoryStorage(Plugin):
    namespace = "acme.storage"
    name = "memory"

    def load(self):
        return {}  # stands for a real backend object


class S3Storage(Plugin):
    namespace = "acme.storage"
    name = "s3"

    def load(self):
        import boto3  # only imported if this backend is chosen

        return boto3.client("s3")


pm = PluginManager("acme.storage", discover=False)
pm.register(MemoryStorage)
pm.register(S3Storage)

backend = pm.load("memory")  # in practice: pm.load(settings.STORAGE_BACKEND)
assert pm.load("memory") is backend  # cached

Only the chosen plugin is instantiated and imported. The others stay discovered and cost nothing.

Caching

By default a manager keeps one instance per plugin and returns the same load result on every pm.load(name); load() runs once. With PluginManager(..., cache=False), every pm.load(name) creates a new instance and runs load() again (cleaning up the previous load first, if load() is a generator). Use that when the host manages the objects' lifetime itself.

Errors

Situation pm.load(name) raises
No plugin of that name PluginNotFoundError
The plugin is disabled, or should_load() returned false PluginDisabledError
The plugin's import, contract check or load() fails the original exception; the plugin is marked ERRORED

A plugin can do both

A backend plugin may also implement hooks. The two channels are independent: what load() returns and which hooks the plugin implements never interact. See Concepts.

Typing

A contract checks the plugin object, not what its load() returns. To type the backend itself, annotate load()'s return type in each plugin and declare the expected type in the host:

from typing import Protocol


class Storage(Protocol):
    def get(self, key: str) -> bytes | None: ...
    def put(self, key: str, data: bytes) -> None: ...


def storage(pm) -> Storage:
    return pm.load(settings.STORAGE_BACKEND)

Your type checker then checks the host's use of the backend; checking each plugin's load() against Storage is the plugin author's type checker's job.