Rename _Result -> Result, export as pluggy.Result

For typing purposes, refs #428.

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

Author: bluetech

CHANGELOG.rst

@@ -51,7 +51,7 @@ Features
 
 - `#260 <https://github.com/pytest-dev/pluggy/issues/260>`_: Added "new-style" hook wrappers, a simpler but equally powerful alternative to the existing ``hookwrapper=True`` wrappers.
 
-  New-style wrappers are generator functions, similarly to ``hookwrapper``, but do away with the :class:`result <pluggy._result._Result>` object.
+  New-style wrappers are generator functions, similarly to ``hookwrapper``, but do away with the :class:`result <pluggy.Result>` object.
   Instead, the return value is sent directly to the ``yield`` statement, or, if inner calls raised an exception, it is raised from the ``yield``.
   The wrapper is expected to return a value or raise an exception, which will become the result of the hook call.
 
@@ -64,7 +64,7 @@ Features
 - `#364 <https://github.com/pytest-dev/pluggy/issues/364>`_: Python 3.11 and 3.12 are now officially supported.
 
 
-- `#394 <https://github.com/pytest-dev/pluggy/issues/394>`_: Added the :meth:`~pluggy._result._Result.force_exception` method to ``_Result``.
+- `#394 <https://github.com/pytest-dev/pluggy/issues/394>`_: Added the :meth:`~pluggy.Result.force_exception` method to ``_Result``.
 
   ``force_exception`` allows (old-style) hookwrappers to force an exception or override/adjust an existing exception of a hook invocation,
   in a properly behaving manner. Using ``force_exception`` is preferred over raising an exception from the hookwrapper,

docs/api_reference.rst

@@ -14,7 +14,7 @@ API Reference
 
 .. autodecorator:: pluggy.HookimplMarker
 
-.. autoclass:: pluggy._result._Result()
+.. autoclass:: pluggy.Result()
     :show-inheritance:
     :members:
 

docs/index.rst

@@ -472,21 +472,21 @@ execution of all corresponding non-wrappper *hookimpls*.
         if config.use_defaults:
             outcome.force_result(defaults)
 
-The generator is :py:meth:`sent <python:generator.send>` a :py:class:`pluggy._result._Result` object which can
+The generator is :py:meth:`sent <python:generator.send>` a :py:class:`pluggy.Result` object which can
 be assigned in the ``yield`` expression and used to inspect
 the final result(s) or exceptions returned back to the caller using the
-:py:meth:`~pluggy._result._Result.get_result` method, override the result
-using the :py:meth:`~pluggy._result._Result.force_result`, or override
-the exception using the :py:meth:`~pluggy._result._Result.force_exception`
+:py:meth:`~pluggy.Result.get_result` method, override the result
+using the :py:meth:`~pluggy.Result.force_result`, or override
+the exception using the :py:meth:`~pluggy.Result.force_exception`
 method.
 
 .. note::
     Old-style hook wrappers can **not** return results; they can only modify
-    them using the :py:meth:`~pluggy._result._Result.force_result` API.
+    them using the :py:meth:`~pluggy.Result.force_result` API.
 
     Old-style Hook wrappers should **not** raise exceptions; this will cause
     further hookwrappers to be skipped. They should use
-    :py:meth:`~pluggy._result._Result.force_exception` to adjust the
+    :py:meth:`~pluggy.Result.force_exception` to adjust the
     exception.
 
 .. _specs:

src/pluggy/__init__.py

@@ -11,8 +11,9 @@
     "HookCallError",
     "HookspecMarker",
     "HookimplMarker",
+    "Result",
 ]
 
 from ._manager import PluginManager, PluginValidationError
-from ._result import HookCallError
+from ._result import HookCallError, Result
 from ._hooks import HookspecMarker, HookimplMarker

src/pluggy/_callers.py

@@ -12,14 +12,14 @@
 
 from ._hooks import HookImpl
 from ._result import _raise_wrapfail
-from ._result import _Result
 from ._result import HookCallError
+from ._result import Result
 
 
 # Need to distinguish between old- and new-style hook wrappers.
 # Wrapping one a singleton tuple is the fastest type-safe way I found to do it.
 Teardown = Union[
-    Tuple[Generator[None, _Result[object], None]],
+    Tuple[Generator[None, Result[object], None]],
     Generator[None, object, object],
 ]
 
