Architecture¶
Layers, not competitors¶
Python's plugin systems are usually compared as alternatives. They are better understood as answers to different questions, at different layers. pluxeo takes each layer from the system that handles it best, and builds the ones no system covers well.
| Layer | Question | Source |
|---|---|---|
| Discovery | Which plugins exist, without importing them? | pluxeo's own; Plux's build-time scan needs setuptools |
| Lifecycle | In what states does a plugin live; how are failures contained? | Plux |
| Dispatch | How does the host call N implementations and combine results? | Pluggy, embedded |
| Contracts | What shape must a plugin have, and when is it checked? | pluxeo's own, on typing.Protocol |
| Enablement | Who decides which plugins are active? | Trac |
| Removal | What undoes what a plugin did? | Cordis |
| Instantiation | How does a plugin get its dependencies? | one factory per plugin; a seam for dependency injection later |
The code¶
One package, pluxeo, with one private module per layer and __init__.py as the only public surface. Every variation point is a Protocol with a default implementation: DiscoverySource, EnablementPolicy, LifecycleListener, and the contract policy. PluginManager owns one namespace and composes the rest. The whole library is about 1,200 lines on top of Pluggy.
The rules¶
These are the invariants the design rests on. Each is enforced by the test suite.
1. Hooks are live exactly while a plugin is loaded and enabled. A plugin's hook implementations are registered with Pluggy when it finishes loading and removed when it is disabled, unloaded or fails. Nothing else is ever called. Calling a hook never loads a plugin: loading would import code, and that must be the host's explicit choice.
2. Pull and push are independent.
What load() returns and which hooks a plugin implements never interact. This is where Plux's model (load a plugin, use its result) and Pluggy's (broadcast a call) meet without either constraining the other.
3. One namespace per manager, one Pluggy manager per pluxeo manager. Pluggy separates projects with a marker name. pluxeo uses a single marker name and gets isolation structurally: each manager owns its own Pluggy registry, created only when a hookspec is given, and refuses plugins of another namespace. Two namespaces can use the same hook names without interference, and namespaces without hooks pay nothing for them.
4. Deterministic order.
Discovery and load_all() sort by name; requirements are loaded first; hooks run in reverse load order, as in Pluggy. The same plugins behave the same on every machine, whatever order the packaging tools list them in.
5. Contracts and hookspecs are complementary. Pluggy checks hook signatures when a plugin joins dispatch. The contract checks the rest of the plugin object when it loads. Neither replaces the other.
6. Single calls propagate; batches contain.
load(name) lets exceptions through; load_all() marks the plugin ERRORED, keeps the exception, and carries on. Listeners cannot affect the plugin they observe: their exceptions become warnings.
7. Teardown is the inverse of loading, not of disabling.
A generator load() keeps its cleanup next to its setup. unload() runs it, after unloading dependents and after leaving dispatch, so rule 1 holds during cleanup. disable() only toggles dispatch.
8. Requirements are declarations.
should_load() is a predicate the manager can call but not inspect. requires is data it can read, so it loads dependencies first and detects cycles.
9. Every instance comes from a factory. The manager never calls a plugin class directly; it calls the spec's factory. That single indirection is where a dependency-injection container can later take over instantiation without changing plugin code.
Async¶
Pluggy is synchronous. pluxeo adds its own async caller over Pluggy's registry: sequential by default, concurrent on request, without wrappers. Loading stays synchronous: an asynchronous lifecycle would make the manager own tasks, with cancellation and transitions in flight, a cost not worth paying for work that happens at startup.