Pluggy vs. pluxeo¶
Short version: Pluggy is a hook caller. pluxeo is the plugin framework around it. pluxeo depends on Pluggy and uses it for what Pluggy is great at (sync dispatch — multicall, wrappers, validation, ordering knobs). Everything else in the table below, pluxeo adds.
Pluggy : pluxeo :: WSGI : a web framework.
Side by side¶
| Capability | Pluggy | pluxeo |
|---|---|---|
| Sync hook dispatch (multicall, firstresult, wrappers, ordering) | ✅ | ✅ (via Pluggy; historic hooks not yet, see Known Limitations) |
| Hookspec / hookimpl arg-subset validation | ✅ | ✅ (via Pluggy) |
Async hook dispatch (await pm.hook.x.aio(...)) |
❌ | ✅ |
Plugin discovery beyond a manual load_setuptools_entrypoints call |
❌ | ✅ runtime scan + opt-in build-time index + namespace-package mode + imperative register, with refresh() |
| Build-backend-agnostic discovery (uv_build / PDM / hatchling / setuptools) | n/a | ✅ |
Lifecycle — PluginSpec + factory + resolve → init → loaded state machine |
❌ (you register already-instantiated objects) | ✅ |
| Lazy import — discovery never imports plugin code | ❌ | ✅ (import deferred to load()) |
should_load() gate; per-stage error isolation |
❌ | ✅ |
Lifecycle listeners (on_resolve_*, on_init_*, on_load_*) |
❌ | ✅ |
| Namespace as a first-class runtime abstraction (config, discovery, enablement, contracts all keyed on it) | ⚠️ only project_name for marker scoping |
✅ |
Contracts — typing.Protocol checked when each plugin loads, over the whole plugin object (incl. non-hook members) |
❌ (validates hook signatures only) | ✅ (host-tunable policy) |
| Enablement — host-controlled, dynamic, dispatch-aware enable/disable per plugin/namespace | ⚠️ register/unregister only | ✅ (enable/disable, EnablementPolicy) |
Pull-style plugins (backend = pm.load("s3")) coexisting with push-style hooks on the same plugin |
❌ | ✅ (two-channels rule) |
| Deterministic discovery/dispatch order across environments | ⚠️ entry-point iteration order | ✅ (sorted by name) |
| Cleanup on unload, declared dependencies between plugins | ❌ | ✅ (generator load(), requires) |
| A seam for scoped instantiation (dependency injection) | ❌ | ✅ (every instance comes from a factory; no container yet) |
What pluxeo actually adds¶
1. Discovery + lifecycle¶
Pluggy hands you a PluginManager and expects you to find plugins yourself and register instantiated objects. pluxeo does the finding, the instantiation, the gating, the error isolation, and the lazy-import discipline.
# Pluggy
import importlib.metadata
pm = pluggy.PluginManager("acme")
pm.add_hookspecs(RendererSpec)
for ep in importlib.metadata.entry_points(group="acme.renderers"):
cls = ep.load() # imports the module now; no should_load gate
pm.register(cls()) # one error here crashes the loop
# pluxeo
pm = PluginManager("acme.renderers", hookspec=RendererSpec)
pm.load_all() # discovers, gates, instantiates, loads, isolates errors
2. Async dispatch as an equal citizen¶
Pluggy is sync-only. In an async context (FastAPI, Litestar) you'd wrap calls by hand and lose firstresult/ordering semantics in the bargain. pluxeo ships a small async caller over Pluggy's registry — same plugins, same hookspecs, same ordering knobs:
# Sync hosts (Flask, Django, CLI)
results = pm.hook.render_block(block=b)
# Async hosts (FastAPI, Litestar)
results = await pm.hook.render_block.aio(block=b)
Sync caller is Pluggy verbatim. Async caller is pluxeo's: sequential with .aio(), concurrent with .aio_gather() for order-independent calls.
3. Namespace, contracts, enablement, configuration¶
Pluggy gives you project_name as a marker-scoping detail. pluxeo makes the namespace the unit of everything:
pm = PluginManager(
"acme.renderers",
hookspec=RendererSpec,
contract=Renderer, # typing.Protocol, checked when each plugin loads
enablement=ConfigEnablement(), # host-controlled, dynamic, runtime toggle
listeners=[Telemetry()],
)
pm.disable("charts") # live; dispatch unregisters charts immediately
Hook-signature validation comes from Pluggy. The whole-object Protocol check, the dynamic enable/disable that flips dispatch participation, the runtime listener, and the namespace-scoped lifecycle policy are pluxeo.
When you only need Pluggy¶
Use Pluggy directly when all of the following hold:
- Sync only, no FastAPI/Litestar surface to extend.
- You manage plugin discovery and instantiation yourself (or you don't need to discover at all — you
register()the plugins by hand at startup). - A single hook namespace; no need for per-namespace contracts, enablement, or configuration.
- No lifecycle to speak of (no
should_loadgates, no per-stage error isolation, no listeners). - No need to clean up after plugins, or to load one before another.
This is the right call for libraries that embed a hook system (pytest, datasette, devpi). It's the wrong call for an application platform that wants plugins to drop in and the host to gate them dynamically.
Cost¶
One runtime dependency (Pluggy, itself zero-dep). The async caller is about 115 lines of pluxeo's own. Discovery, lifecycle, contracts, enablement, namespaces, listeners — code Pluggy doesn't try to provide and that every app builds for itself otherwise.
Pluggy isn't being wrapped — it's being embedded as the dispatch engine in a framework whose value is everything around dispatch.