Merge pull request #632 from RonnyPfannschmidt/varnames-no-resolve-types

[NO-SQUASH-MERGE] fix varnames on py3.14 deferred annotations

Author: RonnyPfannschmidt

changelog/629.bugfix.rst

@@ -0,0 +1 @@
+Fix hooks failing to register on Python 3.14+ when type annotations use forward references.

changelog/632.removal.rst

@@ -0,0 +1 @@
+Hookspec methods defined without ``self`` as the first parameter now emit a :class:`DeprecationWarning`. Add ``self`` as the first parameter or use ``@staticmethod``.

src/pluggy/_hooks.py

@@ -11,6 +11,7 @@
 from collections.abc import Set
 import inspect
 import sys
+import types
 from types import ModuleType
 from typing import Any
 from typing import Final
@@ -287,70 +288,98 @@ def normalize_hookimpl_opts(opts: HookimplOpts) -> None:
     opts.setdefault("specname", None)
 
 
-_PYPY = hasattr(sys, "pypy_version_info")
+_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) -> tuple[tuple[str, ...], tuple[str, ...]]:
-    """Return tuple of positional and keywrord argument names for a function,
-    method, class or callable.
+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 methods the ``self`` parameter is not included.
+    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:
             func = getattr(func, "__call__", func)
         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:
-        # func MUST be a function or method here or we won't parse any args.
-        sig = inspect.signature(
-            func.__func__ if inspect.ismethod(func) else func  # type:ignore[arg-type]
-        )
-    except TypeError:  # pragma: no cover
+        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 (), ()
 
-    _valid_param_kinds = (
-        inspect.Parameter.POSITIONAL_ONLY,
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-    )
-    _valid_params = {
-        name: param
-        for name, param in sig.parameters.items()
-        if param.kind in _valid_param_kinds
-    }
-    args = tuple(_valid_params)
-    defaults = (
-        tuple(
-            param.default
-            for param in _valid_params.values()
-            if param.default is not param.empty
-        )
-        or None
-    )
+    # 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], tuple(args[index:])
+        args, kwargs = args[:index], args[index:]
     else:
         kwargs = ()
 
-    # strip any implicit instance arg
-    # pypy3 uses "obj" instead of "self" for default dunder methods
-    if not _PYPY:
-        implicit_names: tuple[str, ...] = ("self",)
-    else:
-        implicit_names = ("self", "obj")
+    # 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:
-        qualname: str = getattr(func, "__qualname__", "")
-        if inspect.ismethod(func) or ("." in qualname and args[0] in implicit_names):
+        if is_bound:
             args = args[1:]
+        elif _is_class_method and args[0] in _IMPLICIT_NAMES:
+            args = args[1:]
+        elif _is_class_method and legacy_noself:
+            if _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
 
@@ -708,9 +737,14 @@ class HookSpec:
 
     def __init__(self, namespace: _Namespace, name: str, opts: HookspecOpts) -> None:
         self.namespace = namespace
-        self.function: Callable[..., object] = getattr(namespace, name)
         self.name = name
-        self.argnames, self.kwargnames = varnames(self.function)
+        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
+        )
         self.opts = opts
         self.warn_on_impl = opts.get("warn_on_impl")
         self.warn_on_impl_args = opts.get("warn_on_impl_args")

testing/benchmark.py

@@ -2,6 +2,8 @@
 Benchmarking and performance tests.
 """
 
+import inspect
+import sys
 from typing import Any
 
 import pytest
@@ -11,6 +13,66 @@
 from pluggy import PluginManager
 from pluggy._callers import _multicall
 from pluggy._hooks import HookImpl
+from pluggy._hooks import varnames
+
+
+def _varnames_legacy(func: object) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    """Pre-structural-detection implementation using inspect.signature and
+    name-based heuristics for comparison."""
+    if inspect.isclass(func):
+        try:
+            func = func.__init__
+        except AttributeError:
+            return (), ()
+    elif not inspect.isroutine(func):
+        try:
+            func = getattr(func, "__call__", func)
+        except Exception:
+            return (), ()
+
+    try:
+        sig = inspect.signature(
+            func.__func__ if inspect.ismethod(func) else func  # type: ignore[arg-type]
+        )
+    except TypeError:
+        return (), ()
+
+    _valid_param_kinds = (
+        inspect.Parameter.POSITIONAL_ONLY,
+        inspect.Parameter.POSITIONAL_OR_KEYWORD,
+    )
+    _valid_params = {
+        name: param
+        for name, param in sig.parameters.items()
+        if param.kind in _valid_param_kinds
+    }
+    args = tuple(_valid_params)
+    defaults = (
+        tuple(
+            param.default
+            for param in _valid_params.values()
+            if param.default is not param.empty
+        )
+        or None
+    )
+
+    if defaults:
+        index = -len(defaults)
+        args, kwargs = args[:index], tuple(args[index:])
+    else:
+        kwargs = ()
+
+    _pypy = hasattr(sys, "pypy_version_info")
+    if not _pypy:
+        implicit_names: tuple[str, ...] = ("self",)
+    else:
+        implicit_names = ("self", "obj")
+    if args:
+        qualname: str = getattr(func, "__qualname__", "")
+        if inspect.ismethod(func) or ("." in qualname and args[0] in implicit_names):
+            args = args[1:]
+
+    return args, kwargs
 
 
 hookspec = HookspecMarker("example")
@@ -106,3 +168,30 @@ def fun(self):
         pm.register(PluginWrap(i), name=f"wrap_plug_{i}")
 
     benchmark(pm.hook.fun, hooks=pm.hook, nesting=nesting)
+
+
+def _plain_func(x: int, y: str, z: float = 1.0) -> None:
+    pass
+
+
+class _MethodHolder:
+    def method(self, x: int, y: str, z: float = 1.0) -> None:
+        pass
+
+
+_varnames_funcs = [
+    pytest.param(_plain_func, id="plain_function"),
+    pytest.param(_MethodHolder.method, id="unbound_method"),
+    pytest.param(_MethodHolder().method, id="bound_method"),
+    pytest.param(_MethodHolder, id="class"),
+]
+
+
+@pytest.mark.parametrize("func", _varnames_funcs)
+def test_varnames(benchmark, func: object) -> None:
+    benchmark(varnames, func)
+
+
+@pytest.mark.parametrize("func", _varnames_funcs)
+def test_varnames_legacy(benchmark, func: object) -> None:
+    benchmark(_varnames_legacy, func)