Skip to content

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.

Each pluxeo layer and the system it borrows from.

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.

Plugin states.

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.

Three callers over one registry.