diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 2dd8555a..15f936aa 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -51,7 +51,7 @@ Features - `#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 ` object. + New-style wrappers are generator functions, similarly to ``hookwrapper``, but do away with the :class:`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 `_: Python 3.11 and 3.12 are now officially supported. -- `#394 `_: Added the :meth:`~pluggy._callers._Result.force_exception` method to ``_Result``. +- `#394 `_: Added the :meth:`~pluggy._result._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, diff --git a/docs/api_reference.rst b/docs/api_reference.rst index 81608bc7..4e73fbaf 100644 --- a/docs/api_reference.rst +++ b/docs/api_reference.rst @@ -7,10 +7,10 @@ API Reference :members: :undoc-members: -.. autoclass:: pluggy._callers._Result -.. automethod:: pluggy._callers._Result.get_result -.. automethod:: pluggy._callers._Result.force_result -.. automethod:: pluggy._callers._Result.force_exception +.. autoclass:: pluggy._result._Result +.. automethod:: pluggy._result._Result.get_result +.. automethod:: pluggy._result._Result.force_result +.. automethod:: pluggy._result._Result.force_exception .. autoclass:: pluggy._hooks._HookCaller .. automethod:: pluggy._hooks._HookCaller.call_extra diff --git a/docs/conf.py b/docs/conf.py index 2b4d59e6..66be769a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -86,10 +86,10 @@ intersphinx_mapping = { "python": ("https://docs.python.org/3", None), "pytest": ("https://docs.pytest.org/en/latest", None), - "setuptools": ("https://setuptools.readthedocs.io/en/latest", None), - "tox": ("https://tox.readthedocs.io/en/latest", None), + "setuptools": ("https://setuptools.pypa.io/en/latest", None), + "tox": ("https://tox.wiki/en/latest", None), "devpi": ("https://devpi.net/docs/devpi/devpi/stable/+doc/", None), - "kedro": ("https://kedro.readthedocs.io/en/latest/", None), + "kedro": ("https://docs.kedro.org/en/latest/", None), } diff --git a/docs/index.rst b/docs/index.rst index 51d5fb45..339fb9e2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -468,21 +468,21 @@ execution of all corresponding non-wrappper *hookimpls*. if config.use_defaults: outcome.force_result(defaults) -The generator is :py:meth:`sent ` a :py:class:`pluggy._callers._Result` object which can +The generator is :py:meth:`sent ` a :py:class:`pluggy._result._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._callers._Result.get_result` method, override the result -using the :py:meth:`~pluggy._callers._Result.force_result`, or override -the exception using the :py:meth:`~pluggy._callers._Result.force_exception` +: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` method. .. note:: Old-style hook wrappers can **not** return results; they can only modify - them using the :py:meth:`~pluggy._callers._Result.force_result` API. + them using the :py:meth:`~pluggy._result._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._callers._Result.force_exception` to adjust the + :py:meth:`~pluggy._result._Result.force_exception` to adjust the exception. .. _specs: diff --git a/src/pluggy/_manager.py b/src/pluggy/_manager.py index 80118b09..e14965ca 100644 --- a/src/pluggy/_manager.py +++ b/src/pluggy/_manager.py @@ -119,7 +119,7 @@ def register(self, plugin: _Plugin, name: str | None = None) -> str | None: If the name is blocked from registering, returns ``None``. - If the plugin is already registered, raises a :class:`ValueError`. + If the plugin is already registered, raises a :exc:`ValueError`. """ plugin_name = name or self.get_canonical_name(plugin) @@ -329,7 +329,7 @@ def _verify_hook(self, hook: _HookCaller, hookimpl: HookImpl) -> None: def check_pending(self) -> None: """Verify that all hooks which have not been verified against a hook specification are optional, otherwise raise - :class:`PluginValidationError`.""" + :exc:`PluginValidationError`.""" for name in self.hook.__dict__: if name[0] != "_": hook: _HookCaller = getattr(self.hook, name) @@ -399,7 +399,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:`_Result` object + same arguments as ``before`` but also a :class:`~pluggy._result._Result` object which represents the result of the overall hook call. """ oldcall = self._inner_hookexec