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.