add paramspec to raises

Author: jakkdl

changelog/12141.improvement.rst

@@ -0,0 +1 @@
+:func:`pytest.raises` now uses :class:`ParamSpec` for the type hint to the legacy callable overload, instead of :class:`Any`. Also ``func`` can now be passed as a kwarg, which the type hint previously showed as possible but didn't accept.

src/_pytest/python_api.py

@@ -33,6 +33,9 @@
 
 if TYPE_CHECKING:
     from numpy import ndarray
+    from typing_extensions import ParamSpec
+
+    P = ParamSpec("P")
 
 
 def _compare_approx(
@@ -805,14 +808,17 @@ def raises(
 @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,
 ) -> _pytest._code.ExceptionInfo[E]: ...
 
 
 def raises(
-    expected_exception: type[E] | tuple[type[E], ...], *args: Any, **kwargs: Any
+    expected_exception: type[E] | tuple[type[E], ...],
+    func: Callable[P, object] | None = None,
+    *args: Any,
+    **kwargs: Any,
 ) -> RaisesContext[E] | _pytest._code.ExceptionInfo[E]:
     r"""Assert that a code block/function call raises an exception type, or one of its subclasses.
 
@@ -1003,7 +1009,7 @@ def validate_exc(exc: type[E]) -> type[E]:
 
     message = f"DID NOT RAISE {expected_exception}"
 
-    if not args:
+    if func is None and not args:
         match: str | re.Pattern[str] | None = kwargs.pop("match", None)
         if kwargs:
             msg = "Unexpected keyword arguments passed to pytest.raises: "
@@ -1012,11 +1018,10 @@ def validate_exc(exc: type[E]) -> type[E]:
             raise TypeError(msg)
         return RaisesContext(expected_exceptions, message, match)
     else:
-        func = args[0]
         if not callable(func):
             raise TypeError(f"{func!r} object (type: {type(func)}) must be callable")
         try:
-            func(*args[1:], **kwargs)
+            func(*args, **kwargs)
         except expected_exceptions as e:
             return _pytest._code.ExceptionInfo.from_exception(e)
     fail(message)

testing/python/raises.py

@@ -231,7 +231,7 @@ def test_raises_match(self) -> None:
             pytest.raises(ValueError, int, "asdf").match(msg)
         assert str(excinfo.value) == expr
 
-        pytest.raises(TypeError, int, match="invalid")
+        pytest.raises(TypeError, int, match="invalid")  # type: ignore[call-overload]
 
         def tfunc(match):
             raise ValueError(f"match={match}")
@@ -337,3 +337,11 @@ def test_issue_11872(self) -> None:
 
         with pytest.raises(HTTPError, match="Not Found"):
             raise HTTPError(code=404, msg="Not Found", fp=None, hdrs=None, url="")  # type: ignore [arg-type]
+
+    def test_callable_func_kwarg(self) -> None:
+        # raises previously assumed that `func` was passed as positional, but
+        # the type hint indicated it could be a keyword parameter
+        def my_raise() -> None:
+            raise ValueError
+
+        pytest.raises(expected_exception=ValueError, func=my_raise)

testing/test_capture.py

@@ -853,7 +853,7 @@ def test_text(self) -> None:
     def test_unicode_and_str_mixture(self) -> None:
         f = capture.CaptureIO()
         f.write("\u00f6")
-        pytest.raises(TypeError, f.write, b"hello")
+        pytest.raises(TypeError, f.write, b"hello")  # type: ignore[call-overload]
 
     def test_write_bytes_to_buffer(self) -> None:
         """In python3, stdout / stderr are text io wrappers (exposing a buffer
@@ -880,7 +880,7 @@ def test_unicode_and_str_mixture(self) -> None:
         sio = io.StringIO()
         f = capture.TeeCaptureIO(sio)
         f.write("\u00f6")
-        pytest.raises(TypeError, f.write, b"hello")
+        pytest.raises(TypeError, f.write, b"hello")  # type: ignore[call-overload]
 
 
 def test_dontreadfrominput() -> None:
@@ -900,7 +900,7 @@ def test_dontreadfrominput() -> None:
     assert not f.seekable()
     pytest.raises(UnsupportedOperation, f.tell)
     pytest.raises(UnsupportedOperation, f.truncate, 0)
-    pytest.raises(UnsupportedOperation, f.write, b"")
+    pytest.raises(UnsupportedOperation, f.write, b"")  # type: ignore[call-overload]
     pytest.raises(UnsupportedOperation, f.writelines, [])
     assert not f.writable()
     assert isinstance(f.encoding, str)
@@ -1635,7 +1635,7 @@ def test_encodedfile_writelines(tmpfile: BinaryIO) -> None:
 
 def test__get_multicapture() -> None:
     assert isinstance(_get_multicapture("no"), MultiCapture)
-    pytest.raises(ValueError, _get_multicapture, "unknown").match(
+    pytest.raises(ValueError, _get_multicapture, "unknown").match(  # type: ignore[call-overload]
         r"^unknown capturing method: 'unknown'"
     )