Skip to content

Pluggy vs. Plushy

Short version: Pluggy is a hook caller. Plushy is the plugin framework around it. Plushy 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, Plushy adds.

Pluggy : Plushy :: WSGI : a web framework.

Side by side

Capability Pluggy Plushy
Sync hook dispatch (multicall, firstresult, wrappers, historic, ordering) ✅ ✅ (via Pluggy)
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 single place to add scoped instantiation (dependency injection) ❌ ✅ (every instance comes from a factory; no container yet)

What Plushy actually adds

1. Discovery + lifecycle

Pluggy hands you a PluginManager and expects you to find plugins yourself and register instantiated objects. Plushy 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

# plushy
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. Plushy ships a small async caller over Pluggy's registry, with the same plugins, hookspecs and 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 Plushy'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. Plushy 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 Plushy.

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 need no discovery at all, because 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: should_load gates, per-stage error isolation and listeners would go unused.
  • 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

Plushy depends only on Pluggy, which itself has no dependencies. The async caller is about 115 lines of Plushy's own. Discovery, lifecycle, contracts, enablement, namespaces and listeners are code Pluggy leaves to each application, which otherwise writes it for itself.

Plushy embeds Pluggy as its dispatch engine. Its own value lies in everything around dispatch.