@@ -58,7 +58,7 @@ def _multicall(
                         # If this cast is not valid, a type error is raised below,
                         # which is the desired response.
                         res = hook_impl.function(*args)
-                        wrapper_gen = cast(Generator[None, _Result[object], None], res)
+                        wrapper_gen = cast(Generator[None, Result[object], None], res)
                         next(wrapper_gen)  # first yield
                         teardowns.append((wrapper_gen,))
                     except StopIteration:
@@ -82,7 +82,7 @@ def _multicall(
         except BaseException as exc:
             exception = exc
     finally:
-        # Fast path - only new-style wrappers, no _Result.
+        # Fast path - only new-style wrappers, no Result.
         if only_new_style_wrappers:
             if firstresult:  # first result hooks return a single value
                 result = results[0] if results else None
@@ -117,11 +117,11 @@ def _multicall(
         # Slow path - need to support old-style wrappers.
         else:
             if firstresult:  # first result hooks return a single value
-                outcome: _Result[object | list[object]] = _Result(
+                outcome: Result[object | list[object]] = Result(
                     results[0] if results else None, exception
                 )
             else:
-                outcome = _Result(results, exception)
+                outcome = Result(results, exception)
 
             # run all wrapper post-yield blocks
             for teardown in reversed(teardowns):

src/pluggy/_hooks.py

@@ -23,7 +23,7 @@
 from typing import TypeVar
 from typing import Union
 
-from ._result import _Result
+from ._result import Result
 
 
 _T = TypeVar("_T")
@@ -34,7 +34,7 @@
     [str, Sequence["HookImpl"], Mapping[str, object], bool],
     Union[object, List[object]],
 ]
-_HookImplFunction = Callable[..., Union[_T, Generator[None, _Result[_T], None]]]
+_HookImplFunction = Callable[..., Union[_T, Generator[None, Result[_T], None]]]
 
 
 class _HookSpecOpts(TypedDict):
@@ -232,7 +232,7 @@ def __call__(  # noqa: F811
             needs to execute exactly one ``yield``. The code before the
             ``yield`` is run early before any non-hook-wrapper function is run.
             The code after the ``yield`` is run after all non-hook-wrapper
-            function have run  The ``yield`` receives a :class:`_Result` object
+            function have run  The ``yield`` receives a :class:`Result` object
             representing the exception or result outcome of the inner calls
             (including earlier hook wrapper calls). This option is mutually
             exclusive with ``wrapper``. See :ref:`old_style_hookwrapper`.

src/pluggy/_manager.py

@@ -25,11 +25,11 @@
 from ._hooks import HookImpl
 from ._hooks import HookSpec
 from ._hooks import normalize_hookimpl_opts
-from ._result import _Result
+from ._result import Result
 
 
 _BeforeTrace = Callable[[str, Sequence[HookImpl], Mapping[str, Any]], None]
-_AfterTrace = Callable[[_Result[Any], str, Sequence[HookImpl], Mapping[str, Any]], None]
+_AfterTrace = Callable[[Result[Any], str, Sequence[HookImpl], Mapping[str, Any]], None]
 
 
 def _warn_for_function(warning: Warning, function: Callable[..., object]) -> None:
@@ -439,7 +439,7 @@ def add_hookcall_monitoring(
         of HookImpl instances and the keyword arguments for the hook call.
 
         ``after(outcome, hook_name, hook_impls, kwargs)`` receives the
-        same arguments as ``before`` but also a :class:`~pluggy._result._Result` object
+        same arguments as ``before`` but also a :class:`~pluggy.Result` object
         which represents the result of the overall hook call.
         """
         oldcall = self._inner_hookexec
@@ -451,7 +451,7 @@ def traced_hookexec(
             firstresult: bool,
         ) -> object | list[object]:
             before(hook_name, hook_impls, caller_kwargs)
-            outcome = _Result.from_call(
+            outcome = Result.from_call(
                 lambda: oldcall(hook_name, hook_impls, caller_kwargs, firstresult)
             )
             after(outcome, hook_name, hook_impls, caller_kwargs)
@@ -478,7 +478,7 @@ def before(
             hooktrace(hook_name, kwargs)
 
         def after(
-            outcome: _Result[object],
+            outcome: Result[object],
             hook_name: str,
             methods: Sequence[HookImpl],
             kwargs: Mapping[str, object],

src/pluggy/_result.py

@@ -16,12 +16,12 @@
 
 
 _ExcInfo = Tuple[Type[BaseException], BaseException, Optional[TracebackType]]
-_T = TypeVar("_T")
+ResultType = TypeVar("ResultType")
 
 
 def _raise_wrapfail(
     wrap_controller: (
-        Generator[None, _Result[_T], None] | Generator[None, object, object]
+        Generator[None, Result[ResultType], None] | Generator[None, object, object]
     ),
     msg: str,
 ) -> NoReturn:
@@ -36,15 +36,15 @@ class HookCallError(Exception):
     """Hook was called incorrectly."""
 
 
-class _Result(Generic[_T]):
+class Result(Generic[ResultType]):
     """An object used to inspect and set the result in a :ref:`hook wrapper
     <hookwrappers>`."""
 
     __slots__ = ("_result", "_exception")
 
     def __init__(
         self,
-        result: _T | None,
+        result: ResultType | None,
         exception: BaseException | None,
     ) -> None:
         """:meta private:"""
@@ -66,7 +66,7 @@ def exception(self) -> BaseException | None:
         return self._exception
 
     @classmethod
-    def from_call(cls, func: Callable[[], _T]) -> _Result[_T]:
+    def from_call(cls, func: Callable[[], ResultType]) -> Result[ResultType]:
         """:meta private:"""
         __tracebackhide__ = True
         result = exception = None
@@ -76,7 +76,7 @@ def from_call(cls, func: Callable[[], _T]) -> _Result[_T]:
             exception = exc
         return cls(result, exception)
 
-    def force_result(self, result: _T) -> None:
+    def force_result(self, result: ResultType) -> None:
         """Force the result(s) to ``result``.
 
         If the hook was marked as a ``firstresult`` a single value should
@@ -98,7 +98,7 @@ def force_exception(self, exception: BaseException) -> None:
         self._result = None
         self._exception = exception
 
-    def get_result(self) -> _T:
+    def get_result(self) -> ResultType:
         """Get the result(s) for this hook call.
 
         If the hook was marked as a ``firstresult`` only a single value
@@ -107,6 +107,10 @@ def get_result(self) -> _T:
         __tracebackhide__ = True
         exc = self._exception
         if exc is None:
-            return cast(_T, self._result)
+            return cast(ResultType, self._result)
         else:
             raise exc.with_traceback(exc.__traceback__)
+
+
+# Historical name (pluggy<=1.2), kept for backward compatibility.
+_Result = Result