Erste Version
This commit is contained in:
commit
782b1850a3
1641 files changed
+512713
No files matched your search
@@ -0,0 +1,38 @@
|
||||
__all__ = [
|
||||
"HookCallError",
|
||||
"HookCaller",
|
||||
"HookImpl",
|
||||
"HookRelay",
|
||||
"HookimplMarker",
|
||||
"HookimplOpts",
|
||||
"HookspecMarker",
|
||||
"HookspecOpts",
|
||||
"PluggyTeardownRaisedWarning",
|
||||
"PluggyWarning",
|
||||
"PluginManager",
|
||||
"PluginValidationError",
|
||||
"Result",
|
||||
"__version__",
|
||||
]
|
||||
from ._hooks import HookCaller
|
||||
from ._hooks import HookImpl
|
||||
from ._hooks import HookimplMarker
|
||||
from ._hooks import HookimplOpts
|
||||
from ._hooks import HookRelay
|
||||
from ._hooks import HookspecMarker
|
||||
from ._hooks import HookspecOpts
|
||||
from ._manager import PluginManager
|
||||
from ._manager import PluginValidationError
|
||||
from ._result import HookCallError
|
||||
from ._result import Result
|
||||
from ._warnings import PluggyTeardownRaisedWarning
|
||||
from ._warnings import PluggyWarning
|
||||
|
||||
|
||||
def __getattr__(name: str) -> str:
|
||||
if name == "__version__":
|
||||
from importlib.metadata import version
|
||||
|
||||
return version("pluggy")
|
||||
|
||||
raise AttributeError(f"module {__name__} has no attribute {name!r}")
|
||||
@@ -0,0 +1,322 @@
|
||||
"""
|
||||
Hook callers and relay.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Callable
|
||||
from collections.abc import Mapping
|
||||
from collections.abc import Sequence
|
||||
from collections.abc import Set as AbstractSet
|
||||
from typing import Any
|
||||
from typing import Final
|
||||
from typing import final
|
||||
from typing import TYPE_CHECKING
|
||||
from typing import TypeAlias
|
||||
import warnings
|
||||
|
||||
from ._config import HookimplOpts
|
||||
from ._config import HookspecOpts
|
||||
from ._decorators import _Namespace
|
||||
from ._decorators import HookSpec
|
||||
from ._impl import _Plugin
|
||||
from ._impl import HookImpl
|
||||
|
||||
|
||||
_HookExec: TypeAlias = Callable[
|
||||
[str, Sequence[HookImpl], Mapping[str, object], bool],
|
||||
object | list[object],
|
||||
]
|
||||
|
||||
|
||||
@final
|
||||
class HookRelay:
|
||||
"""Hook holder object for performing 1:N hook calls where N is the number
|
||||
of registered plugins."""
|
||||
|
||||
__slots__ = ("__dict__",)
|
||||
|
||||
def __init__(self) -> None:
|
||||
""":meta private:"""
|
||||
|
||||
if TYPE_CHECKING:
|
||||
|
||||
def __getattr__(self, name: str) -> HookCaller: ...
|
||||
|
||||
|
||||
# Historical name (pluggy<=1.2), kept for backward compatibility.
|
||||
_HookRelay = HookRelay
|
||||
|
||||
|
||||
_CallHistory: TypeAlias = list[
|
||||
tuple[Mapping[str, object], Callable[[Any], None] | None]
|
||||
]
|
||||
|
||||
|
||||
class HookCaller:
|
||||
"""A caller of all registered implementations of a hook specification."""
|
||||
|
||||
__slots__ = (
|
||||
"_call_history",
|
||||
"_hookexec",
|
||||
"_hookimpls",
|
||||
"name",
|
||||
"spec",
|
||||
)
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
name: str,
|
||||
hook_execute: _HookExec,
|
||||
specmodule_or_class: _Namespace | None = None,
|
||||
spec_opts: HookspecOpts | None = None,
|
||||
) -> None:
|
||||
""":meta private:"""
|
||||
#: Name of the hook getting called.
|
||||
self.name: Final = name
|
||||
self._hookexec: Final = hook_execute
|
||||
# The hookimpls list. The caller iterates it *in reverse*. Format:
|
||||
# 1. trylast nonwrappers
|
||||
# 2. nonwrappers
|
||||
# 3. tryfirst nonwrappers
|
||||
# 4. trylast wrappers
|
||||
# 5. wrappers
|
||||
# 6. tryfirst wrappers
|
||||
self._hookimpls: Final[list[HookImpl]] = []
|
||||
self._call_history: _CallHistory | None = None
|
||||
# TODO: Document, or make private.
|
||||
self.spec: HookSpec | None = None
|
||||
if specmodule_or_class is not None:
|
||||
assert spec_opts is not None
|
||||
self.set_specification(specmodule_or_class, spec_opts)
|
||||
|
||||
# TODO: Document, or make private.
|
||||
def has_spec(self) -> bool:
|
||||
return self.spec is not None
|
||||
|
||||
# TODO: Document, or make private.
|
||||
def set_specification(
|
||||
self,
|
||||
specmodule_or_class: _Namespace,
|
||||
spec_opts: HookspecOpts,
|
||||
) -> None:
|
||||
if self.spec is not None:
|
||||
raise ValueError(
|
||||
f"Hook {self.spec.name!r} is already registered "
|
||||
f"within namespace {self.spec.namespace}"
|
||||
)
|
||||
self.spec = HookSpec(specmodule_or_class, self.name, spec_opts)
|
||||
if spec_opts.get("historic"):
|
||||
self._call_history = []
|
||||
|
||||
def is_historic(self) -> bool:
|
||||
"""Whether this caller is :ref:`historic <historic>`."""
|
||||
return self._call_history is not None
|
||||
|
||||
def _remove_plugin(self, plugin: _Plugin) -> None:
|
||||
"""Remove all hook implementations registered by the given plugin."""
|
||||
remaining = [impl for impl in self._hookimpls if impl.plugin != plugin]
|
||||
if len(remaining) == len(self._hookimpls):
|
||||
raise ValueError(f"plugin {plugin!r} not found")
|
||||
self._hookimpls[:] = remaining
|
||||
|
||||
def get_hookimpls(self) -> list[HookImpl]:
|
||||
"""Get all registered hook implementations for this hook."""
|
||||
return self._hookimpls.copy()
|
||||
|
||||
def _add_hookimpl(self, hookimpl: HookImpl) -> None:
|
||||
"""Add an implementation to the callback chain."""
|
||||
for i, method in enumerate(self._hookimpls):
|
||||
if method.hookwrapper or method.wrapper:
|
||||
splitpoint = i
|
||||
break
|
||||
else:
|
||||
splitpoint = len(self._hookimpls)
|
||||
if hookimpl.hookwrapper or hookimpl.wrapper:
|
||||
start, end = splitpoint, len(self._hookimpls)
|
||||
else:
|
||||
start, end = 0, splitpoint
|
||||
|
||||
if hookimpl.trylast:
|
||||
self._hookimpls.insert(start, hookimpl)
|
||||
elif hookimpl.tryfirst:
|
||||
self._hookimpls.insert(end, hookimpl)
|
||||
else:
|
||||
# find last non-tryfirst method
|
||||
i = end - 1
|
||||
while i >= start and self._hookimpls[i].tryfirst:
|
||||
i -= 1
|
||||
self._hookimpls.insert(i + 1, hookimpl)
|
||||
|
||||
def __repr__(self) -> str:
|
||||
return f"<HookCaller {self.name!r}>"
|
||||
|
||||
def _apply_defaults(self, kwargs: Mapping[str, object]) -> Mapping[str, object]:
|
||||
if self.spec is None or not self.spec.kwargdefaults:
|
||||
return kwargs
|
||||
return {**self.spec.kwargdefaults, **kwargs}
|
||||
|
||||
def _verify_all_args_are_provided(self, kwargs: Mapping[str, object]) -> None:
|
||||
# This is written to avoid expensive operations when not needed.
|
||||
if self.spec:
|
||||
for argname in self.spec.argnames:
|
||||
if argname not in kwargs:
|
||||
notincall = ", ".join(
|
||||
repr(argname)
|
||||
for argname in self.spec.argnames
|
||||
# Avoid self.spec.argnames - kwargs.keys()
|
||||
# it doesn't preserve order.
|
||||
if argname not in kwargs
|
||||
)
|
||||
warnings.warn(
|
||||
f"Argument(s) {notincall} which are declared in the hookspec "
|
||||
"cannot be found in this hook call",
|
||||
# 3, not 2: the warning is raised in this helper, which
|
||||
# is called by __call__/call_historic/call_extra, which
|
||||
# are called by the code making the hook call.
|
||||
stacklevel=3,
|
||||
)
|
||||
break
|
||||
|
||||
def __call__(self, **kwargs: object) -> Any:
|
||||
"""Call the hook.
|
||||
|
||||
Only accepts keyword arguments, which should match the hook
|
||||
specification.
|
||||
|
||||
Returns the result(s) of calling all registered plugins, see
|
||||
:ref:`calling`.
|
||||
"""
|
||||
assert not self.is_historic(), (
|
||||
"Cannot directly call a historic hook - use call_historic instead."
|
||||
)
|
||||
call_kwargs = self._apply_defaults(kwargs)
|
||||
self._verify_all_args_are_provided(call_kwargs)
|
||||
firstresult = self.spec.opts.get("firstresult", False) if self.spec else False
|
||||
# Copy because plugins may register other plugins during iteration (#438).
|
||||
return self._hookexec(
|
||||
self.name, self._hookimpls.copy(), call_kwargs, firstresult
|
||||
)
|
||||
|
||||
def call_historic(
|
||||
self,
|
||||
result_callback: Callable[[Any], None] | None = None,
|
||||
kwargs: Mapping[str, object] | None = None,
|
||||
) -> None:
|
||||
"""Call the hook with given ``kwargs`` for all registered plugins and
|
||||
for all plugins which will be registered afterwards, see
|
||||
:ref:`historic`.
|
||||
|
||||
:param result_callback:
|
||||
If provided, will be called for each non-``None`` result obtained
|
||||
from a hook implementation.
|
||||
"""
|
||||
assert self._call_history is not None
|
||||
kwargs = kwargs or {}
|
||||
kwargs = self._apply_defaults(kwargs)
|
||||
self._verify_all_args_are_provided(kwargs)
|
||||
self._call_history.append((kwargs, result_callback))
|
||||
# Historizing hooks don't return results.
|
||||
# Remember firstresult isn't compatible with historic.
|
||||
# Copy because plugins may register other plugins during iteration (#438).
|
||||
res = self._hookexec(self.name, self._hookimpls.copy(), kwargs, False)
|
||||
if result_callback is None:
|
||||
return
|
||||
if isinstance(res, list):
|
||||
for x in res:
|
||||
result_callback(x)
|
||||
|
||||
def call_extra(
|
||||
self, methods: Sequence[Callable[..., object]], kwargs: Mapping[str, object]
|
||||
) -> Any:
|
||||
"""Call the hook with some additional temporarily participating
|
||||
methods using the specified ``kwargs`` as call parameters, see
|
||||
:ref:`call_extra`."""
|
||||
assert not self.is_historic(), (
|
||||
"Cannot directly call a historic hook - use call_historic instead."
|
||||
)
|
||||
kwargs = self._apply_defaults(kwargs)
|
||||
self._verify_all_args_are_provided(kwargs)
|
||||
opts: HookimplOpts = {
|
||||
"wrapper": False,
|
||||
"hookwrapper": False,
|
||||
"optionalhook": False,
|
||||
"trylast": False,
|
||||
"tryfirst": False,
|
||||
"specname": None,
|
||||
}
|
||||
hookimpls = self._hookimpls.copy()
|
||||
for method in methods:
|
||||
hookimpl = HookImpl(None, "<temp>", method, opts)
|
||||
# Find last non-tryfirst nonwrapper method.
|
||||
i = len(hookimpls) - 1
|
||||
while i >= 0 and (
|
||||
# Skip wrappers.
|
||||
(hookimpls[i].hookwrapper or hookimpls[i].wrapper)
|
||||
# Skip tryfirst nonwrappers.
|
||||
or hookimpls[i].tryfirst
|
||||
):
|
||||
i -= 1
|
||||
hookimpls.insert(i + 1, hookimpl)
|
||||
firstresult = self.spec.opts.get("firstresult", False) if self.spec else False
|
||||
return self._hookexec(self.name, hookimpls, kwargs, firstresult)
|
||||
|
||||
def _maybe_apply_history(self, method: HookImpl) -> None:
|
||||
"""Apply call history to a new hookimpl if it is marked as historic."""
|
||||
if self.is_historic():
|
||||
assert self._call_history is not None
|
||||
for kwargs, result_callback in self._call_history:
|
||||
res = self._hookexec(self.name, [method], kwargs, False)
|
||||
if res and result_callback is not None:
|
||||
# XXX: remember firstresult isn't compat with historic
|
||||
assert isinstance(res, list)
|
||||
result_callback(res[0])
|
||||
|
||||
|
||||
# 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
|
||||
# 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
|
||||
# HookCaller, copying all hookimpls from the original. This had problems
|
||||
# with memory leaks (#346) and historic calls (#347), which make a proxy
|
||||
# approach better.
|
||||
# An alternative implementation is to use a `_getattr__`/`__getattribute__`
|
||||
# proxy, however that adds more overhead and is more tricky to implement.
|
||||
|
||||
__slots__ = (
|
||||
"_orig",
|
||||
"_remove_plugins",
|
||||
)
|
||||
|
||||
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]
|
||||
self._hookexec = orig._hookexec # type: ignore[misc]
|
||||
|
||||
@property # type: ignore[misc]
|
||||
def _hookimpls(self) -> list[HookImpl]:
|
||||
return [
|
||||
impl
|
||||
for impl in self._orig._hookimpls
|
||||
if impl.plugin not in self._remove_plugins
|
||||
]
|
||||
|
||||
@property
|
||||
def spec(self) -> HookSpec | None: # type: ignore[override]
|
||||
return self._orig.spec
|
||||
|
||||
@property
|
||||
def _call_history(self) -> _CallHistory | None: # type: ignore[override]
|
||||
return self._orig._call_history
|
||||
|
||||
def __repr__(self) -> str:
|
||||
return f"<_SubsetHookCaller {self.name!r}>"
|
||||
@@ -0,0 +1,23 @@
|
||||
"""
|
||||
Call loop machinery.
|
||||
|
||||
This module re-exports the execution engine for backward compatibility.
|
||||
Prefer importing from :mod:`pluggy._execution`.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from ._execution import _multicall
|
||||
from ._execution import _raise_wrapfail
|
||||
from ._execution import _warn_teardown_exception
|
||||
from ._execution import run_old_style_hookwrapper
|
||||
from ._execution import Teardown
|
||||
|
||||
|
||||
__all__ = [
|
||||
"Teardown",
|
||||
"_multicall",
|
||||
"_raise_wrapfail",
|
||||
"_warn_teardown_exception",
|
||||
"run_old_style_hookwrapper",
|
||||
]
|
||||
@@ -0,0 +1,43 @@
|
||||
"""Compatibility helpers."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
|
||||
if TYPE_CHECKING:
|
||||
import importlib.metadata
|
||||
|
||||
|
||||
class DistFacade:
|
||||
"""Facade providing pkg_resources.Distribution-like interface.
|
||||
|
||||
This class wraps importlib.metadata.Distribution to provide a
|
||||
compatibility layer for code expecting the legacy pkg_resources API.
|
||||
The primary difference is the ``project_name`` attribute which
|
||||
pkg_resources provided but importlib.metadata.Distribution does not.
|
||||
"""
|
||||
|
||||
__slots__ = ("_dist",)
|
||||
|
||||
def __init__(self, dist: importlib.metadata.Distribution) -> None:
|
||||
self._dist = dist
|
||||
|
||||
@property
|
||||
def project_name(self) -> str:
|
||||
"""Get the project name (for pkg_resources compatibility).
|
||||
|
||||
This is equivalent to dist.metadata["name"] but matches the
|
||||
pkg_resources.Distribution.project_name attribute.
|
||||
"""
|
||||
name: str = self.metadata["name"]
|
||||
return name
|
||||
|
||||
def __getattr__(self, attr: str) -> Any:
|
||||
"""Delegate all other attributes to the wrapped Distribution."""
|
||||
return getattr(self._dist, attr)
|
||||
|
||||
def __dir__(self) -> list[str]:
|
||||
"""List available attributes including facade additions."""
|
||||
return sorted(dir(self._dist) + ["_dist", "project_name"])
|
||||
@@ -0,0 +1,54 @@
|
||||
"""
|
||||
Configuration types for hook specifications and implementations.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping
|
||||
from typing import TypedDict
|
||||
|
||||
|
||||
class HookspecOpts(TypedDict):
|
||||
"""Options for a hook specification."""
|
||||
|
||||
#: Whether the hook is :ref:`first result only <firstresult>`.
|
||||
firstresult: bool
|
||||
#: Whether the hook is :ref:`historic <historic>`.
|
||||
historic: bool
|
||||
#: Whether the hook :ref:`warns when implemented <warn_on_impl>`.
|
||||
warn_on_impl: Warning | None
|
||||
#: Whether the hook warns when :ref:`certain arguments are requested
|
||||
#: <warn_on_impl>`.
|
||||
#:
|
||||
#: .. versionadded:: 1.5
|
||||
warn_on_impl_args: Mapping[str, Warning] | None
|
||||
|
||||
|
||||
class HookimplOpts(TypedDict):
|
||||
"""Options for a hook implementation."""
|
||||
|
||||
#: Whether the hook implementation is a :ref:`wrapper <hookwrapper>`.
|
||||
wrapper: bool
|
||||
#: Whether the hook implementation is an :ref:`old-style wrapper
|
||||
#: <old_style_hookwrappers>`.
|
||||
hookwrapper: bool
|
||||
#: Whether validation against a hook specification is :ref:`optional
|
||||
#: <optionalhook>`.
|
||||
optionalhook: bool
|
||||
#: Whether to try to order this hook implementation :ref:`first
|
||||
#: <callorder>`.
|
||||
tryfirst: bool
|
||||
#: Whether to try to order this hook implementation :ref:`last
|
||||
#: <callorder>`.
|
||||
trylast: bool
|
||||
#: The name of the hook specification to match, see :ref:`specname`.
|
||||
specname: str | None
|
||||
|
||||
|
||||
def normalize_hookimpl_opts(opts: HookimplOpts) -> None:
|
||||
opts.setdefault("tryfirst", False)
|
||||
opts.setdefault("trylast", False)
|
||||
opts.setdefault("wrapper", False)
|
||||
opts.setdefault("hookwrapper", False)
|
||||
opts.setdefault("optionalhook", False)
|
||||
opts.setdefault("specname", None)
|
||||
@@ -0,0 +1,356 @@
|
||||
"""
|
||||
Hook markers, specifications, and related helpers.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Callable
|
||||
from collections.abc import Mapping
|
||||
import inspect
|
||||
import sys
|
||||
import types
|
||||
from types import ModuleType
|
||||
from typing import Final
|
||||
from typing import final
|
||||
from typing import overload
|
||||
from typing import TypeAlias
|
||||
from typing import TypeVar
|
||||
import warnings
|
||||
|
||||
from ._config import HookimplOpts
|
||||
from ._config import HookspecOpts
|
||||
|
||||
|
||||
_F = TypeVar("_F", bound=Callable[..., object])
|
||||
|
||||
_Namespace: TypeAlias = ModuleType | type
|
||||
|
||||
|
||||
@final
|
||||
class HookspecMarker:
|
||||
"""Decorator for marking functions as hook specifications.
|
||||
|
||||
Instantiate it with a project_name to get a decorator.
|
||||
Calling :meth:`PluginManager.add_hookspecs` later will discover all marked
|
||||
functions if the :class:`PluginManager` uses the same project name.
|
||||
"""
|
||||
|
||||
__slots__ = ("project_name",)
|
||||
|
||||
def __init__(self, project_name: str) -> None:
|
||||
self.project_name: Final = project_name
|
||||
|
||||
@overload
|
||||
def __call__(
|
||||
self,
|
||||
function: _F,
|
||||
firstresult: bool = False,
|
||||
historic: bool = False,
|
||||
warn_on_impl: Warning | None = None,
|
||||
warn_on_impl_args: Mapping[str, Warning] | None = None,
|
||||
) -> _F: ...
|
||||
|
||||
@overload
|
||||
def __call__(
|
||||
self,
|
||||
function: None = ...,
|
||||
firstresult: bool = ...,
|
||||
historic: bool = ...,
|
||||
warn_on_impl: Warning | None = ...,
|
||||
warn_on_impl_args: Mapping[str, Warning] | None = ...,
|
||||
) -> Callable[[_F], _F]: ...
|
||||
|
||||
def __call__(
|
||||
self,
|
||||
function: _F | None = None,
|
||||
firstresult: bool = False,
|
||||
historic: bool = False,
|
||||
warn_on_impl: Warning | None = None,
|
||||
warn_on_impl_args: Mapping[str, Warning] | None = None,
|
||||
) -> _F | Callable[[_F], _F]:
|
||||
"""If passed a function, directly sets attributes on the function
|
||||
which will make it discoverable to :meth:`PluginManager.add_hookspecs`.
|
||||
|
||||
If passed no function, returns a decorator which can be applied to a
|
||||
function later using the attributes supplied.
|
||||
|
||||
:param firstresult:
|
||||
If ``True``, the 1:N hook call (N being the number of registered
|
||||
hook implementation functions) will stop at I<=N when the I'th
|
||||
function returns a non-``None`` result. See :ref:`firstresult`.
|
||||
|
||||
:param historic:
|
||||
If ``True``, every call to the hook will be memorized and replayed
|
||||
on plugins registered after the call was made. See :ref:`historic`.
|
||||
|
||||
:param warn_on_impl:
|
||||
If given, every implementation of this hook will trigger the given
|
||||
warning. See :ref:`warn_on_impl`.
|
||||
|
||||
:param warn_on_impl_args:
|
||||
If given, every implementation of this hook which requests one of
|
||||
the arguments in the dict will trigger the corresponding warning.
|
||||
See :ref:`warn_on_impl`.
|
||||
|
||||
.. versionadded:: 1.5
|
||||
"""
|
||||
|
||||
def setattr_hookspec_opts(func: _F) -> _F:
|
||||
if historic and firstresult:
|
||||
raise ValueError("cannot have a historic firstresult hook")
|
||||
opts: HookspecOpts = {
|
||||
"firstresult": firstresult,
|
||||
"historic": historic,
|
||||
"warn_on_impl": warn_on_impl,
|
||||
"warn_on_impl_args": warn_on_impl_args,
|
||||
}
|
||||
setattr(func, self.project_name + "_spec", opts)
|
||||
return func
|
||||
|
||||
if function is not None:
|
||||
return setattr_hookspec_opts(function)
|
||||
else:
|
||||
return setattr_hookspec_opts
|
||||
|
||||
|
||||
@final
|
||||
class HookimplMarker:
|
||||
"""Decorator for marking functions as hook implementations.
|
||||
|
||||
Instantiate it with a ``project_name`` to get a decorator.
|
||||
Calling :meth:`PluginManager.register` later will discover all marked
|
||||
functions if the :class:`PluginManager` uses the same project name.
|
||||
"""
|
||||
|
||||
__slots__ = ("project_name",)
|
||||
|
||||
def __init__(self, project_name: str) -> None:
|
||||
self.project_name: Final = project_name
|
||||
|
||||
@overload
|
||||
def __call__(
|
||||
self,
|
||||
function: _F,
|
||||
hookwrapper: bool = ...,
|
||||
optionalhook: bool = ...,
|
||||
tryfirst: bool = ...,
|
||||
trylast: bool = ...,
|
||||
specname: str | None = ...,
|
||||
wrapper: bool = ...,
|
||||
) -> _F: ...
|
||||
|
||||
@overload
|
||||
def __call__(
|
||||
self,
|
||||
function: None = ...,
|
||||
hookwrapper: bool = ...,
|
||||
optionalhook: bool = ...,
|
||||
tryfirst: bool = ...,
|
||||
trylast: bool = ...,
|
||||
specname: str | None = ...,
|
||||
wrapper: bool = ...,
|
||||
) -> Callable[[_F], _F]: ...
|
||||
|
||||
def __call__(
|
||||
self,
|
||||
function: _F | None = None,
|
||||
hookwrapper: bool = False,
|
||||
optionalhook: bool = False,
|
||||
tryfirst: bool = False,
|
||||
trylast: bool = False,
|
||||
specname: str | None = None,
|
||||
wrapper: bool = False,
|
||||
) -> _F | Callable[[_F], _F]:
|
||||
"""If passed a function, directly sets attributes on the function
|
||||
which will make it discoverable to :meth:`PluginManager.register`.
|
||||
|
||||
If passed no function, returns a decorator which can be applied to a
|
||||
function later using the attributes supplied.
|
||||
|
||||
:param optionalhook:
|
||||
If ``True``, a missing matching hook specification will not result
|
||||
in an error (by default it is an error if no matching spec is
|
||||
found). See :ref:`optionalhook`.
|
||||
|
||||
:param tryfirst:
|
||||
If ``True``, this hook implementation will run as early as possible
|
||||
in the chain of N hook implementations for a specification. See
|
||||
:ref:`callorder`.
|
||||
|
||||
:param trylast:
|
||||
If ``True``, this hook implementation will run as late as possible
|
||||
in the chain of N hook implementations for a specification. See
|
||||
:ref:`callorder`.
|
||||
|
||||
:param wrapper:
|
||||
If ``True`` ("new-style hook wrapper"), the hook implementation
|
||||
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
|
||||
functions have run. The ``yield`` receives the result value of the
|
||||
inner calls, or raises the exception of inner calls (including
|
||||
earlier hook wrapper calls). The return value of the function
|
||||
becomes the return value of the hook, and a raised exception becomes
|
||||
the exception of the hook. See :ref:`hookwrapper`.
|
||||
|
||||
:param hookwrapper:
|
||||
If ``True`` ("old-style hook wrapper"), the hook implementation
|
||||
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
|
||||
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`.
|
||||
|
||||
:param specname:
|
||||
If provided, the given name will be used instead of the function
|
||||
name when matching this hook implementation to a hook specification
|
||||
during registration. See :ref:`specname`.
|
||||
|
||||
.. versionadded:: 1.2.0
|
||||
The ``wrapper`` parameter.
|
||||
"""
|
||||
|
||||
def setattr_hookimpl_opts(func: _F) -> _F:
|
||||
opts: HookimplOpts = {
|
||||
"wrapper": wrapper,
|
||||
"hookwrapper": hookwrapper,
|
||||
"optionalhook": optionalhook,
|
||||
"tryfirst": tryfirst,
|
||||
"trylast": trylast,
|
||||
"specname": specname,
|
||||
}
|
||||
setattr(func, self.project_name + "_impl", opts)
|
||||
return func
|
||||
|
||||
if function is None:
|
||||
return setattr_hookimpl_opts
|
||||
else:
|
||||
return setattr_hookimpl_opts(function)
|
||||
|
||||
|
||||
_PYPY = sys.implementation.name == "pypy"
|
||||
_IMPLICIT_NAMES = ("self", "cls", "obj") if _PYPY else ("self", "cls")
|
||||
|
||||
# Qualnames whose missing-self deprecation warning is suppressed because
|
||||
# their upstream code is already fixed but not yet released.
|
||||
# Remove entries once a release with the fix is available.
|
||||
_NOSELF_WARN_SUPPRESS: frozenset[str] = frozenset(
|
||||
{
|
||||
# pytest-timeout >=2.3.2 has the fix, but is unreleased as of 2026-05.
|
||||
"TimeoutHooks.pytest_timeout_set_timer",
|
||||
"TimeoutHooks.pytest_timeout_cancel_timer",
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
def varnames(
|
||||
func: object, *, legacy_noself: bool = False
|
||||
) -> tuple[tuple[str, ...], tuple[str, ...]]:
|
||||
"""Return tuple of positional and keyword parameter names for a callable.
|
||||
|
||||
In case of a class, its ``__init__`` method is considered.
|
||||
For bound methods, the already-bound first parameter is not included.
|
||||
For unbound methods with a dotted ``__qualname__``, the first parameter is
|
||||
stripped only if its name is a known implicit name (``self``, ``cls``).
|
||||
Keyword-only parameters are not included.
|
||||
|
||||
:param legacy_noself:
|
||||
If ``True``, support hookspec classes whose methods omit ``self``.
|
||||
When the function looks like a class method but has no implicit first
|
||||
parameter, a :class:`DeprecationWarning` is emitted.
|
||||
"""
|
||||
is_bound = False
|
||||
if inspect.isclass(func):
|
||||
try:
|
||||
func = func.__init__
|
||||
except AttributeError: # pragma: no cover - pypy special case
|
||||
return (), ()
|
||||
is_bound = True
|
||||
elif not inspect.isroutine(func): # callable object?
|
||||
try:
|
||||
# Not a `callable()` check: the `__call__` attribute itself is
|
||||
# wanted, so that its signature can be inspected below.
|
||||
func = getattr(func, "__call__", func) # noqa: B004
|
||||
except Exception: # pragma: no cover - pypy special case
|
||||
return (), ()
|
||||
|
||||
# Track bound methods before unwrapping, since __func__ loses that info.
|
||||
if inspect.ismethod(func):
|
||||
is_bound = True
|
||||
func = inspect.unwrap(func) # type: ignore[arg-type]
|
||||
if inspect.ismethod(func):
|
||||
is_bound = True
|
||||
func = func.__func__
|
||||
|
||||
try:
|
||||
code: types.CodeType = func.__code__ # type: ignore[attr-defined]
|
||||
defaults: tuple[object, ...] | None = func.__defaults__ # type: ignore[attr-defined]
|
||||
qualname: str = func.__qualname__ # type: ignore[attr-defined]
|
||||
except AttributeError: # pragma: no cover
|
||||
return (), ()
|
||||
|
||||
# Get positional argument names (positional-only + positional-or-keyword)
|
||||
args: tuple[str, ...] = code.co_varnames[: code.co_argcount]
|
||||
|
||||
# Determine which args have defaults
|
||||
kwargs: tuple[str, ...]
|
||||
if defaults:
|
||||
index = -len(defaults)
|
||||
args, kwargs = args[:index], args[index:]
|
||||
else:
|
||||
kwargs = ()
|
||||
|
||||
# Strip implicit instance/class arg.
|
||||
# Check if this looks like a method defined in a class by examining the
|
||||
# qualname after the last "<locals>." segment (if any). A remaining dot
|
||||
# means it's a class method (e.g. "MyClass.method" or
|
||||
# "func.<locals>.MyClass.method"), not just a nested function.
|
||||
_tail = qualname.rsplit("<locals>.", maxsplit=1)[-1]
|
||||
_is_class_method = "." in _tail
|
||||
if args:
|
||||
if is_bound or (_is_class_method and args[0] in _IMPLICIT_NAMES):
|
||||
args = args[1:]
|
||||
elif _is_class_method and legacy_noself and _tail not in _NOSELF_WARN_SUPPRESS:
|
||||
warnings.warn(
|
||||
f"{qualname} is a method but its first parameter"
|
||||
f" {args[0]!r} is not 'self'."
|
||||
f" Add 'self' as the first parameter or use @staticmethod."
|
||||
f" This will become an error in a future version of pluggy.",
|
||||
DeprecationWarning,
|
||||
stacklevel=2,
|
||||
)
|
||||
|
||||
return args, kwargs
|
||||
|
||||
|
||||
@final
|
||||
class HookSpec:
|
||||
__slots__ = (
|
||||
"argnames",
|
||||
"function",
|
||||
"kwargdefaults",
|
||||
"kwargnames",
|
||||
"name",
|
||||
"namespace",
|
||||
"opts",
|
||||
"warn_on_impl",
|
||||
"warn_on_impl_args",
|
||||
)
|
||||
|
||||
def __init__(self, namespace: _Namespace, name: str, opts: HookspecOpts) -> None:
|
||||
self.namespace = namespace
|
||||
self.name = name
|
||||
self.function: Callable[..., object] = getattr(namespace, name)
|
||||
legacy_noself = inspect.isclass(namespace) and not isinstance(
|
||||
inspect.getattr_static(namespace, name), staticmethod
|
||||
)
|
||||
self.argnames, self.kwargnames = varnames(
|
||||
self.function, legacy_noself=legacy_noself
|
||||
)
|
||||
defaults = inspect.unwrap(self.function).__defaults__
|
||||
self.kwargdefaults = dict(zip(self.kwargnames, defaults or ()))
|
||||
self.opts = opts
|
||||
self.warn_on_impl = opts.get("warn_on_impl")
|
||||
self.warn_on_impl_args = opts.get("warn_on_impl_args")
|
||||
@@ -0,0 +1,197 @@
|
||||
"""
|
||||
Hook call execution (multicall) machinery.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Generator
|
||||
from collections.abc import Mapping
|
||||
from collections.abc import Sequence
|
||||
from typing import cast
|
||||
from typing import NoReturn
|
||||
from typing import TYPE_CHECKING
|
||||
from typing import TypeAlias
|
||||
import warnings
|
||||
|
||||
from ._impl import HookImpl
|
||||
from ._result import HookCallError
|
||||
from ._result import Result
|
||||
from ._warnings import PluggyTeardownRaisedWarning
|
||||
|
||||
|
||||
# Need to distinguish between old- and new-style hook wrappers.
|
||||
# Wrapping with a tuple is the fastest type-safe way I found to do it.
|
||||
Teardown: TypeAlias = Generator[None, object, object]
|
||||
|
||||
|
||||
def run_old_style_hookwrapper(
|
||||
hook_impl: HookImpl,
|
||||
hook_name: str,
|
||||
args: Sequence[object],
|
||||
kwargs: Mapping[str, object] | None,
|
||||
) -> Teardown:
|
||||
"""
|
||||
backward compatibility wrapper to run a old style hookwrapper as a wrapper
|
||||
"""
|
||||
if kwargs is None:
|
||||
res = hook_impl.function(*args)
|
||||
else:
|
||||
res = hook_impl.function(*args, **kwargs)
|
||||
if TYPE_CHECKING:
|
||||
teardown = cast(Teardown, res)
|
||||
else:
|
||||
teardown = res
|
||||
try:
|
||||
next(teardown)
|
||||
except StopIteration:
|
||||
_raise_wrapfail(teardown, "did not yield")
|
||||
try:
|
||||
res = yield
|
||||
result = Result(res, None)
|
||||
except BaseException as exc:
|
||||
result = Result(None, exc)
|
||||
try:
|
||||
teardown.send(result)
|
||||
except StopIteration:
|
||||
pass
|
||||
except BaseException as e:
|
||||
_warn_teardown_exception(hook_name, hook_impl, e)
|
||||
raise
|
||||
else:
|
||||
_raise_wrapfail(teardown, "has second yield")
|
||||
finally:
|
||||
teardown.close()
|
||||
return result.get_result()
|
||||
|
||||
|
||||
def _raise_wrapfail(
|
||||
wrap_controller: Generator[None, object, object],
|
||||
msg: str,
|
||||
) -> NoReturn:
|
||||
co = wrap_controller.gi_code # type: ignore[attr-defined]
|
||||
raise RuntimeError(
|
||||
f"wrap_controller at {co.co_name!r} {co.co_filename}:{co.co_firstlineno} {msg}"
|
||||
)
|
||||
|
||||
|
||||
def _warn_teardown_exception(
|
||||
hook_name: str, hook_impl: HookImpl, e: BaseException
|
||||
) -> None:
|
||||
msg = (
|
||||
f"A plugin raised an exception during an old-style hookwrapper teardown.\n"
|
||||
f"Plugin: {hook_impl.plugin_name}, Hook: {hook_name}\n"
|
||||
f"{type(e).__name__}: {e}\n"
|
||||
f"For more information see https://pluggy.readthedocs.io/en/stable/api_reference.html#pluggy.PluggyTeardownRaisedWarning"
|
||||
)
|
||||
warnings.warn(PluggyTeardownRaisedWarning(msg), stacklevel=6)
|
||||
|
||||
|
||||
def _multicall(
|
||||
hook_name: str,
|
||||
hook_impls: Sequence[HookImpl],
|
||||
caller_kwargs: Mapping[str, object],
|
||||
firstresult: bool,
|
||||
) -> object | list[object]:
|
||||
"""Execute a call into multiple python functions/methods and return the
|
||||
result(s).
|
||||
|
||||
``caller_kwargs`` comes from HookCaller.__call__().
|
||||
"""
|
||||
__tracebackhide__ = True
|
||||
results: list[object] = []
|
||||
exception = None
|
||||
teardowns: list[Teardown] = []
|
||||
try: # run impl and wrapper setup functions in a loop
|
||||
for hook_impl in reversed(hook_impls):
|
||||
try:
|
||||
args = [caller_kwargs[argname] for argname in hook_impl.argnames]
|
||||
if hook_impl.kwargnames:
|
||||
kwargs = {
|
||||
argname: caller_kwargs[argname]
|
||||
for argname in hook_impl.kwargnames
|
||||
if argname in caller_kwargs
|
||||
} or None
|
||||
else:
|
||||
kwargs = None
|
||||
except KeyError as e:
|
||||
raise HookCallError(
|
||||
f"hook call must provide argument {e.args[0]!r}"
|
||||
) from e
|
||||
|
||||
if hook_impl.hookwrapper:
|
||||
function_gen = run_old_style_hookwrapper(
|
||||
hook_impl, hook_name, args, kwargs
|
||||
)
|
||||
|
||||
next(function_gen) # first yield
|
||||
teardowns.append(function_gen)
|
||||
|
||||
elif hook_impl.wrapper:
|
||||
if kwargs is None:
|
||||
res = hook_impl.function(*args)
|
||||
else:
|
||||
res = hook_impl.function(*args, **kwargs)
|
||||
# If this cast is not valid, a type error is raised below,
|
||||
# which is the desired response.
|
||||
if TYPE_CHECKING:
|
||||
function_gen = cast(Generator[None, object, object], res)
|
||||
else:
|
||||
function_gen = res
|
||||
try:
|
||||
next(function_gen) # first yield
|
||||
except StopIteration:
|
||||
_raise_wrapfail(function_gen, "did not yield")
|
||||
teardowns.append(function_gen)
|
||||
else:
|
||||
if kwargs is None:
|
||||
res = hook_impl.function(*args)
|
||||
else:
|
||||
res = hook_impl.function(*args, **kwargs)
|
||||
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")
|
||||
|
||||
if exception is not None:
|
||||
raise exception
|
||||
else:
|
||||
return result
|
||||
@@ -0,0 +1,47 @@
|
||||
"""
|
||||
Internal hook annotation, representation and calling machinery.
|
||||
|
||||
This module re-exports symbols from the role-specific modules for
|
||||
backward compatibility.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from ._caller import _HookCaller
|
||||
from ._caller import _HookExec
|
||||
from ._caller import _HookRelay
|
||||
from ._caller import _SubsetHookCaller
|
||||
from ._caller import HookCaller
|
||||
from ._caller import HookRelay
|
||||
from ._config import HookimplOpts
|
||||
from ._config import HookspecOpts
|
||||
from ._config import normalize_hookimpl_opts
|
||||
from ._decorators import _Namespace
|
||||
from ._decorators import HookimplMarker
|
||||
from ._decorators import HookSpec
|
||||
from ._decorators import HookspecMarker
|
||||
from ._decorators import varnames
|
||||
from ._impl import _HookImplFunction
|
||||
from ._impl import _Plugin
|
||||
from ._impl import HookImpl
|
||||
|
||||
|
||||
__all__ = [
|
||||
"HookCaller",
|
||||
"HookImpl",
|
||||
"HookRelay",
|
||||
"HookSpec",
|
||||
"HookimplMarker",
|
||||
"HookimplOpts",
|
||||
"HookspecMarker",
|
||||
"HookspecOpts",
|
||||
"_HookCaller",
|
||||
"_HookExec",
|
||||
"_HookImplFunction",
|
||||
"_HookRelay",
|
||||
"_Namespace",
|
||||
"_Plugin",
|
||||
"_SubsetHookCaller",
|
||||
"normalize_hookimpl_opts",
|
||||
"varnames",
|
||||
]
|
||||
@@ -0,0 +1,81 @@
|
||||
"""
|
||||
Hook implementation representation.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Callable
|
||||
from collections.abc import Generator
|
||||
from typing import Final
|
||||
from typing import final
|
||||
from typing import TypeAlias
|
||||
from typing import TypeVar
|
||||
|
||||
from ._config import HookimplOpts
|
||||
from ._decorators import varnames
|
||||
from ._result import Result
|
||||
|
||||
|
||||
_T = TypeVar("_T")
|
||||
|
||||
_Plugin: TypeAlias = object
|
||||
_HookImplFunction: TypeAlias = Callable[..., _T | Generator[None, Result[_T], None]]
|
||||
|
||||
|
||||
@final
|
||||
class HookImpl:
|
||||
"""A hook implementation in a :class:`HookCaller`."""
|
||||
|
||||
__slots__ = (
|
||||
"argnames",
|
||||
"function",
|
||||
"hookwrapper",
|
||||
"kwargnames",
|
||||
"optionalhook",
|
||||
"opts",
|
||||
"plugin",
|
||||
"plugin_name",
|
||||
"tryfirst",
|
||||
"trylast",
|
||||
"wrapper",
|
||||
)
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
plugin: _Plugin,
|
||||
plugin_name: str,
|
||||
function: _HookImplFunction[object],
|
||||
hook_impl_opts: HookimplOpts,
|
||||
) -> None:
|
||||
""":meta private:"""
|
||||
#: The hook implementation function.
|
||||
self.function: Final = function
|
||||
argnames, kwargnames = varnames(self.function)
|
||||
#: The positional parameter names of ``function``.
|
||||
self.argnames: Final = argnames
|
||||
#: The keyword parameter names of ``function`` which declare defaults.
|
||||
#: Keyword-only parameters are *not* included.
|
||||
self.kwargnames: Final = kwargnames
|
||||
#: The plugin which defined this hook implementation.
|
||||
self.plugin: Final = plugin
|
||||
#: The :class:`HookimplOpts` used to configure this hook implementation.
|
||||
self.opts: Final = hook_impl_opts
|
||||
#: The name of the plugin which defined this hook implementation.
|
||||
self.plugin_name: Final = plugin_name
|
||||
#: Whether the hook implementation is a :ref:`wrapper <hookwrapper>`.
|
||||
self.wrapper: Final = hook_impl_opts["wrapper"]
|
||||
#: Whether the hook implementation is an :ref:`old-style wrapper
|
||||
#: <old_style_hookwrappers>`.
|
||||
self.hookwrapper: Final = hook_impl_opts["hookwrapper"]
|
||||
#: Whether validation against a hook specification is :ref:`optional
|
||||
#: <optionalhook>`.
|
||||
self.optionalhook: Final = hook_impl_opts["optionalhook"]
|
||||
#: Whether to try to order this hook implementation :ref:`first
|
||||
#: <callorder>`.
|
||||
self.tryfirst: Final = hook_impl_opts["tryfirst"]
|
||||
#: Whether to try to order this hook implementation :ref:`last
|
||||
#: <callorder>`.
|
||||
self.trylast: Final = hook_impl_opts["trylast"]
|
||||
|
||||
def __repr__(self) -> str:
|
||||
return f"<HookImpl plugin_name={self.plugin_name!r}, plugin={self.plugin!r}>"
|
||||
@@ -0,0 +1,652 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Callable
|
||||
from collections.abc import Iterable
|
||||
from collections.abc import Mapping
|
||||
from collections.abc import Sequence
|
||||
import inspect
|
||||
import types
|
||||
from typing import Any
|
||||
from typing import cast
|
||||
from typing import Final
|
||||
from typing import TYPE_CHECKING
|
||||
from typing import TypeAlias
|
||||
import warnings
|
||||
|
||||
from . import _tracing
|
||||
from ._callers import _multicall
|
||||
from ._compat import DistFacade
|
||||
from ._hooks import _HookImplFunction
|
||||
from ._hooks import _Namespace
|
||||
from ._hooks import _Plugin
|
||||
from ._hooks import _SubsetHookCaller
|
||||
from ._hooks import HookCaller
|
||||
from ._hooks import HookImpl
|
||||
from ._hooks import HookimplOpts
|
||||
from ._hooks import HookRelay
|
||||
from ._hooks import HookspecOpts
|
||||
from ._hooks import normalize_hookimpl_opts
|
||||
from ._result import Result
|
||||
|
||||
|
||||
if TYPE_CHECKING:
|
||||
import importlib.metadata
|
||||
|
||||
|
||||
_BeforeTrace: TypeAlias = Callable[[str, Sequence[HookImpl], Mapping[str, Any]], None]
|
||||
_AfterTrace: TypeAlias = Callable[
|
||||
[Result[Any], str, Sequence[HookImpl], Mapping[str, Any]], None
|
||||
]
|
||||
|
||||
|
||||
def _warn_for_function(warning: Warning, function: Callable[..., object]) -> None:
|
||||
func = cast(types.FunctionType, function)
|
||||
warnings.warn_explicit(
|
||||
warning,
|
||||
type(warning),
|
||||
lineno=func.__code__.co_firstlineno,
|
||||
filename=func.__code__.co_filename,
|
||||
)
|
||||
|
||||
|
||||
_ABSENT: Final = object()
|
||||
|
||||
|
||||
def _instance_dict(obj: object) -> dict[str, Any]:
|
||||
"""Return ``obj``'s own ``__dict__``, without going through ``getattr``."""
|
||||
try:
|
||||
instance_dict = object.__getattribute__(obj, "__dict__")
|
||||
except AttributeError:
|
||||
return {}
|
||||
return instance_dict if isinstance(instance_dict, dict) else {}
|
||||
|
||||
|
||||
def _static_hook_attr(
|
||||
obj: object, name: str
|
||||
) -> tuple[object, Callable[..., object]] | None:
|
||||
"""Return ``(marker_holder, function)`` for ``name`` on ``obj``, else None.
|
||||
|
||||
Lookup avoids ``getattr()`` so that properties, ``cached_property`` and
|
||||
other descriptors are skipped instead of being evaluated -- hooks provided
|
||||
through such a descriptor (or only through ``__getattr__``) are not
|
||||
supported. Only plain functions, :class:`classmethod`, :class:`staticmethod`
|
||||
and already-bound :class:`~types.MethodType` objects are hookable.
|
||||
|
||||
``marker_holder`` is the object that may carry the hookimpl/hookspec
|
||||
options: the ``classmethod``/``staticmethod`` wrapper when the marker was
|
||||
applied above it, the underlying function otherwise. ``function`` is bound
|
||||
exactly the way ``getattr()`` would have bound it.
|
||||
"""
|
||||
if not (inspect.isclass(obj) or inspect.ismodule(obj)):
|
||||
# Values stored on the instance itself -- in ``__dict__`` or in a
|
||||
# ``__slots__`` slot -- are handed out by ``getattr()`` as they are,
|
||||
# bypassing the descriptor protocol, so they must not be bound here.
|
||||
value = _instance_dict(obj).get(name, _ABSENT)
|
||||
if value is _ABSENT:
|
||||
slot = inspect.getattr_static(obj, name, None)
|
||||
if isinstance(slot, types.MemberDescriptorType):
|
||||
# Reading a slot runs no user code.
|
||||
try:
|
||||
value = slot.__get__(obj, type(obj))
|
||||
except AttributeError:
|
||||
value = _ABSENT
|
||||
if value is not _ABSENT:
|
||||
if isinstance(value, types.MethodType):
|
||||
return value.__func__, value
|
||||
if inspect.isfunction(value):
|
||||
return value, value
|
||||
return None
|
||||
|
||||
static: object = inspect.getattr_static(obj, name, None)
|
||||
if isinstance(static, staticmethod):
|
||||
return static, static.__func__
|
||||
if isinstance(static, classmethod):
|
||||
owner = obj if inspect.isclass(obj) else type(obj)
|
||||
return static, cast(Callable[..., object], static.__get__(owner, owner))
|
||||
if isinstance(static, types.MethodType):
|
||||
return static.__func__, static
|
||||
if inspect.isfunction(static):
|
||||
if inspect.isclass(obj) or inspect.ismodule(obj):
|
||||
return static, static
|
||||
return static, static.__get__(obj, type(obj))
|
||||
return None
|
||||
|
||||
|
||||
def _get_marker_opts(holder: object, attrname: str) -> dict[str, Any] | None:
|
||||
"""Read marker options from ``holder``, falling back to ``__func__``."""
|
||||
opts = getattr(holder, attrname, None)
|
||||
if opts is not None:
|
||||
return opts if isinstance(opts, dict) else None
|
||||
func = getattr(holder, "__func__", None)
|
||||
if func is not None:
|
||||
opts = getattr(func, attrname, None)
|
||||
if opts is not None:
|
||||
return opts if isinstance(opts, dict) else None
|
||||
return None
|
||||
|
||||
|
||||
class PluginValidationError(Exception):
|
||||
"""Plugin failed validation.
|
||||
|
||||
:param plugin: The plugin which failed validation.
|
||||
:param message: Error message.
|
||||
"""
|
||||
|
||||
def __init__(self, plugin: _Plugin, message: str) -> None:
|
||||
super().__init__(message)
|
||||
#: The plugin which failed validation.
|
||||
self.plugin = plugin
|
||||
|
||||
|
||||
class PluginManager:
|
||||
"""Core class which manages registration of plugin objects and 1:N hook
|
||||
calling.
|
||||
|
||||
You can register new hooks by calling :meth:`add_hookspecs(module_or_class)
|
||||
<PluginManager.add_hookspecs>`.
|
||||
|
||||
You can register plugin objects (which contain hook implementations) by
|
||||
calling :meth:`register(plugin) <PluginManager.register>`.
|
||||
|
||||
For debugging purposes you can call :meth:`PluginManager.enable_tracing`
|
||||
which will subsequently send debug information to the trace helper.
|
||||
|
||||
:param project_name:
|
||||
The short project name. Prefer snake case. Make sure it's unique!
|
||||
"""
|
||||
|
||||
def __init__(self, project_name: str) -> None:
|
||||
#: The project name.
|
||||
self.project_name: Final = project_name
|
||||
self._name2plugin: Final[dict[str, _Plugin]] = {}
|
||||
self._plugin_distinfo: Final[
|
||||
list[tuple[_Plugin, importlib.metadata.Distribution]]
|
||||
] = []
|
||||
#: The "hook relay", used to call a hook on all registered plugins.
|
||||
#: See :ref:`calling`.
|
||||
self.hook: Final = HookRelay()
|
||||
#: The tracing entry point. See :ref:`tracing`.
|
||||
self.trace: Final[_tracing.TagTracerSub] = _tracing.TagTracer().get(
|
||||
"pluginmanage"
|
||||
)
|
||||
self._inner_hookexec = _multicall
|
||||
|
||||
def _hookexec(
|
||||
self,
|
||||
hook_name: str,
|
||||
methods: Sequence[HookImpl],
|
||||
kwargs: Mapping[str, object],
|
||||
firstresult: bool,
|
||||
) -> object | list[object]:
|
||||
# called from all hookcaller instances.
|
||||
# enable_tracing will set its own wrapping function at self._inner_hookexec
|
||||
return self._inner_hookexec(hook_name, methods, kwargs, firstresult)
|
||||
|
||||
def register(self, plugin: _Plugin, name: str | None = None) -> str | None:
|
||||
"""Register a plugin and return its name.
|
||||
|
||||
:param name:
|
||||
The name under which to register the plugin. If not specified, a
|
||||
name is generated using :func:`get_canonical_name`.
|
||||
|
||||
:returns:
|
||||
The plugin name. If the name is blocked from registering, returns
|
||||
``None``.
|
||||
|
||||
If the plugin is already registered, raises a :exc:`ValueError`.
|
||||
"""
|
||||
if plugin is None:
|
||||
# Registering a `None` plugin causes problems (#731). However, some
|
||||
# users are doing it, so can't error out (#749). Just ignore
|
||||
# instead.
|
||||
return None
|
||||
|
||||
plugin_name = name or self.get_canonical_name(plugin)
|
||||
|
||||
if plugin_name in self._name2plugin:
|
||||
if self._name2plugin.get(plugin_name, -1) is None:
|
||||
return None # blocked plugin, return None to indicate no registration
|
||||
raise ValueError(
|
||||
"Plugin name already registered: "
|
||||
f"{plugin_name}={plugin}\n{self._name2plugin}"
|
||||
)
|
||||
|
||||
if plugin in self._name2plugin.values():
|
||||
raise ValueError(
|
||||
"Plugin already registered under a different name: "
|
||||
f"{plugin_name}={plugin}\n{self._name2plugin}"
|
||||
)
|
||||
|
||||
# Validate every hookimpl before changing any state, so a plugin that
|
||||
# fails validation leaves the manager untouched.
|
||||
hookimpls: list[tuple[str, HookImpl, bool]] = []
|
||||
for attr_name in dir(plugin):
|
||||
hookimpl_opts = self.parse_hookimpl_opts(plugin, attr_name)
|
||||
if hookimpl_opts is not None:
|
||||
normalize_hookimpl_opts(hookimpl_opts)
|
||||
found = _static_hook_attr(plugin, attr_name)
|
||||
# Only reachable when a subclass overrode parse_hookimpl_opts
|
||||
# to claim an attribute pluggy cannot bind.
|
||||
assert found is not None, (
|
||||
f"{plugin!r}.{attr_name} is not a hookable attribute"
|
||||
)
|
||||
method: _HookImplFunction[object] = found[1]
|
||||
hookimpl = HookImpl(plugin, plugin_name, method, hookimpl_opts)
|
||||
hook_name = hookimpl_opts.get("specname") or attr_name
|
||||
hook: HookCaller | None = getattr(self.hook, hook_name, None)
|
||||
verified = False
|
||||
if hook is not None and hook.has_spec():
|
||||
self._verify_hook(hook, hookimpl)
|
||||
verified = True
|
||||
hookimpls.append((hook_name, hookimpl, verified))
|
||||
|
||||
self._name2plugin[plugin_name] = plugin
|
||||
for hook_name, hookimpl, verified in hookimpls:
|
||||
hook = getattr(self.hook, hook_name, None)
|
||||
if hook is None:
|
||||
hook = HookCaller(hook_name, self._hookexec)
|
||||
setattr(self.hook, hook_name, hook)
|
||||
elif not verified and hook.has_spec():
|
||||
# An earlier impl's historic replay added this spec after the
|
||||
# first pass. Failing here leaves the plugin partially
|
||||
# registered, but only user code during replay can get here.
|
||||
self._verify_hook(hook, hookimpl)
|
||||
hook._maybe_apply_history(hookimpl)
|
||||
hook._add_hookimpl(hookimpl)
|
||||
return plugin_name
|
||||
|
||||
def parse_hookimpl_opts(self, plugin: _Plugin, name: str) -> HookimplOpts | None:
|
||||
"""Try to obtain a hook implementation from an item with the given name
|
||||
in the given plugin which is being searched for hook impls.
|
||||
|
||||
:returns:
|
||||
The parsed hookimpl options, or None to skip the given item.
|
||||
|
||||
This method can be overridden by ``PluginManager`` subclasses to
|
||||
customize how hook implementation are picked up. By default, returns the
|
||||
options for items decorated with :class:`HookimplMarker`.
|
||||
|
||||
Discovery uses :func:`inspect.getattr_static` so properties and other
|
||||
descriptors are not executed. Only functions, classmethods,
|
||||
staticmethods, and bound methods are considered.
|
||||
"""
|
||||
found = _static_hook_attr(plugin, name)
|
||||
if found is None:
|
||||
return None
|
||||
return cast(
|
||||
HookimplOpts | None,
|
||||
_get_marker_opts(found[0], self.project_name + "_impl"),
|
||||
)
|
||||
|
||||
def unregister(
|
||||
self, plugin: _Plugin | None = None, name: str | None = None
|
||||
) -> Any | None:
|
||||
"""Unregister a plugin and all of its hook implementations.
|
||||
|
||||
The plugin can be specified either by the plugin object or the plugin
|
||||
name. If both are specified, they must agree.
|
||||
|
||||
Returns the unregistered plugin, or ``None`` if not found.
|
||||
"""
|
||||
if name is None:
|
||||
assert plugin is not None, "one of name or plugin needs to be specified"
|
||||
name = self.get_name(plugin)
|
||||
assert name is not None, "plugin is not registered"
|
||||
|
||||
if plugin is None:
|
||||
plugin = self.get_plugin(name)
|
||||
if plugin is None:
|
||||
return None
|
||||
else:
|
||||
# Both given: hook callers are looked up by plugin but the registry
|
||||
# entry is removed by name, so they must refer to the same plugin.
|
||||
registered_plugin = self._name2plugin.get(name)
|
||||
registered_name = self.get_name(plugin)
|
||||
if (registered_plugin is not None and registered_plugin is not plugin) or (
|
||||
registered_name is not None and registered_name != name
|
||||
):
|
||||
raise ValueError(
|
||||
f"Plugin name {name!r} and plugin {plugin!r} do not agree"
|
||||
f" (name is registered to {registered_plugin!r},"
|
||||
f" plugin is registered as {registered_name!r})"
|
||||
)
|
||||
|
||||
hookcallers = self.get_hookcallers(plugin)
|
||||
if hookcallers:
|
||||
for hookcaller in hookcallers:
|
||||
hookcaller._remove_plugin(plugin)
|
||||
|
||||
# if self._name2plugin[name] == None registration was blocked: ignore
|
||||
if self._name2plugin.get(name) is not None:
|
||||
del self._name2plugin[name]
|
||||
|
||||
return plugin
|
||||
|
||||
def set_blocked(self, name: str) -> None:
|
||||
"""Block registrations of the given name, unregister if already registered."""
|
||||
self.unregister(name=name)
|
||||
self._name2plugin[name] = None
|
||||
|
||||
def is_blocked(self, name: str) -> bool:
|
||||
"""Return whether the given plugin name is blocked."""
|
||||
return name in self._name2plugin and self._name2plugin[name] is None
|
||||
|
||||
def unblock(self, name: str) -> bool:
|
||||
"""Unblocks a name.
|
||||
|
||||
Returns whether the name was actually blocked.
|
||||
"""
|
||||
if self._name2plugin.get(name, -1) is None:
|
||||
del self._name2plugin[name]
|
||||
return True
|
||||
return False
|
||||
|
||||
def add_hookspecs(self, module_or_class: _Namespace) -> None:
|
||||
"""Add new hook specifications defined in the given ``module_or_class``.
|
||||
|
||||
Functions are recognized as hook specifications if they have been
|
||||
decorated with a matching :class:`HookspecMarker`.
|
||||
"""
|
||||
names = []
|
||||
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)
|
||||
if hc is None:
|
||||
hc = HookCaller(name, self._hookexec, module_or_class, spec_opts)
|
||||
setattr(self.hook, name, hc)
|
||||
else:
|
||||
# Plugins registered this hook without knowing the spec.
|
||||
hc.set_specification(module_or_class, spec_opts)
|
||||
for hookfunction in hc.get_hookimpls():
|
||||
self._verify_hook(hc, hookfunction)
|
||||
names.append(name)
|
||||
|
||||
if not names:
|
||||
raise ValueError(
|
||||
f"did not find any {self.project_name!r} hooks in {module_or_class!r}"
|
||||
)
|
||||
|
||||
def parse_hookspec_opts(
|
||||
self, module_or_class: _Namespace, name: str
|
||||
) -> HookspecOpts | None:
|
||||
"""Try to obtain a hook specification from an item with the given name
|
||||
in the given module or class which is being searched for hook specs.
|
||||
|
||||
:returns:
|
||||
The parsed hookspec options for defining a hook, or None to skip the
|
||||
given item.
|
||||
|
||||
This method can be overridden by ``PluginManager`` subclasses to
|
||||
customize how hook specifications are picked up. By default, returns the
|
||||
options for items decorated with :class:`HookspecMarker`.
|
||||
|
||||
Discovery uses :func:`inspect.getattr_static` so properties and other
|
||||
descriptors are not executed. Only functions, classmethods,
|
||||
staticmethods, and bound methods are considered.
|
||||
"""
|
||||
found = _static_hook_attr(module_or_class, name)
|
||||
if found is None:
|
||||
return None
|
||||
return cast(
|
||||
HookspecOpts | None,
|
||||
_get_marker_opts(found[0], self.project_name + "_spec"),
|
||||
)
|
||||
|
||||
def get_plugins(self) -> set[Any]:
|
||||
"""Return a set of all registered plugin objects."""
|
||||
return {x for x in self._name2plugin.values() if x is not None}
|
||||
|
||||
def is_registered(self, plugin: _Plugin) -> bool:
|
||||
"""Return whether the plugin is already registered."""
|
||||
return any(plugin == val for val in self._name2plugin.values())
|
||||
|
||||
def get_canonical_name(self, plugin: _Plugin) -> str:
|
||||
"""Return a canonical name for a plugin object.
|
||||
|
||||
Note that a plugin may be registered under a different name
|
||||
specified by the caller of :meth:`register(plugin, name) <register>`.
|
||||
To obtain the name of a registered plugin use :meth:`get_name(plugin)
|
||||
<get_name>` instead.
|
||||
"""
|
||||
name: str | None = getattr(plugin, "__name__", None)
|
||||
return name or str(id(plugin))
|
||||
|
||||
def get_plugin(self, name: str) -> Any | None:
|
||||
"""Return the plugin registered under the given name, if any."""
|
||||
return self._name2plugin.get(name)
|
||||
|
||||
def has_plugin(self, name: str) -> bool:
|
||||
"""Return whether a plugin with the given name is registered."""
|
||||
return self.get_plugin(name) is not None
|
||||
|
||||
def get_name(self, plugin: _Plugin) -> str | None:
|
||||
"""Return the name the plugin is registered under, or ``None`` if
|
||||
is isn't."""
|
||||
for name, val in self._name2plugin.items():
|
||||
if plugin == val:
|
||||
return name
|
||||
return None
|
||||
|
||||
def _verify_hook(self, hook: HookCaller, hookimpl: HookImpl) -> None:
|
||||
if hook.is_historic() and (hookimpl.hookwrapper or hookimpl.wrapper):
|
||||
raise PluginValidationError(
|
||||
hookimpl.plugin,
|
||||
f"Plugin {hookimpl.plugin_name!r}\nhook {hook.name!r}\n"
|
||||
"historic incompatible with yield/wrapper/hookwrapper",
|
||||
)
|
||||
|
||||
assert hook.spec is not None
|
||||
if hook.spec.warn_on_impl:
|
||||
_warn_for_function(hook.spec.warn_on_impl, hookimpl.function)
|
||||
|
||||
# positional arg checking
|
||||
notinspec = set(hookimpl.argnames) - (
|
||||
set(hook.spec.argnames) | set(hook.spec.kwargnames)
|
||||
)
|
||||
if notinspec:
|
||||
raise PluginValidationError(
|
||||
hookimpl.plugin,
|
||||
f"Plugin {hookimpl.plugin_name!r} for hook {hook.name!r}\n"
|
||||
f"hookimpl definition: {_formatdef(hookimpl.function)}\n"
|
||||
f"Argument(s) {notinspec} are declared in the hookimpl but "
|
||||
"can not be found in the hookspec",
|
||||
)
|
||||
|
||||
if hook.spec.warn_on_impl_args:
|
||||
for hookimpl_argname in hookimpl.argnames + hookimpl.kwargnames:
|
||||
argname_warning = hook.spec.warn_on_impl_args.get(hookimpl_argname)
|
||||
if argname_warning is not None:
|
||||
_warn_for_function(argname_warning, hookimpl.function)
|
||||
|
||||
if (
|
||||
hookimpl.wrapper or hookimpl.hookwrapper
|
||||
) and not inspect.isgeneratorfunction(hookimpl.function):
|
||||
raise PluginValidationError(
|
||||
hookimpl.plugin,
|
||||
f"Plugin {hookimpl.plugin_name!r} for hook {hook.name!r}\n"
|
||||
f"hookimpl definition: {_formatdef(hookimpl.function)}\n"
|
||||
"Declared as wrapper=True or hookwrapper=True "
|
||||
"but function is not a generator function",
|
||||
)
|
||||
|
||||
if hookimpl.wrapper and hookimpl.hookwrapper:
|
||||
raise PluginValidationError(
|
||||
hookimpl.plugin,
|
||||
f"Plugin {hookimpl.plugin_name!r} for hook {hook.name!r}\n"
|
||||
f"hookimpl definition: {_formatdef(hookimpl.function)}\n"
|
||||
"The wrapper=True and hookwrapper=True options are mutually exclusive",
|
||||
)
|
||||
|
||||
def check_pending(self) -> None:
|
||||
"""Verify that all hooks which have not been verified against a
|
||||
hook specification are optional, otherwise raise
|
||||
:exc:`PluginValidationError`."""
|
||||
for name in self.hook.__dict__:
|
||||
if name[0] == "_":
|
||||
continue
|
||||
hook: HookCaller = getattr(self.hook, name)
|
||||
if not hook.has_spec():
|
||||
for hookimpl in hook.get_hookimpls():
|
||||
if not hookimpl.optionalhook:
|
||||
raise PluginValidationError(
|
||||
hookimpl.plugin,
|
||||
f"unknown hook {name!r} in plugin {hookimpl.plugin!r}",
|
||||
)
|
||||
|
||||
def load_setuptools_entrypoints(self, group: str, name: str | None = None) -> int:
|
||||
"""Load modules from querying the specified setuptools ``group``.
|
||||
|
||||
:param group:
|
||||
Entry point group to load plugins.
|
||||
:param name:
|
||||
If given, loads only plugins with the given ``name``.
|
||||
|
||||
:return:
|
||||
The number of plugins loaded by this call.
|
||||
"""
|
||||
import importlib.metadata
|
||||
|
||||
count = 0
|
||||
for dist in list(importlib.metadata.distributions()):
|
||||
for ep in dist.entry_points:
|
||||
if (
|
||||
ep.group != group
|
||||
or (name is not None and ep.name != name)
|
||||
# already registered
|
||||
or self.has_plugin(ep.name)
|
||||
or self.is_blocked(ep.name)
|
||||
):
|
||||
continue
|
||||
plugin = ep.load()
|
||||
self.register(plugin, name=ep.name)
|
||||
self._plugin_distinfo.append((plugin, dist))
|
||||
count += 1
|
||||
return count
|
||||
|
||||
def list_plugin_distinfo(self) -> list[tuple[_Plugin, DistFacade]]:
|
||||
"""Return a list of (plugin, distinfo) pairs for all
|
||||
setuptools-registered plugins.
|
||||
|
||||
.. note::
|
||||
The distinfo objects are wrapped with :class:`~pluggy._compat.DistFacade`
|
||||
for backward compatibility with the legacy pkg_resources API.
|
||||
Prefer :meth:`list_plugin_distributions` for raw
|
||||
:class:`importlib.metadata.Distribution` objects.
|
||||
"""
|
||||
from ._compat import DistFacade
|
||||
|
||||
return [(plugin, DistFacade(dist)) for plugin, dist in self._plugin_distinfo]
|
||||
|
||||
def list_plugin_distributions(
|
||||
self,
|
||||
) -> list[tuple[_Plugin, importlib.metadata.Distribution]]:
|
||||
"""Return a list of (plugin, distribution) pairs for all plugins
|
||||
loaded via entry points.
|
||||
|
||||
.. versionadded:: 1.7
|
||||
"""
|
||||
return list(self._plugin_distinfo)
|
||||
|
||||
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:
|
||||
"""Get all hook callers for the specified plugin.
|
||||
|
||||
:returns:
|
||||
The hook callers, or ``None`` if ``plugin`` is not registered in
|
||||
this plugin manager.
|
||||
"""
|
||||
if self.get_name(plugin) is None:
|
||||
return None
|
||||
hookcallers = []
|
||||
for hookcaller in self.hook.__dict__.values():
|
||||
if any(impl.plugin is plugin for impl in hookcaller.get_hookimpls()):
|
||||
hookcallers.append(hookcaller)
|
||||
return hookcallers
|
||||
|
||||
def add_hookcall_monitoring(
|
||||
self, before: _BeforeTrace, after: _AfterTrace
|
||||
) -> Callable[[], None]:
|
||||
"""Add before/after tracing functions for all hooks.
|
||||
|
||||
Returns an undo function which, when called, removes the added tracers.
|
||||
|
||||
``before(hook_name, hook_impls, kwargs)`` will be called ahead
|
||||
of all hook calls and receive a hookcaller instance, a list
|
||||
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` object
|
||||
which represents the result of the overall hook call.
|
||||
"""
|
||||
oldcall = self._inner_hookexec
|
||||
|
||||
def traced_hookexec(
|
||||
hook_name: str,
|
||||
hook_impls: Sequence[HookImpl],
|
||||
caller_kwargs: Mapping[str, object],
|
||||
firstresult: bool,
|
||||
) -> object | list[object]:
|
||||
before(hook_name, hook_impls, caller_kwargs)
|
||||
outcome = Result.from_call(
|
||||
lambda: oldcall(hook_name, hook_impls, caller_kwargs, firstresult)
|
||||
)
|
||||
after(outcome, hook_name, hook_impls, caller_kwargs)
|
||||
return outcome.get_result()
|
||||
|
||||
self._inner_hookexec = traced_hookexec
|
||||
|
||||
def undo() -> None:
|
||||
self._inner_hookexec = oldcall
|
||||
|
||||
return undo
|
||||
|
||||
def enable_tracing(self) -> Callable[[], None]:
|
||||
"""Enable tracing of hook calls.
|
||||
|
||||
Returns an undo function which, when called, removes the added tracing.
|
||||
"""
|
||||
hooktrace = self.trace.root.get("hook")
|
||||
|
||||
def before(
|
||||
hook_name: str, methods: Sequence[HookImpl], kwargs: Mapping[str, object]
|
||||
) -> None:
|
||||
hooktrace.root.indent += 1
|
||||
hooktrace(hook_name, kwargs)
|
||||
|
||||
def after(
|
||||
outcome: Result[object],
|
||||
hook_name: str,
|
||||
methods: Sequence[HookImpl],
|
||||
kwargs: Mapping[str, object],
|
||||
) -> None:
|
||||
if outcome.exception is None:
|
||||
hooktrace("finish", hook_name, "-->", outcome.get_result())
|
||||
hooktrace.root.indent -= 1
|
||||
|
||||
return self.add_hookcall_monitoring(before, after)
|
||||
|
||||
def subset_hook_caller(
|
||||
self, name: str, remove_plugins: Iterable[_Plugin]
|
||||
) -> HookCaller:
|
||||
"""Return a proxy :class:`~pluggy.HookCaller` for the named hook which
|
||||
calls all registered plugins except the ones from remove_plugins."""
|
||||
orig: HookCaller = getattr(self.hook, name)
|
||||
plugins_to_remove = set(remove_plugins)
|
||||
# Optimization: discard plugins to remove which don't actually implement
|
||||
# the hook, to make checks faster.
|
||||
plugins_to_remove.intersection_update(
|
||||
hookimpl.plugin for hookimpl in orig._hookimpls
|
||||
)
|
||||
# Optimization: if none of the plugins to remove actually implement the
|
||||
# hook, avoid the subset hook caller overhead.
|
||||
if not plugins_to_remove:
|
||||
return orig
|
||||
return _SubsetHookCaller(orig, plugins_to_remove)
|
||||
|
||||
|
||||
def _formatdef(func: Callable[..., object]) -> str:
|
||||
return f"{func.__name__}{inspect.signature(func)}"
|
||||
@@ -0,0 +1,107 @@
|
||||
"""
|
||||
Hook wrapper "result" utilities.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Callable
|
||||
from types import TracebackType
|
||||
from typing import cast
|
||||
from typing import final
|
||||
from typing import Generic
|
||||
from typing import TypeAlias
|
||||
from typing import TypeVar
|
||||
|
||||
|
||||
_ExcInfo: TypeAlias = tuple[type[BaseException], BaseException, TracebackType | None]
|
||||
ResultType = TypeVar("ResultType")
|
||||
|
||||
|
||||
class HookCallError(Exception):
|
||||
"""Hook was called incorrectly."""
|
||||
|
||||
|
||||
@final
|
||||
class Result(Generic[ResultType]):
|
||||
"""An object used to inspect and set the result in a :ref:`hook wrapper
|
||||
<hookwrappers>`."""
|
||||
|
||||
__slots__ = ("_exception", "_result", "_traceback")
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
result: ResultType | None,
|
||||
exception: BaseException | None,
|
||||
) -> None:
|
||||
""":meta private:"""
|
||||
self._result = result
|
||||
self._exception = exception
|
||||
# Exception __traceback__ is mutable, this keeps the original.
|
||||
self._traceback = exception.__traceback__ if exception is not None else None
|
||||
|
||||
@property
|
||||
def excinfo(self) -> _ExcInfo | None:
|
||||
""":meta private:"""
|
||||
exc = self._exception
|
||||
if exc is None:
|
||||
return None
|
||||
else:
|
||||
return (type(exc), exc, self._traceback)
|
||||
|
||||
@property
|
||||
def exception(self) -> BaseException | None:
|
||||
""":meta private:"""
|
||||
return self._exception
|
||||
|
||||
@classmethod
|
||||
def from_call(cls, func: Callable[[], ResultType]) -> Result[ResultType]:
|
||||
""":meta private:"""
|
||||
__tracebackhide__ = True
|
||||
result = exception = None
|
||||
try:
|
||||
result = func()
|
||||
except BaseException as exc:
|
||||
exception = exc
|
||||
return cls(result, exception)
|
||||
|
||||
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
|
||||
be set, otherwise set a (modified) list of results. Any exceptions
|
||||
found during invocation will be deleted.
|
||||
|
||||
This overrides any previous result or exception.
|
||||
"""
|
||||
self._result = result
|
||||
self._exception = None
|
||||
self._traceback = None
|
||||
|
||||
def force_exception(self, exception: BaseException) -> None:
|
||||
"""Force the result to fail with ``exception``.
|
||||
|
||||
This overrides any previous result or exception.
|
||||
|
||||
.. versionadded:: 1.1.0
|
||||
"""
|
||||
self._result = None
|
||||
self._exception = exception
|
||||
self._traceback = exception.__traceback__ if exception is not None else None
|
||||
|
||||
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
|
||||
will be returned, otherwise a list of results.
|
||||
"""
|
||||
__tracebackhide__ = True
|
||||
exc = self._exception
|
||||
tb = self._traceback
|
||||
if exc is None:
|
||||
return cast(ResultType, self._result)
|
||||
else:
|
||||
raise exc.with_traceback(tb)
|
||||
|
||||
|
||||
# Historical name (pluggy<=1.2), kept for backward compatibility.
|
||||
_Result = Result
|
||||
@@ -0,0 +1,147 @@
|
||||
"""
|
||||
Tracing utils
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Callable
|
||||
from collections.abc import Sequence
|
||||
import enum
|
||||
import os
|
||||
from typing import Any
|
||||
|
||||
|
||||
_Writer = Callable[[str], object]
|
||||
_Processor = Callable[[tuple[str, ...], tuple[Any, ...]], object]
|
||||
|
||||
|
||||
def _describe_failure(exc: Exception, obj: object, func: str) -> str:
|
||||
try:
|
||||
exc_info = repr(exc)
|
||||
except Exception:
|
||||
exc_info = f"unpresentable {type(exc).__name__}"
|
||||
name = type(obj).__name__
|
||||
return f"<[{exc_info} raised in {func}()] {name} object at 0x{id(obj):x}>"
|
||||
|
||||
|
||||
def _escape_surrogates(text: str) -> str:
|
||||
"""Escape lone surrogates so the result survives any text writer.
|
||||
|
||||
A lone surrogate reaching the writer raises :exc:`UnicodeEncodeError`
|
||||
inside the trace call for any utf-8 target, such as the file behind
|
||||
pytest's ``--debug``.
|
||||
"""
|
||||
if text.isascii():
|
||||
return text
|
||||
return text.encode("utf-8", "backslashreplace").decode("utf-8")
|
||||
|
||||
|
||||
def _safe_str(obj: object) -> str:
|
||||
"""``str(obj)`` for tracing, with a failing ``__str__`` rendered, not raised.
|
||||
|
||||
The result has lone surrogates escaped, so any text writer accepts it.
|
||||
"""
|
||||
try:
|
||||
text = str(obj)
|
||||
except Exception as exc:
|
||||
text = _describe_failure(exc, obj, "str")
|
||||
return _escape_surrogates(text)
|
||||
|
||||
|
||||
def _is_plain_token(text: str) -> bool:
|
||||
"""Whether ``text`` can be shown bare, without quotes around it."""
|
||||
return bool(text) and text.isprintable() and " " not in text
|
||||
|
||||
|
||||
def _format_block(indent: str, lines: list[str]) -> list[str]:
|
||||
"""Indent a multi line value under its key, so it reads as one value."""
|
||||
return [f"{indent} {line}\n" for line in lines]
|
||||
|
||||
|
||||
def _render_value(obj: object) -> str:
|
||||
"""Render a traced value, adding detail only where ``str`` is ambiguous."""
|
||||
# Before the str check: a StrEnum member is a str whose str() drops the name.
|
||||
if isinstance(obj, (enum.Enum, os.PathLike)):
|
||||
return _safe_repr(obj)
|
||||
if isinstance(obj, str):
|
||||
if len(obj.splitlines()) > 1:
|
||||
return _safe_str(obj)
|
||||
if _is_plain_token(obj):
|
||||
return _safe_str(obj)
|
||||
return _safe_repr(obj)
|
||||
return _safe_str(obj)
|
||||
|
||||
|
||||
def _safe_repr(obj: object) -> str:
|
||||
"""``repr(obj)`` for tracing, with a failing ``__repr__`` rendered, not raised.
|
||||
|
||||
The result has lone surrogates escaped, so any text writer accepts it.
|
||||
"""
|
||||
try:
|
||||
text = repr(obj)
|
||||
except Exception as exc:
|
||||
text = _describe_failure(exc, obj, "repr")
|
||||
return _escape_surrogates(text)
|
||||
|
||||
|
||||
class TagTracer:
|
||||
def __init__(self) -> None:
|
||||
self._tags2proc: dict[tuple[str, ...], _Processor] = {}
|
||||
self._writer: _Writer | None = None
|
||||
self.indent = 0
|
||||
|
||||
def get(self, name: str) -> TagTracerSub:
|
||||
return TagTracerSub(self, (name,))
|
||||
|
||||
def _format_message(self, tags: Sequence[str], args: Sequence[object]) -> str:
|
||||
if isinstance(args[-1], dict):
|
||||
extra = args[-1]
|
||||
args = args[:-1]
|
||||
else:
|
||||
extra = {}
|
||||
|
||||
content = " ".join(map(_safe_str, args))
|
||||
indent = " " * self.indent
|
||||
|
||||
lines = [f"{indent}{content} [{':'.join(tags)}]\n"]
|
||||
|
||||
for name, value in extra.items():
|
||||
rendered = _render_value(value)
|
||||
# A bare \r is a line break too: inline, the terminal would
|
||||
# return to column 0 and overwrite the key.
|
||||
body = rendered.splitlines()
|
||||
if body in ([], [rendered]):
|
||||
lines.append(f"{indent} {name}: {rendered}\n")
|
||||
else:
|
||||
lines.append(f"{indent} {name}:\n")
|
||||
lines.extend(_format_block(indent, body))
|
||||
|
||||
return "".join(lines)
|
||||
|
||||
def _processmessage(self, tags: tuple[str, ...], args: tuple[object, ...]) -> None:
|
||||
if self._writer is not None and args:
|
||||
self._writer(self._format_message(tags, args))
|
||||
if processor := self._tags2proc.get(tags):
|
||||
processor(tags, args)
|
||||
|
||||
def setwriter(self, writer: _Writer | None) -> None:
|
||||
self._writer = writer
|
||||
|
||||
def setprocessor(self, tags: str | tuple[str, ...], processor: _Processor) -> None:
|
||||
if isinstance(tags, str):
|
||||
tags = tuple(tags.split(":"))
|
||||
else:
|
||||
assert isinstance(tags, tuple)
|
||||
self._tags2proc[tags] = processor
|
||||
|
||||
|
||||
class TagTracerSub:
|
||||
def __init__(self, root: TagTracer, tags: tuple[str, ...]) -> None:
|
||||
self.root = root
|
||||
self.tags = tags
|
||||
|
||||
def __call__(self, *args: object) -> None:
|
||||
self.root._processmessage(self.tags, args)
|
||||
|
||||
def get(self, name: str) -> TagTracerSub:
|
||||
return self.__class__(self.root, self.tags + (name,))
|
||||
@@ -0,0 +1,27 @@
|
||||
from typing import final
|
||||
|
||||
|
||||
class PluggyWarning(UserWarning):
|
||||
"""Base class for all warnings emitted by pluggy."""
|
||||
|
||||
__module__ = "pluggy"
|
||||
|
||||
|
||||
@final
|
||||
class PluggyTeardownRaisedWarning(PluggyWarning):
|
||||
"""A plugin raised an exception during an :ref:`old-style hookwrapper
|
||||
<old_style_hookwrappers>` teardown.
|
||||
|
||||
Such exceptions are not handled by pluggy, and may cause subsequent
|
||||
teardowns to be executed at unexpected times, or be skipped entirely.
|
||||
|
||||
This is an issue in the plugin implementation.
|
||||
|
||||
If the exception is unintended, fix the underlying cause.
|
||||
|
||||
If the exception is intended, switch to :ref:`new-style hook wrappers
|
||||
<hookwrappers>`, or use :func:`result.force_exception()
|
||||
<pluggy.Result.force_exception>` to set the exception instead of raising.
|
||||
"""
|
||||
|
||||
__module__ = "pluggy"
|
||||
Whitespace-only changes.
Reference in new issue
Block a user