Rename _HookRelay -> HookRelay, export it as pluggy.HookRelay

For typing purposes, refs #428.

The old name `pluggy._hooks._HookRelay` is kept for backward
compatibility, no reason to break the "offenders" who have imported it
before.

Author: bluetech

docs/api_reference.rst

@@ -26,7 +26,7 @@ API Reference
     :show-inheritance:
     :members:
 
-.. autoclass:: pluggy._hooks._HookRelay()
+.. autoclass:: pluggy.HookRelay()
     :members:
 
     .. data:: <hook name>

docs/index.rst

@@ -743,8 +743,8 @@ a :py:class:`pluggy.HookCaller` which in turn *loops* through the
 ``1:N`` registered *hookimpls* and calls them in sequence.
 
 Every :py:class:`~pluggy.PluginManager` has a ``hook`` attribute
-which is an instance of this :py:class:`pluggy._hooks._HookRelay`.
-The :py:class:`~pluggy._hooks._HookRelay` itself contains references
+which is an instance of :py:class:`pluggy.HookRelay`.
+The :py:class:`~pluggy.HookRelay` itself contains references
 (by hook name) to each registered *hookimpl*'s :py:class:`~pluggy.HookCaller` instance.
 
 More practically you call a *hook* like so:

src/pluggy/__init__.py

@@ -10,11 +10,12 @@
     "PluginValidationError",
     "HookCaller",
     "HookCallError",
+    "HookRelay",
     "HookspecMarker",
     "HookimplMarker",
     "Result",
 ]
 
 from ._manager import PluginManager, PluginValidationError
 from ._result import HookCallError, Result
-from ._hooks import HookspecMarker, HookimplMarker, HookCaller
+from ._hooks import HookspecMarker, HookimplMarker, HookCaller, HookRelay

src/pluggy/_hooks.py

@@ -341,7 +341,7 @@ def varnames(func: object) -> tuple[tuple[str, ...], tuple[str, ...]]:
     return args, kwargs
 
 
-class _HookRelay:
+class HookRelay:
     """Hook holder object for performing 1:N hook calls where N is the number
     of registered plugins."""
 
@@ -356,6 +356,10 @@ def __getattr__(self, name: str) -> HookCaller:
             ...
 
 
+# Historical name (pluggy<=1.2), kept for backward compatibility.
+_HookRelay = HookRelay
+
+
 _CallHistory = List[Tuple[Mapping[str, object], Optional[Callable[[Any], None]]]]
 
 

src/pluggy/_manager.py

@@ -16,13 +16,13 @@
 from ._callers import _multicall
 from ._hooks import _HookImplFunction
 from ._hooks import _HookImplOpts
-from ._hooks import _HookRelay
 from ._hooks import _HookSpecOpts
 from ._hooks import _Namespace
 from ._hooks import _Plugin
 from ._hooks import _SubsetHookCaller
 from ._hooks import HookCaller
 from ._hooks import HookImpl
+from ._hooks import HookRelay
 from ._hooks import HookSpec
 from ._hooks import normalize_hookimpl_opts
 from ._result import Result
@@ -97,7 +97,7 @@ def __init__(self, project_name: str) -> None:
         self._plugin_distinfo: Final[list[tuple[_Plugin, DistFacade]]] = []
         #: The "hook relay", used to call a hook on all registered plugins.
         #: See :ref:`calling`.
-        self.hook: Final[_HookRelay] = _HookRelay()
+        self.hook: Final[HookRelay] = HookRelay()
         #: The tracing entry point. See :ref:`tracing`.
         self.trace: Final[_tracing.TagTracerSub] = _tracing.TagTracer().get(
             "pluginmanage"