Pluggy: A Battle-Tested Foundation for Python Plugin Systems

When pytest needed a reliable way to manage its extensive plugin ecosystem, the developers created an internal solution that eventually evolved into Pluggy—a standalone library now powering plugin systems across the Python ecosystem. Rather than another framework promising revolution, Pluggy offers something more valuable: a battle-tested foundation for developers who want to add plugin support without reinventing the wheel. Its design reflects hard-won lessons from years of real-world use in one of Python's most popular testing tools.

At its core, Pluggy centers on hooks—well-defined extension points where host applications declare functionality and plugins provide implementations. The host uses HookspecMarker to declare hooks, while plugins use HookimplMarker to attach to them. This clean separation keeps concerns distinct: hosts define what can be extended, plugins define how. In the htmlize example from the original article, two hooks emerge naturally: one for handling custom markup roles (like :role:text``) and another for post-processing entire documents. Notably, these hooks return functions rather than values, allowing plugins to encapsulate complex logic while maintaining a simple invocation pattern for the host.

Plugin discovery remains intentionally flexible. While Pluggy includes built-in support for Python's entry point system (via load_setuptools_entrypoints), it doesn't mandate this approach. Hosts can register plugins manually through PluginManager.register() or implement custom discovery mechanisms. This pragmatism acknowledges that plugin systems serve diverse needs—from simple CLI tools to complex IDEs—while still providing a convenient default for the majority of use cases where both host and plugins follow standard Python packaging practices. The htmlize case study demonstrates this with a pyproject.toml entry point section that enables automatic discovery when plugins are installed alongside the host.

What makes Pluggy particularly instructive is how it aligns with fundamental plugin infrastructure concepts without imposing rigid constraints:

• Discovery: Delegated to the host, with entry points as a convenient opt-in mechanism
• Registration: Achieved through standard Python packaging metadata or manual register() calls
• Hooks: Implemented via Python decorators that feel idiomatic and require minimal boilerplate
• API Exposure: Leverages Python's import system—plugins directly access host modules when both are in the same environment
• Result Handling: Supports patterns like firstresult (stop at first non-None response) and ordered invocation (tryfirst/trylast)

The library's value becomes clear when considering the alternative: building a plugin system from scratch. As noted in the original fundamental concepts discussion, plugin frameworks often suffer from being "shallow APIs"—relatively simple to implement but tricky to get right at scale. Pluggy sidesteps this by providing exactly what's needed for advanced use cases: validated hook signatures, consistent result collection across multiple implementations, and wrapper hooks for cross-cutting concerns. These features address subtle pitfalls that emerge only after significant real-world usage.

For developers weighing the dependency trade-off, Pluggy's pedigree offers reassurance. Its extraction from pytest means it's already proven in a project with hundreds of plugins and millions of downloads. While trivial projects might still opt for a simpler solution, any application anticipating non-trivial extensibility benefits from starting with a foundation that's survived years of ecosystem evolution. The full implementation details and working examples are available in the original article, with the Pluggy repository providing the latest releases and documentation.