Skip to content

Plushy

Plushy: Typed plugins for Python Plushy: Typed plugins for Python

Plushy is a plugin framework for Python applications. A host application declares what plugins can do. Plugins ship as ordinary installed packages, which Plushy finds, loads and calls, while the host decides which ones run.

Version 0.1

This documents Plushy 0.1.0, its first release. Before 1.0, a minor release may change the API; the changelog says how.

from plushy import Plugin, PluginManager, hookimpl, hookspec


class Spec:
    @hookspec
    def render_block(self, block: dict) -> str | None: ...


class Charts(Plugin):
    namespace = "acme.renderers"
    name = "charts"

    @hookimpl
    def render_block(self, block):
        if block["type"] == "chart":
            return f"<figure data-chart='{block['spec']}'></figure>"
        return None


pm = PluginManager("acme.renderers", hookspec=Spec)
pm.register(Charts)  # or ship it as an entry point, and skip this line
pm.load_all()

print(pm.hook.render_block(block={"type": "chart", "spec": "x"}))
# ["<figure data-chart='x'></figure>"]

Four jobs, one library

  • Discover

    Plugins are installed packages declaring an entry point. Discovery reads package metadata and imports no plugin code until a plugin is loaded.

  • Load

    A defined lifecycle: gates, declared dependencies, cleanup on unload, and failures contained to the plugin that caused them.

  • Dispatch

    Typed hooks called on every active plugin, sync or async, with Pluggy's result modes and ordering.

  • Gate

    typing.Protocol contracts checked when a plugin loads, and host-controlled enable/disable that takes effect immediately.

Where to go next