pluginkit 0.3.1

A strictly-typed, generics-first plugin framework for Python 3.13: hooks with derived return types

pluginkit

A small, strictly-typed, generics-first plugin framework for Python 3.13+. Declare hook specifications, let plugins implement them, discover plugins via entry points - and, unlike untyped hook systems, get the right return type for every call, derived from the spec and checked by your type checker.

pm.caller(spec) hands back a caller whose result type matches the dispatch mode - list[R] for collecting, R | None for firstresult, R for pipeline - with no hand-annotations and no drift. Zero runtime dependencies, a py.typed marker, and a few readable files.

pip install pluginkit   # or: uv add pluginkit

from pluginkit import HookimplMarker, HookspecMarker, PluginManager

hookspec = HookspecMarker("greeter")
hookimpl = HookimplMarker("greeter")


class Specs:
    @staticmethod
    @hookspec
    def greeting(name: str) -> str:
        """Return a greeting for the given name."""


class Casual:
    @hookimpl
    def greeting(self, name: str) -> str:
        return f"hey {name}!"


pm = PluginManager("greeter")
pm.add_hookspecs(Specs)
pm.register(Casual(), name="casual")

greetings = pm.caller(Specs.greeting)(name="Ada")   # typed list[str] - derived, not asserted
print(greetings)                                     # ['hey Ada!']

What it supports

• collecting, firstresult, and pipeline (fold/middleware) hooks;
• call ordering with tryfirst / trylast, plus optionalhook and specname;
• generator wrappers that decorate results and observe exceptions safely;
• historic hooks replayed to plugins registered later;
• async dispatch via AsyncPluginManager (awaits coroutine impls);
• plugin lifecycle: register, unregister (by name or object), set_blocked, lookup, call_extra;
• registration-time validation and call-time argument checking (failures are loud);
• external plugin discovery via the stdlib importlib.metadata (no setuptools);
• thread-safe registry mutation.

Layout

src/pluginkit/             the library (pure - no demo code)
examples/                  everything that uses the library (not shipped):
  recipes/                   standalone single-file scripts, run directly
  tour/                      pluginkit-tour: a guided CLI walkthrough
  external-plugin/           a separate distribution discovered via entry points
docs/                      mkdocs + Material documentation
tests/                     library, tour, and recipe tests

Everything that demonstrates the library lives under examples/. The recipes are independent scripts you run on their own; the tour is a guided walkthrough on one host; the external-plugin shows cross-package discovery via entry points.

Use it

make install              # uv sync (library + tour + external plugin)
make test                 # pytest (framework, tour, examples)
make lint                 # ruff + mypy + pyright
make docs-serve           # serve the docs at http://127.0.0.1:8000
make docs-build           # build the docs (strict)

Two ways to learn it

The tour (examples/tour/) walks through one mechanism at a time on a single host:

make run                  # run every step
make run DEMO=wrapper      # run one
uv run pluginkit-tour list

The recipes apply the library to different realistic domains - see examples/:

uv run python examples/recipes/report_builder.py
uv run python examples/recipes/notification_router.py
uv run python examples/recipes/validation_rules.py
uv run python examples/recipes/app_lifecycle.py

Documentation

Full docs (concepts, one page per mechanism, production/hardening notes, and a generated API reference) live under docs/. Serve them with make docs-serve.

Is it production ready?

It is solid - exception-safe wrappers, fail-fast validation, lifecycle management, resilient discovery, thread-safe mutation, strict typing, and a test suite. But for anything you ship, prefer pluggy itself: it is maintained and battle tested by pytest, tox, and datasette. See docs/production/vs-pluggy.md for the honest inventory of what differs.