Replace complex _multicall wrapper logic with streamlined completion hook pattern

The _multicall function had intricate generator-based wrapper teardown logic
that was difficult to understand and maintain. This refactoring introduces
a completion hook pattern that simplifies the wrapper invocation process.

Key changes:
- Add CompletionHook type alias with (result, exception) -> (result, exception) signature
- Implement setup_and_get_completion_hook() method in WrapperImpl class
- Unify old-style and new-style wrapper handling using run_old_style_hookwrapper adapter
- Replace complex teardown loop with simple completion hook calls
- Adjust warning stacklevel from 6 to 7 for correct source attribution

The completion hook pattern makes wrapper teardown explicit and easier to debug
while maintaining full backward compatibility with both hookwrapper and wrapper
implementations.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: RonnyPfannschmidt

src/pluggy/_callers.py

@@ -70,7 +70,7 @@ def _warn_teardown_exception(
     msg += f"Plugin: {hook_impl.plugin_name}, Hook: {hook_name}\n"
     msg += f"{type(e).__name__}: {e}\n"
     msg += "For more information see https://pluggy.readthedocs.io/en/stable/api_reference.html#pluggy.PluggyTeardownRaisedWarning"  # noqa: E501
-    warnings.warn(PluggyTeardownRaisedWarning(msg), stacklevel=6)
+    warnings.warn(PluggyTeardownRaisedWarning(msg), stacklevel=7)
 
 
 def _multicall(
@@ -89,76 +89,40 @@ def _multicall(
     results: list[object] = []
     exception = None
 
-    try:  # run impl and wrapper setup functions in a loop
-        teardowns: list[Teardown] = []
-        try:
-            for hook_impl in reversed(wrapper_impls):
-                args = hook_impl._get_call_args(caller_kwargs)
-
-                if hook_impl.hookwrapper:
-                    function_gen = run_old_style_hookwrapper(hook_impl, hook_name, args)
-                    next(function_gen)  # first yield
-                    teardowns.append(function_gen)
-                elif hook_impl.wrapper:
-                    try:
-                        # If this cast is not valid, a type error is raised below,
-                        # which is the desired response.
-                        res = hook_impl.function(*args)
-                        function_gen = cast(Generator[None, object, object], res)
-                        next(function_gen)  # first yield
-                        teardowns.append(function_gen)
-                    except StopIteration:
-                        _raise_wrapfail(function_gen, "did not yield")
-
-            # Process normal implementations (in reverse order for correct execution)
-            # Caller ensures normal_impls contains only non-wrapper implementations
-            for normal_impl in reversed(normal_impls):
-                args = normal_impl._get_call_args(caller_kwargs)
-
-                res = normal_impl.function(*args)
-                if res is not None:
-                    results.append(res)
-                    if firstresult:  # halt further impl calls
-                        break
-        except BaseException as exc:
-            exception = exc
-    finally:
-        if firstresult:  # first result hooks return a single value
-            result = results[0] if results else None
-        else:
-            result = results
-
-        # run all wrapper post-yield blocks
-        for teardown in reversed(teardowns):
-            try:
-                if exception is not None:
-                    try:
-                        teardown.throw(exception)
-                    except RuntimeError as re:
-                        # StopIteration from generator causes RuntimeError
-                        # even for coroutine usage - see #544
-                        if (
-                            isinstance(exception, StopIteration)
-                            and re.__cause__ is exception
-                        ):
-                            teardown.close()
-                            continue
-                        else:
-                            raise
-                else:
-                    teardown.send(result)
-                # Following is unreachable for a well behaved hook wrapper.
-                # Try to force finalizers otherwise postponed till GC action.
-                # Note: close() may raise if generator handles GeneratorExit.
-                teardown.close()
-            except StopIteration as si:
-                result = si.value
-                exception = None
-                continue
-            except BaseException as e:
-                exception = e
-                continue
-            _raise_wrapfail(teardown, "has second yield")
+    # Set up wrapper completion hooks
+    from ._hook_callers import CompletionHook
+
+    completion_hooks: list[CompletionHook] = []
+
+    try:
+        # Set up all wrappers and collect their completion hooks
+        for wrapper_impl in reversed(wrapper_impls):
+            completion_hook = wrapper_impl.setup_and_get_completion_hook(
+                hook_name, caller_kwargs
+            )
+            completion_hooks.append(completion_hook)
+
+        # Process normal implementations (in reverse order for correct execution)
+        # Caller ensures normal_impls contains only non-wrapper implementations
+        for normal_impl in reversed(normal_impls):
+            args = normal_impl._get_call_args(caller_kwargs)
+            res = normal_impl.function(*args)
+            if res is not None:
+                results.append(res)
+                if firstresult:  # halt further impl calls
+                    break
+    except BaseException as exc:
+        exception = exc
+
+    # Determine final result before teardown
+    if firstresult:  # first result hooks return a single value
+        result = results[0] if results else None
+    else:
+        result = results
+
+    # Run completion hooks in reverse order (LIFO - Last In, First Out)
+    for completion_hook in reversed(completion_hooks):
+        result, exception = completion_hook(result, exception)
 
     if exception is not None:
         raise exception

src/pluggy/_hook_callers.py

@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Generator
 from collections.abc import Mapping
 from collections.abc import MutableSequence
 from collections.abc import Sequence
@@ -33,6 +34,12 @@
 
 _T_HookImpl = TypeVar("_T_HookImpl", bound="HookImpl")
 
+# Type alias for completion hook functions
+CompletionHook = Callable[
+    [object | list[object] | None, BaseException | None],
+    tuple[object | list[object] | None, BaseException | None],
+]
+
 
 def _insert_hookimpl_into_list(
     hookimpl: _T_HookImpl, target_list: MutableSequence[_T_HookImpl]
@@ -738,3 +745,75 @@ def __init__(
                 "Use HookImpl for normal implementations."
             )
         super().__init__(plugin, plugin_name, function, hook_impl_config)
+
+    def setup_and_get_completion_hook(
+        self, hook_name: str, caller_kwargs: Mapping[str, object]
+    ) -> CompletionHook:
+        """Set up wrapper and return a completion hook for teardown processing.
+
+        This method provides a streamlined way to handle wrapper setup and teardown.
+        Both old-style hookwrappers and new-style wrappers are handled uniformly
+        by converting old-style wrappers to the new protocol using
+        run_old_style_hookwrapper.
+
+        Args:
+            hook_name: Name of the hook being called
+            caller_kwargs: Keyword arguments passed to the hook call
+
+        Returns:
+            A completion hook function that handles the teardown process
+        """
+        args = self._get_call_args(caller_kwargs)
+
+        # Use run_old_style_hookwrapper for old-style, direct generator for new-style
+        if self.hookwrapper:
+            from ._callers import run_old_style_hookwrapper
+
+            wrapper_gen = run_old_style_hookwrapper(self, hook_name, args)
+        else:
+            # New-style wrapper handling
+            res = self.function(*args)
+            wrapper_gen = cast(Generator[None, object, object], res)
+
+        # Start the wrapper generator - this is where "did not yield" is checked
+        try:
+            next(wrapper_gen)  # first yield
+        except StopIteration:
+            from ._callers import _raise_wrapfail
+
+            _raise_wrapfail(wrapper_gen, "did not yield")
+
+        def completion_hook(
+            result: object | list[object] | None, exception: BaseException | None
+        ) -> tuple[object | list[object] | None, BaseException | None]:
+            """Unified completion hook for both old-style and new-style wrappers."""
+            try:
+                if exception is not None:
+                    try:
+                        wrapper_gen.throw(exception)
+                    except RuntimeError as re:
+                        # StopIteration from generator causes RuntimeError
+                        # even for coroutine usage - see #544
+                        if (
+                            isinstance(exception, StopIteration)
+                            and re.__cause__ is exception
+                        ):
+                            wrapper_gen.close()
+                            return result, exception
+                        else:
+                            raise
+                else:
+                    wrapper_gen.send(result)
+                # Following is unreachable for a well behaved hook wrapper.
+                # Try to force finalizers otherwise postponed till GC action.
+                # Note: close() may raise if generator handles GeneratorExit.
+                wrapper_gen.close()
+                from ._callers import _raise_wrapfail
+
+                _raise_wrapfail(wrapper_gen, "has second yield")
+            except StopIteration as si:
+                return si.value, None
+            except BaseException as e:
+                return result, e
+
+        return completion_hook