{"id":267,"library":"pluggy","title":"pluggy","description":"pluggy is the crystallized core of plugin management and hook calling for pytest, powering 1400+ pytest plugins and pytest itself. It provides HookspecMarker and HookimplMarker decorators to define typed hook contracts, a PluginManager to register plugins and dispatch calls, and supports hook ordering (tryfirst/trylast), firstresult short-circuiting, historic hooks, and new-style generator-based hook wrappers. Current stable version is 1.6.0 (released May 15, 2025); releases follow Semantic Versioning with breaking changes reserved for major version bumps.","status":"active","version":"1.6.0","language":"python","source_language":"en","source_url":"https://github.com/pytest-dev/pluggy","tags":["plugin","hooks","pytest","extensibility","architecture"],"install":[{"cmd":"pip install pluggy","lang":"bash","label":"pip"},{"cmd":"uv add pluggy","lang":"bash","label":"uv"}],"dependencies":[],"imports":[{"note":"Also accessible as pluggy.HookspecMarker. Only top-level pluggy exports are public API.","symbol":"HookspecMarker","correct":"from pluggy import HookspecMarker"},{"note":"Also accessible as pluggy.HookimplMarker. Only top-level pluggy exports are public API.","symbol":"HookimplMarker","correct":"from pluggy import HookimplMarker"},{"note":"Internal submodules (pluggy.manager, pluggy.hooks, pluggy.callers) are private (prefixed with _). Import only from the top-level pluggy namespace.","wrong":"from pluggy.manager import PluginManager","symbol":"PluginManager","correct":"from pluggy import PluginManager"},{"note":"Raised when a hookimpl fails validation at registration time, e.g. hookwrapper=True on a non-generator function.","symbol":"PluginValidationError","correct":"from pluggy import PluginValidationError"},{"note":"Used inside old-style hookwrappers (hookwrapper=True). The deprecated .result property was removed in 1.0.0; always call .get_result() which re-raises on failure.","symbol":"Result","correct":"from pluggy import Result"}],"quickstart":{"code":"import pluggy\n\n# Both markers MUST share the same project name as PluginManager\nhookspec = pluggy.HookspecMarker(\"myproject\")\nhookimpl = pluggy.HookimplMarker(\"myproject\")\n\n\nclass MySpec:\n    \"\"\"Hook specification namespace.\"\"\"\n\n    @hookspec\n    def process(self, value: int) -> int:\n        \"\"\"Transform a value. Each implementation's return is collected into a list.\"\"\"\n\n\nclass PluginA:\n    @hookimpl\n    def process(self, value: int) -> int:\n        return value * 2\n\n\nclass PluginB:\n    @hookimpl(tryfirst=True)  # runs before PluginA despite LIFO default\n    def process(self, value: int) -> int:\n        return value + 10\n\n\npm = pluggy.PluginManager(\"myproject\")\npm.add_hookspecs(MySpec)       # register the spec BEFORE plugins\npm.register(PluginA())\npm.register(PluginB())\n\n# Hook calls MUST use keyword arguments only\nresults = pm.hook.process(value=5)\nprint(results)  # [15, 10]  — PluginB (tryfirst) then PluginA, LIFO order\n\n# New-style wrapper (>=1.2.0): use wrapper=True, plain function with yield\nclass WrapperPlugin:\n    @hookimpl(wrapper=True)\n    def process(self, value: int) -> int:\n        print(\"before\")\n        result = yield  # receives return value of inner calls\n        print(\"after\")\n        return result\n\npm.register(WrapperPlugin())\nresults2 = pm.hook.process(value=3)\nprint(results2)\n","lang":"python","description":"Define a hook spec and two implementations, register them with a PluginManager scoped to a project name, then call the hook and collect results."},"warnings":[{"fix":"Import all symbols exclusively from the top-level pluggy namespace: from pluggy import PluginManager, HookspecMarker, HookimplMarker, PluginValidationError, Result.","message":"Internal submodules pluggy.callers, pluggy.manager, and pluggy.hooks are private. Importing from them (e.g. from pluggy.manager import PluginManager) will break across any release.","severity":"breaking","affected_versions":"<1.0.0 (made private in 1.0.0)"},{"fix":"Always pass hook arguments as keyword arguments: pm.hook.myhook(arg1=1, arg2=2).","message":"Hook calls must use keyword-only arguments. Calling pm.hook.myhook(1, 2) instead of pm.hook.myhook(arg1=1, arg2=2) raises TypeError.","severity":"breaking","affected_versions":"all"},{"fix":"Replace outcome.result with outcome.get_result(), which also re-raises any exception the hook raised.","message":"The _Result.result property was removed in 1.0.0. Code using outcome.result inside old-style hookwrappers will raise AttributeError.","severity":"breaking","affected_versions":"<1.0.0 (removed in 1.0.0)"},{"fix":"Upgrade to Python >=3.9 or pin pluggy<1.5 for Python 3.8 environments.","message":"Python 3.8 support was dropped in pluggy 1.5.0. Environments pinned to Python 3.8 must stay on pluggy <1.5.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Migrate hookwrapper=True generator functions to wrapper=True. The yield in new-style wrappers receives the result value directly, not a Result object.","message":"Old-style hook wrappers (hookwrapper=True) are soft-deprecated in favor of new-style wrappers (wrapper=True, added in 1.2.0). Old-style wrappers now emit PluggyTeardownRaisedWarning when an exception is raised during teardown.","severity":"deprecated","affected_versions":">=1.2.0"},{"fix":"Use @hookimpl(tryfirst=True) or @hookimpl(trylast=True) to explicitly control execution order, or @hookspec(firstresult=True) on the spec to stop after the first non-None result.","message":"Multiple hook implementations are called in Last In First Out (LIFO) order by default: the last-registered plugin runs first. Return values are collected into a list in that same order.","severity":"gotcha","affected_versions":"all"},{"fix":"Define the project_name as a module-level constant (e.g. PROJECT_NAME = 'myproject') and reference it in all three places to prevent typo-driven silent failures.","message":"HookspecMarker, HookimplMarker, and PluginManager must all be initialized with the SAME project_name string. A mismatch silently causes implementations to be ignored — no error is raised.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'1.6.0':65 '1400':16 '15':68 '2025':69 'architectur':86 'base':58 'break':75 'bump':81 'call':12,40 'chang':76 'circuit':49 'contract':32 'core':6 'crystal':5 'current':61 'decor':27 'defin':29 'dispatch':39 'extens':85 'firstresult':46 'follow':71 'generat':57 'generator-bas':56 'histor':50 'hook':11,31,43,51,59,83 'hookimplmark':26 'hookspecmark':24 'major':79 'manag':9 'may':67 'new':54 'new-styl':53 'order':44 'pluggi':1,2 'plugin':8,18,37,82 'pluginmanag':34 'power':15 'provid':23 'pytest':14,17,20,84 'regist':36 'releas':66,70 'reserv':77 'semant':72 'short':48 'short-circuit':47 'stabl':62 'style':55 'support':42 'tryfirst/trylast':45 'type':30 'version':63,73,80 'wrapper':60","created_at":"2026-03-28T04:29:48.412590+00:00","updated_at":"2026-04-16T18:04:19.093689+00:00","problems":[{"fix":"pip install pluggy","cause":"The 'pluggy' package is not installed in the current Python environment or there's an issue with the Python path.","error":"ModuleNotFoundError: No module named 'pluggy'"},{"fix":"Ensure that all hook implementations have a matching hook specification defined using `pm.add_hookspecs(MySpecClass)` and that their function signatures (name and arguments) are compatible. If the hook is optional, mark the hook implementation with `@pluggy.hookimpl(optionalhook=True)`.","cause":"A hook implementation (hookimpl) is registered for a hook name that does not have a corresponding hook specification (hookspec) defined in the plugin manager, or the hookimpl's signature does not match the hookspec.","error":"pluggy.manager.PluginValidationError: unknown hook 'your_hook_name' in plugin 'your_plugin_name'"},{"fix":"Rewrite the hook wrapper function to be a generator that contains exactly one `yield` statement. For example:\n```python\n@hookimpl(wrapper=True)\ndef my_hook_wrapper(arg1, arg2):\n    print('before hook')\n    outcome = yield\n    print('after hook')\n    # Optionally process or force result/exception\n    # result = outcome.get_result()\n    # outcome.force_result(new_result)\n```","cause":"A hook implementation decorated with `wrapper=True` (new style) or `hookwrapper=True` (old style) is not implemented as a Python generator function (i.e., it's missing a `yield` statement).","error":"pluggy.manager.PluginValidationError: Plugin 'your_plugin_name' for hook 'your_hook_name'\\nhookimpl definition: ...\\nDeclared as wrapper=True or hookwrapper=True but function is not a generator function"},{"fix":"Upgrade your `pluggy` package to the latest version, or to a version compatible with the dependent library (e.g., `pytest`).\n`pip install --upgrade pluggy`","cause":"This error typically occurs when an older version of `pluggy` is used with a library (like `pytest`) that expects a newer `pluggy` feature or attribute that was introduced in a later version (e.g., pluggy>=1.4.0).","error":"AttributeError: module 'pluggy' has no attribute 'PluggyTeardownRaisedWarning'"},{"fix":"Reinstall `pluggy` to ensure all its components are correctly placed. It's also advisable to check your Python environment's site-packages for any conflicting files or directories named `pluggy` or `pluggy.py`.\n`pip uninstall pluggy`\n`pip install pluggy`","cause":"This usually indicates a corrupted installation, a conflict with another package that might shadow `pluggy`, or an attempt to import from an incorrect location. While `HookspecMarker` is a core `pluggy` component, this specific import error suggests the `pluggy` package itself might be misconfigured.","error":"ImportError: cannot import name 'HookspecMarker' from 'pluggy'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"1.6.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/pluggy/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}