Add ParamSpec to legacy callable forms of raises/warns/deprecated_call

`pytest.raises`, `warns` & `deprecated_call` previously typed `*args`
and `**kwargs` as `Any` in the legacy callable form, so this did not
raise errors:

```py
def foo(x: int) -> None:
    raise ValueError
raises(ValueError, foo, None)
```

but now it will give call-overload.

It also makes it possible to pass `func` as a kwarg, which the type
hints previously showed as possible, but it didn't work.

It's possible that `func` (and the expected type?) should be pos-only,
as this looks quite weird:

```py
raises(1, 2, kwarg1=3, func=my_func, kwarg2=4, expected_exception=ValueError)
```

but if somebody is dynamically generating parameters to send to `raises`
then we probably shouldn't ban it needlessly; and we can't make `func`
pos-only without making `expected_exception` pos-only, and that could
break backwards compatibility.

Author: jakkdl

changelog/13241.improvement.rst

@@ -0,0 +1,2 @@
+:func:`pytest.raises`, :func:`pytest.warns` and :func:`pytest.deprecated_call` now uses :class:`ParamSpec` for the type hint to the (old and not recommended) callable overload, instead of :class:`Any`. This allows type checkers to raise errors when passing incorrect function parameters.
+``func`` can now also be passed as a kwarg, which the type hint previously showed as possible but didn't accept.

doc/en/conf.py

@@ -102,6 +102,10 @@
     # TypeVars
     ("py:class", "_pytest._code.code.E"),
     ("py:class", "E"),  # due to delayed annotation
+    ("py:class", "T"),
+    ("py:class", "P"),
+    ("py:class", "P.args"),
+    ("py:class", "P.kwargs"),
     ("py:class", "_pytest.fixtures.FixtureFunction"),
     ("py:class", "_pytest.nodes._NodeType"),
     ("py:class", "_NodeType"),  # due to delayed annotation

pyproject.toml

@@ -453,6 +453,7 @@ exclude_lines = [
     '^\s*case unreachable:',
     '^\s*assert_never\(',
     '^\s*if TYPE_CHECKING:',
+    '^\s*(el)?if TYPE_CHECKING:',
     '^\s*@overload( |$)',
     '^\s*def .+: \.\.\.$',
     '^\s*@pytest\.mark\.xfail',

src/_pytest/raises.py

@@ -95,14 +95,15 @@ def raises(*, check: Callable[[BaseException], bool]) -> RaisesExc[BaseException
 @overload
 def raises(
     expected_exception: type[E] | tuple[type[E], ...],
-    func: Callable[..., Any],
-    *args: Any,
-    **kwargs: Any,
+    func: Callable[P, object],
+    *args: P.args,
+    **kwargs: P.kwargs,
 ) -> ExceptionInfo[E]: ...
 
 
 def raises(
     expected_exception: type[E] | tuple[type[E], ...] | None = None,
+    func: Callable[P, object] | None = None,
     *args: Any,
     **kwargs: Any,
 ) -> RaisesExc[BaseException] | ExceptionInfo[E]:
@@ -253,7 +254,7 @@ def raises(
     """
     __tracebackhide__ = True
 
-    if not args:
+    if func is None and not args:
         if set(kwargs) - {"match", "check", "expected_exception"}:
             msg = "Unexpected keyword arguments passed to pytest.raises: "
             msg += ", ".join(sorted(kwargs))
@@ -270,11 +271,10 @@ def raises(
             f"Raising exceptions is already understood as failing the test, so you don't need "
             f"any special code to say 'this should never raise an exception'."
         )
-    func = args[0]
     if not callable(func):
         raise TypeError(f"{func!r} object (type: {type(func)}) must be callable")
     with RaisesExc(expected_exception) as excinfo:
-        func(*args[1:], **kwargs)
+        func(*args, **kwargs)
     try:
         return excinfo
     finally:

src/_pytest/recwarn.py

@@ -17,8 +17,11 @@
 
 
 if TYPE_CHECKING:
+    from typing_extensions import ParamSpec
     from typing_extensions import Self
 
+    P = ParamSpec("P")
+
 import warnings
 
 from _pytest.deprecated import check_ispytest
@@ -49,7 +52,7 @@ def deprecated_call(
 
 
 @overload
-def deprecated_call(func: Callable[..., T], *args: Any, **kwargs: Any) -> T: ...
+def deprecated_call(func: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> T: ...
 
 
 def deprecated_call(
@@ -78,11 +81,12 @@ def deprecated_call(
     (regardless of whether it is an ``expected_warning`` or not).
     """
     __tracebackhide__ = True
-    if func is not None:
-        args = (func, *args)
-    return warns(
-        (DeprecationWarning, PendingDeprecationWarning, FutureWarning), *args, **kwargs
-    )
+    dep_warnings = (DeprecationWarning, PendingDeprecationWarning, FutureWarning)
+    if func is None:
+        return warns(dep_warnings, *args, **kwargs)
+
+    with warns(dep_warnings):
+        return func(*args, **kwargs)
 
 
 @overload
@@ -96,16 +100,16 @@ def warns(
 @overload
 def warns(
     expected_warning: type[Warning] | tuple[type[Warning], ...],
-    func: Callable[..., T],
-    *args: Any,
-    **kwargs: Any,
+    func: Callable[P, T],
+    *args: P.args,
+    **kwargs: P.kwargs,
 ) -> T: ...
 
 
 def warns(
     expected_warning: type[Warning] | tuple[type[Warning], ...] = Warning,
+    func: Callable[..., object] | None = None,
     *args: Any,
-    match: str | re.Pattern[str] | None = None,
     **kwargs: Any,
 ) -> WarningsChecker | Any:
     r"""Assert that code raises a particular class of warning.
@@ -152,7 +156,8 @@ def warns(
 
     """
     __tracebackhide__ = True
-    if not args:
+    if func is None and not args:
+        match: str | re.Pattern[str] | None = kwargs.pop("match", None)
         if kwargs:
             argnames = ", ".join(sorted(kwargs))
             raise TypeError(
@@ -161,11 +166,10 @@ def warns(
             )
         return WarningsChecker(expected_warning, match_expr=match, _ispytest=True)
     else:
-        func = args[0]
         if not callable(func):
             raise TypeError(f"{func!r} object (type: {type(func)}) must be callable")
         with WarningsChecker(expected_warning, _ispytest=True):
-            return func(*args[1:], **kwargs)
+            return func(*args, **kwargs)
 
 
 class WarningsRecorder(warnings.catch_warnings):