Export HookImpl as pluggy.HookImpl

Used in hook monitoring and in `pm.hook.my_hook.get_hookimpls()`.

Refs #428.

Author: bluetech

docs/api_reference.rst

@@ -35,6 +35,9 @@ API Reference
     :show-inheritance:
     :members:
 
+.. autoclass:: pluggy.HookImpl()
+    :members:
+
 .. autoclass:: pluggy.HookspecOpts()
     :show-inheritance:
     :members:

docs/index.rst

@@ -966,11 +966,11 @@ The expected signature and default implementations for these functions is:
 
 .. code-block:: python
 
-    def before(hook_name, methods, kwargs):
+    def before(hook_name, hook_impls, kwargs):
         pass
 
 
-    def after(outcome, hook_name, methods, kwargs):
+    def after(outcome, hook_name, hook_impls, kwargs):
         pass
 
 Public API

src/pluggy/__init__.py

@@ -12,6 +12,7 @@
     "HookCallError",
     "HookspecOpts",
     "HookimplOpts",
+    "HookImpl",
     "HookRelay",
     "HookspecMarker",
     "HookimplMarker",
@@ -27,4 +28,5 @@
     HookRelay,
     HookspecOpts,
     HookimplOpts,
+    HookImpl,
 )

src/pluggy/_hooks.py

@@ -607,6 +607,8 @@ def __repr__(self) -> str:
 
 
 class HookImpl:
+    """A hook implementation in a :class:`HookCaller`."""
+
     __slots__ = (
         "function",
         "argnames",
@@ -628,15 +630,33 @@ def __init__(
         function: _HookImplFunction[object],
         hook_impl_opts: HookimplOpts,
     ) -> None:
+        """:meta private:"""
+        #: The hook implementation function.
         self.function: Final = function
-        self.argnames, self.kwargnames = varnames(self.function)
+        argnames, kwargnames = varnames(self.function)
+        #: The positional parameter names of ``function```.
+        self.argnames = argnames
+        #: The keyword parameter names of ``function```.
+        self.kwargnames = kwargnames
+        #: The plugin which defined this hook implementation.
         self.plugin = plugin
+        #: The :class:`HookimplOpts` used to configure this hook implementation.
         self.opts = hook_impl_opts
+        #: The name of the plugin which defined this hook implementation.
         self.plugin_name = plugin_name
+        #: Whether the hook implementation is a :ref:`wrapper <hookwrapper>`.
         self.wrapper = hook_impl_opts["wrapper"]
+        #: Whether the hook implementation is an :ref:`old-style wrapper
+        #: <old_style_hookwrappers>`.
         self.hookwrapper = hook_impl_opts["hookwrapper"]
+        #: Whether validation against a hook specification is :ref:`optional
+        #: <optionalhook>`.
         self.optionalhook = hook_impl_opts["optionalhook"]
+        #: Whether to try to order this hook implementation :ref:`first
+        #: <callorder>`.
         self.tryfirst = hook_impl_opts["tryfirst"]
+        #: Whether to try to order this hook implementation :ref:`last
+        #: <callorder>`.
         self.trylast = hook_impl_opts["trylast"]
 
     def __repr__(self) -> str: