Rename _HookCaller -> HookCaller, export as pluggy.HookCaller

For typing purposes, refs #428.

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

Author: bluetech

docs/api_reference.rst

@@ -18,7 +18,7 @@ API Reference
     :show-inheritance:
     :members:
 
-.. autoclass:: pluggy._hooks._HookCaller()
+.. autoclass:: pluggy.HookCaller()
     :members:
     :special-members: __call__
 
@@ -31,6 +31,6 @@ API Reference
 
     .. data:: <hook name>
 
-        :type: _HookCaller
+        :type: HookCaller
 
         The caller for the hook with the given name.

docs/index.rst

@@ -615,7 +615,7 @@ Also see the :ref:`pytest:firstresult` section in the ``pytest`` docs.
 Historic hooks
 ^^^^^^^^^^^^^^
 You can mark a *hookspec* as being *historic* meaning that the hook
-can be called with :py:meth:`~pluggy._hooks._HookCaller.call_historic()` **before**
+can be called with :py:meth:`~pluggy.HookCaller.call_historic()` **before**
 having been registered:
 
 .. code-block:: python
@@ -739,13 +739,13 @@ The core functionality of ``pluggy`` enables an extension provider
 to override function calls made at certain points throughout a program.
 
 A particular *hook* is invoked by calling an instance of
-a :py:class:`pluggy._hooks._HookCaller` which in turn *loops* through the
+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
-(by hook name) to each registered *hookimpl*'s :py:class:`~pluggy._hooks._HookCaller` instance.
+(by hook name) to each registered *hookimpl*'s :py:class:`~pluggy.HookCaller` instance.
 
 More practically you call a *hook* like so:
 
@@ -761,7 +761,7 @@ More practically you call a *hook* like so:
     pm.add_hookspecs(mypluginspec)
     pm.register(myplugin)
 
-    # we invoke the _HookCaller and thus all underlying hookimpls
+    # we invoke the HookCaller and thus all underlying hookimpls
     result_list = pm.hook.myhook(config=config, args=sys.argv)
 
 Note that you **must** call hooks using keyword :std:term:`python:argument` syntax!
@@ -880,7 +880,7 @@ only useful if you expect that some *hookimpls* may be registered **after** the
 hook is initially invoked.
 
 Historic hooks must be :ref:`specially marked <historic>` and called
-using the :py:meth:`~pluggy._hooks._HookCaller.call_historic()` method:
+using the :py:meth:`~pluggy.HookCaller.call_historic()` method:
 
 .. code-block:: python
 
@@ -901,8 +901,8 @@ using the :py:meth:`~pluggy._hooks._HookCaller.call_historic()` method:
     # historic callback is invoked here
     pm.register(mylateplugin)
 
-Note that if you :py:meth:`~pluggy._hooks._HookCaller.call_historic()`
-the :py:class:`~pluggy._hooks._HookCaller` (and thus your calling code)
+Note that if you :py:meth:`~pluggy.HookCaller.call_historic()`
+the :py:class:`~pluggy.HookCaller` (and thus your calling code)
 can not receive results back from the underlying *hookimpl* functions.
 Instead you can provide a *callback* for processing results (like the
 ``callback`` function above) which will be called as each new plugin
@@ -919,19 +919,19 @@ Calling with extras
 -------------------
 You can call a hook with temporarily participating *implementation* functions
 (that aren't in the registry) using the
-:py:meth:`pluggy._hooks._HookCaller.call_extra()` method.
+:py:meth:`pluggy.HookCaller.call_extra()` method.
 
 
 Calling with a subset of registered plugins
 -------------------------------------------
 You can make a call using a subset of plugins by asking the
 :py:class:`~pluggy.PluginManager` first for a
-:py:class:`~pluggy._hooks._HookCaller` with those plugins removed
+:py:class:`~pluggy.HookCaller` with those plugins removed
 using the :py:meth:`pluggy.PluginManager.subset_hook_caller()` method.
 
-You then can use that :py:class:`_HookCaller <pluggy._hooks._HookCaller>`
-to make normal, :py:meth:`~pluggy._hooks._HookCaller.call_historic`, or
-:py:meth:`~pluggy._hooks._HookCaller.call_extra` calls as necessary.
+You then can use that :py:class:`~pluggy.HookCaller`
+to make normal, :py:meth:`~pluggy.HookCaller.call_historic`, or
+:py:meth:`~pluggy.HookCaller.call_extra` calls as necessary.
 
 
 .. _tracing:

src/pluggy/__init__.py

@@ -8,6 +8,7 @@
 __all__ = [
     "PluginManager",
     "PluginValidationError",
+    "HookCaller",
     "HookCallError",
     "HookspecMarker",
     "HookimplMarker",
@@ -16,4 +17,4 @@
 
 from ._manager import PluginManager, PluginValidationError
 from ._result import HookCallError, Result
-from ._hooks import HookspecMarker, HookimplMarker
+from ._hooks import HookspecMarker, HookimplMarker, HookCaller

src/pluggy/_callers.py

@@ -33,7 +33,7 @@ def _multicall(
     """Execute a call into multiple python functions/methods and return the
     result(s).
 
-    ``caller_kwargs`` comes from _HookCaller.__call__().
+    ``caller_kwargs`` comes from HookCaller.__call__().
     """
     __tracebackhide__ = True
     results: list[object] = []

src/pluggy/_hooks.py

@@ -352,14 +352,14 @@ def __init__(self) -> None:
 
     if TYPE_CHECKING:
 
-        def __getattr__(self, name: str) -> _HookCaller:
+        def __getattr__(self, name: str) -> HookCaller:
             ...
 
 
 _CallHistory = List[Tuple[Mapping[str, object], Optional[Callable[[Any], None]]]]
 
 
-class _HookCaller:
+class HookCaller:
     """A caller of all registered implementations of a hook specification."""
 
     __slots__ = (
@@ -446,7 +446,7 @@ def _add_hookimpl(self, hookimpl: HookImpl) -> None:
             self._hookimpls.insert(i + 1, hookimpl)
 
     def __repr__(self) -> str:
-        return f"<_HookCaller {self.name!r}>"
+        return f"<HookCaller {self.name!r}>"
 
     def _verify_all_args_are_provided(self, kwargs: Mapping[str, object]) -> None:
         # This is written to avoid expensive operations when not needed.
@@ -553,11 +553,15 @@ def _maybe_apply_history(self, method: HookImpl) -> None:
                     result_callback(res[0])
 
 
-class _SubsetHookCaller(_HookCaller):
+# Historical name (pluggy<=1.2), kept for backward compatibility.
+_HookCaller = HookCaller
+
+
+class _SubsetHookCaller(HookCaller):
     """A proxy to another HookCaller which manages calls to all registered
     plugins except the ones from remove_plugins."""
 
-    # This class is unusual: in inhertits from `_HookCaller` so all of
+    # This class is unusual: in inhertits from `HookCaller` so all of
     # the *code* runs in the class, but it delegates all underlying *data*
     # to the original HookCaller.
     # `subset_hook_caller` used to be implemented by creating a full-fledged
@@ -572,7 +576,7 @@ class _SubsetHookCaller(_HookCaller):
         "_remove_plugins",
     )
 
-    def __init__(self, orig: _HookCaller, remove_plugins: AbstractSet[_Plugin]) -> None:
+    def __init__(self, orig: HookCaller, remove_plugins: AbstractSet[_Plugin]) -> None:
         self._orig = orig
         self._remove_plugins = remove_plugins
         self.name = orig.name  # type: ignore[misc]

src/pluggy/_manager.py

@@ -14,14 +14,14 @@
 
 from . import _tracing
 from ._callers import _multicall
-from ._hooks import _HookCaller
 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 HookSpec
 from ._hooks import normalize_hookimpl_opts
@@ -156,9 +156,9 @@ def register(self, plugin: _Plugin, name: str | None = None) -> str | None:
                 method: _HookImplFunction[object] = getattr(plugin, name)
                 hookimpl = HookImpl(plugin, plugin_name, method, hookimpl_opts)
                 name = hookimpl_opts.get("specname") or name
-                hook: _HookCaller | None = getattr(self.hook, name, None)
+                hook: HookCaller | None = getattr(self.hook, name, None)
                 if hook is None:
-                    hook = _HookCaller(name, self._hookexec)
+                    hook = HookCaller(name, self._hookexec)
                     setattr(self.hook, name, hook)
                 elif hook.has_spec():
                     self._verify_hook(hook, hookimpl)
@@ -242,9 +242,9 @@ def add_hookspecs(self, module_or_class: _Namespace) -> None:
         for name in dir(module_or_class):
             spec_opts = self.parse_hookspec_opts(module_or_class, name)
             if spec_opts is not None:
-                hc: _HookCaller | None = getattr(self.hook, name, None)
+                hc: HookCaller | None = getattr(self.hook, name, None)
                 if hc is None:
-                    hc = _HookCaller(name, self._hookexec, module_or_class, spec_opts)
+                    hc = HookCaller(name, self._hookexec, module_or_class, spec_opts)
                     setattr(self.hook, name, hc)
                 else:
                     # Plugins registered this hook without knowing the spec.
@@ -311,7 +311,7 @@ def get_name(self, plugin: _Plugin) -> str | None:
                 return name
         return None
 
-    def _verify_hook(self, hook: _HookCaller, hookimpl: HookImpl) -> None:
+    def _verify_hook(self, hook: HookCaller, hookimpl: HookImpl) -> None:
         if hook.is_historic() and (hookimpl.hookwrapper or hookimpl.wrapper):
             raise PluginValidationError(
                 hookimpl.plugin,
@@ -364,7 +364,7 @@ def check_pending(self) -> None:
         :exc:`PluginValidationError`."""
         for name in self.hook.__dict__:
             if name[0] != "_":
-                hook: _HookCaller = getattr(self.hook, name)
+                hook: HookCaller = getattr(self.hook, name)
                 if not hook.has_spec():
                     for hookimpl in hook.get_hookimpls():
                         if not hookimpl.optionalhook:
@@ -411,7 +411,7 @@ def list_name_plugin(self) -> list[tuple[str, _Plugin]]:
         """Return a list of (name, plugin) pairs for all registered plugins."""
         return list(self._name2plugin.items())
 
-    def get_hookcallers(self, plugin: _Plugin) -> list[_HookCaller] | None:
+    def get_hookcallers(self, plugin: _Plugin) -> list[HookCaller] | None:
         """Get all hook callers for the specified plugin.
 
         :returns:
@@ -491,11 +491,11 @@ def after(
 
     def subset_hook_caller(
         self, name: str, remove_plugins: Iterable[_Plugin]
-    ) -> _HookCaller:
-        """Return a proxy :py:class:`._hooks._HookCaller` instance for the named
+    ) -> HookCaller:
+        """Return a proxy :class:`~pluggy.HookCaller` instance for the named
         method which manages calls to all registered plugins except the ones
         from remove_plugins."""
-        orig: _HookCaller = getattr(self.hook, name)
+        orig: HookCaller = getattr(self.hook, name)
         plugins_to_remove = {plug for plug in remove_plugins if hasattr(plug, name)}
         if plugins_to_remove:
             return _SubsetHookCaller(orig, plugins_to_remove)

testing/test_hookcaller.py

@@ -9,15 +9,15 @@
 from pluggy import HookspecMarker
 from pluggy import PluginManager
 from pluggy import PluginValidationError
-from pluggy._hooks import _HookCaller
+from pluggy._hooks import HookCaller
 from pluggy._hooks import HookImpl
 
 hookspec = HookspecMarker("example")
 hookimpl = HookimplMarker("example")
 
 
 @pytest.fixture
-def hc(pm: PluginManager) -> _HookCaller:
+def hc(pm: PluginManager) -> HookCaller:
     class Hooks:
         @hookspec
         def he_method1(self, arg: object) -> None:
@@ -31,7 +31,7 @@ def he_method1(self, arg: object) -> None:
 
 
 class AddMeth:
-    def __init__(self, hc: _HookCaller) -> None:
+    def __init__(self, hc: HookCaller) -> None:
         self.hc = hc
 
     def __call__(
@@ -57,15 +57,15 @@ def wrap(func: FuncT) -> FuncT:
 
 
 @pytest.fixture
-def addmeth(hc: _HookCaller) -> AddMeth:
+def addmeth(hc: HookCaller) -> AddMeth:
     return AddMeth(hc)
 
 
 def funcs(hookmethods: Sequence[HookImpl]) -> List[Callable[..., object]]:
     return [hookmethod.function for hookmethod in hookmethods]
 
 
-def test_adding_nonwrappers(hc: _HookCaller, addmeth: AddMeth) -> None:
+def test_adding_nonwrappers(hc: HookCaller, addmeth: AddMeth) -> None:
     @addmeth()
     def he_method1() -> None:
         pass
@@ -81,7 +81,7 @@ def he_method3() -> None:
     assert funcs(hc.get_hookimpls()) == [he_method1, he_method2, he_method3]
 
 
-def test_adding_nonwrappers_trylast(hc: _HookCaller, addmeth: AddMeth) -> None:
+def test_adding_nonwrappers_trylast(hc: HookCaller, addmeth: AddMeth) -> None:
     @addmeth()
     def he_method1_middle() -> None:
         pass
@@ -97,7 +97,7 @@ def he_method1_b() -> None:
     assert funcs(hc.get_hookimpls()) == [he_method1, he_method1_middle, he_method1_b]
 
 
-def test_adding_nonwrappers_trylast3(hc: _HookCaller, addmeth: AddMeth) -> None:
+def test_adding_nonwrappers_trylast3(hc: HookCaller, addmeth: AddMeth) -> None:
     @addmeth()
     def he_method1_a() -> None:
         pass
@@ -122,7 +122,7 @@ def he_method1_d() -> None:
     ]
 
 
-def test_adding_nonwrappers_trylast2(hc: _HookCaller, addmeth: AddMeth) -> None:
+def test_adding_nonwrappers_trylast2(hc: HookCaller, addmeth: AddMeth) -> None:
     @addmeth()
     def he_method1_middle() -> None:
         pass
@@ -138,7 +138,7 @@ def he_method1() -> None:
     assert funcs(hc.get_hookimpls()) == [he_method1, he_method1_middle, he_method1_b]
 
 
-def test_adding_nonwrappers_tryfirst(hc: _HookCaller, addmeth: AddMeth) -> None:
+def test_adding_nonwrappers_tryfirst(hc: HookCaller, addmeth: AddMeth) -> None:
     @addmeth(tryfirst=True)
     def he_method1() -> None:
         pass
@@ -154,7 +154,7 @@ def he_method1_b() -> None:
     assert funcs(hc.get_hookimpls()) == [he_method1_middle, he_method1_b, he_method1]
 
 
-def test_adding_wrappers_ordering(hc: _HookCaller, addmeth: AddMeth) -> None:
+def test_adding_wrappers_ordering(hc: HookCaller, addmeth: AddMeth) -> None:
     @addmeth(hookwrapper=True)
     def he_method1():
         yield
@@ -184,7 +184,7 @@ def he_method3():
     ]
 
 
-def test_adding_wrappers_ordering_tryfirst(hc: _HookCaller, addmeth: AddMeth) -> None:
+def test_adding_wrappers_ordering_tryfirst(hc: HookCaller, addmeth: AddMeth) -> None:
     @addmeth(hookwrapper=True, tryfirst=True)
     def he_method1():
         yield
@@ -200,7 +200,7 @@ def he_method3():
     assert funcs(hc.get_hookimpls()) == [he_method2, he_method1, he_method3]
 
 
-def test_adding_wrappers_complex(hc: _HookCaller, addmeth: AddMeth) -> None:
+def test_adding_wrappers_complex(hc: HookCaller, addmeth: AddMeth) -> None:
     assert funcs(hc.get_hookimpls()) == []
 
     @addmeth(hookwrapper=True, trylast=True)

testing/test_pluginmanager.py

@@ -276,7 +276,7 @@ def he_method1(self, arg):
 
 @pytest.mark.parametrize("result_callback", [True, False])
 def test_with_result_memorized(pm: PluginManager, result_callback: bool) -> None:
-    """Verify that ``_HookCaller._maybe_apply_history()`
+    """Verify that ``HookCaller._maybe_apply_history()`
     correctly applies the ``result_callback`` function, when provided,
     to the result from calling each newly registered hook.
     """