pluggy

pluggy is a minimalist plugin and hook-calling framework for Python, extracted from pytest to be reusable by any project that wants a plugin architecture. Projects define a HookspecMarker-decorated hook specification namespace, and plugins implement matching HookimplMarker-decorated hook implementations; a PluginManager registers plugins and dispatches calls to every implementation, collecting their results.

It is the core dependency underlying pytest, tox, and devpi’s plugin systems, and is deliberately small and dependency-free so it can be embedded in any project needing an extensible, third-party-plugin-friendly architecture without adopting a heavier framework.

What You Get

• A PluginManager for registering, unregistering, and blocking plugins by name
• HookspecMarker/HookimplMarker decorators to declare hook specifications and implementations under a project-specific namespace
• Call-time ordering controls (tryfirst, trylast, hookwrapper) for coordinating multiple plugin implementations of the same hook
• firstresult hooks that stop after the first non-None plugin result, alongside the default all-results-collected behavior
• A typed, py.typed-marked codebase with historical call tracing support for debugging plugin dispatch

Common Use Cases

• Building a pytest-style plugin ecosystem where third parties can hook into a tool’s behavior without modifying its core code
• Adding an extensible plugin architecture to a CLI tool or framework (as tox and devpi do) without pulling in a heavier plugin/DI framework
• Allowing multiple independently-developed plugins to all respond to the same lifecycle event and aggregating their results
• Providing library authors a battle-tested, dependency-free hook dispatch mechanism reused across the pytest ecosystem

Under The Hood

Architecture: The package is a small, focused module set under src/pluggy/: _hooks.py defines HookspecMarker, HookimplMarker, and the HookCaller/HookImpl machinery that stores registered implementations per hook name; _manager.py implements PluginManager, which owns the plugin registry and exposes hook.<name>(…) dynamic dispatch; _callers.py implements the actual call loop that invokes each registered implementation in tryfirst/trylast order and aggregates results (or short-circuits for firstresult hooks); _result.py wraps call outcomes/exceptions for hookwrapper implementations; _tracing.py adds optional call tracing for debugging. Tech Stack: Pure Python (99.6%) with zero runtime dependencies, targeting Python 3.10+; built with setuptools plus setuptools-scm for version management, tested with pytest/pytest-benchmark/coverage via tox, and pre-commit for style enforcement. Code Quality: Ships py.typed for full type-checker support, has a mature multi-year test suite (part of the pytest-dev organization’s rigorous CI/release process), and is classified as ‘Development Status :: 6 - Mature’ in its own PyPI metadata, reflecting its role as foundational, heavily-relied-upon infrastructure for the Python testing ecosystem. API Design: The hookspec/hookimpl decorator pattern is deliberately minimal, defining an extension point is a plain method with a decorator, and implementing it in a plugin requires no base-class inheritance, which keeps the boilerplate low, though the dynamic pm.hook.<name>(…) call style trades some static-analysis friendliness for that flexibility.