update docs, add changelog, fix tests

Author: jakkdl

changelog/12141.improvement.rst

@@ -0,0 +1 @@
+The legacy callable form of :func:`pytest.raises`, :func:`pytest.warns` and :func:`pytest.deprecated_call` has been deprecated. Use the context-manager form instead.

changelog/13241.deprecation.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 (now-deprecated) 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.

changelog/13241.improvement.rst

@@ -14,6 +14,37 @@ Deprecated Features
 Below is a complete list of all pytest features which are considered deprecated. Using those features will issue
 :class:`~pytest.PytestWarning` or subclasses, which can be filtered using :ref:`standard warning filters <warnings>`.
 
+legacy callable form of :func:`raises<pytest.raises>`, :func:`warns<pytest.warns>` and :func:`deprecated_call<pytest.deprecated_call>`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 8.4
+
+Pytest created the callable form of :func:`pytest.raises`, :func:`pytest.warns` and :func:`pytest.deprecated_call` before
+the ``with`` statement was added in :pep:`python 2.5 <343>`. It has been kept for a long time, but is considered harder
+to read and doesn't allow passing `match` or other parameters.
+
+.. code-block:: python
+
+    def my_warn(par1, par2, par3):
+        warnings.warn(DeprecationWarning(f"{par1}{par2}{par3}"))
+        return 6.28
+
+
+    # deprecated callable form
+
+    excinfo = pytest.raises(ValueError, int, "hello")
+    ret1 = pytest.warns(DeprecationWarning, my_warns, "a", "b", "c")
+    ret2 = pytest.deprecated_call(my_warns, "d", "e", "f")
+
+    # context-manager form
+
+    with pytest.raises(ValueError) as excinfo:
+        int("hello")
+    with pytest.warns(DeprecationWarning):
+        ret1 = my_warns("a", "b", "c")
+    with pytest.deprecated_call():
+        ret2 = my_warns("d", "e", "f")
+
 
 .. _sync-test-async-fixture:
 

doc/en/deprecations.rst

@@ -194,30 +194,6 @@ exception at a specific level; exceptions contained directly in the top
         assert not excinfo.group_contains(RuntimeError, depth=2)
         assert not excinfo.group_contains(TypeError, depth=1)
 
-Alternate form (legacy)
-~~~~~~~~~~~~~~~~~~~~~~~
-
-There is an alternate form where you pass
-a function that will be executed, along ``*args`` and ``**kwargs``, and :func:`pytest.raises`
-will execute the function with the arguments and assert that the given exception is raised:
-
-.. code-block:: python
-
-    def func(x):
-        if x <= 0:
-            raise ValueError("x needs to be larger than zero")
-
-
-    pytest.raises(ValueError, func, x=-1)
-
-The reporter will provide you with helpful output in case of failures such as *no
-exception* or *wrong exception*.
-
-This form was the original :func:`pytest.raises` API, developed before the ``with`` statement was
-added to the Python language. Nowadays, this form is rarely used, with the context-manager form (using ``with``)
-being considered more readable.
-Nonetheless, this form is fully supported and not deprecated in any way.
-
 xfail mark and pytest.raises
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/en/how-to/assert.rst

@@ -337,13 +337,6 @@ Some examples:
     ...     warnings.warn("issue with foo() func")
     ...
 
-You can also call :func:`pytest.warns` on a function or code string:
-
-.. code-block:: python
-
-    pytest.warns(expected_warning, func, *args, **kwargs)
-    pytest.warns(expected_warning, "func(*args, **kwargs)")
-
 The function also returns a list of all raised warnings (as
 ``warnings.WarningMessage`` objects), which you can query for
 additional information:

doc/en/how-to/capture-warnings.rst

@@ -824,7 +824,7 @@ def raises(
     *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.
+    r"""Assert that a code block raises an exception type, or one of its subclasses.
 
     :param expected_exception:
         The expected exception type, or a tuple if one of multiple possible
@@ -930,25 +930,6 @@ def raises(
 
         :ref:`assertraises` for more examples and detailed discussion.
 
-    **Legacy form**
-
-    It is possible to specify a callable by passing a to-be-called lambda::
-
-        >>> raises(ZeroDivisionError, lambda: 1/0)
-        <ExceptionInfo ...>
-
-    or you can specify an arbitrary callable with arguments::
-
-        >>> def f(x): return 1/x
-        ...
-        >>> raises(ZeroDivisionError, f, 0)
-        <ExceptionInfo ...>
-        >>> raises(ZeroDivisionError, f, x=0)
-        <ExceptionInfo ...>
-
-    The form above is fully supported but discouraged for new code because the
-    context manager form is regarded as more readable and less error-prone.
-
     .. note::
         Similar to caught exception objects in Python, explicitly clearing
         local references to returned ``ExceptionInfo`` objects can

src/_pytest/python_api.py

@@ -62,9 +62,9 @@ def deprecated_call(func: Callable[P, T], *args: P.args, **kwargs: P.kwargs) ->
 def deprecated_call(
     func: Callable[..., Any] | None = None, *args: Any, **kwargs: Any
 ) -> WarningsRecorder | Any:
-    """Assert that code produces a ``DeprecationWarning`` or ``PendingDeprecationWarning`` or ``FutureWarning``.
+    """Assert that a code block produces a ``DeprecationWarning`` or ``PendingDeprecationWarning`` or ``FutureWarning``.
 
-    This function can be used as a context manager::
+    This function is used as a context manager::
 
         >>> import warnings
         >>> def api_call_v2():
@@ -74,16 +74,14 @@ def deprecated_call(
         >>> import pytest
         >>> with pytest.deprecated_call():
         ...    assert api_call_v2() == 200
+        >>> with pytest.deprecated_call(match="^use v3 of this api$") as warning_messages:
+        ...    assert api_call_v2() == 200
 
-    It can also be used by passing a function and ``*args`` and ``**kwargs``,
-    in which case it will ensure calling ``func(*args, **kwargs)`` produces one of
-    the warnings types above. The return value is the return value of the function.
-
-    In the context manager form you may use the keyword argument ``match`` to assert
+    You may use the keyword argument ``match`` to assert
     that the warning matches a text or regex.
 
-    The context manager produces a list of :class:`warnings.WarningMessage` objects,
-    one for each warning raised.
+    This helper produces a list of :class:`warnings.WarningMessage` objects, one for
+    each warning emitted (regardless of whether it is an ``expected_warning`` or not).
     """
     __tracebackhide__ = True
     # potential QoL: allow `with deprecated_call:` - i.e. no parens
@@ -119,7 +117,7 @@ def warns(
     *args: Any,
     **kwargs: Any,
 ) -> WarningsChecker | Any:
-    r"""Assert that code raises a particular class of warning.
+    r"""Assert that a code block raises a particular class of warning.
 
     Specifically, the parameter ``expected_warning`` can be a warning class or tuple
     of warning classes, and the code inside the ``with`` block must issue at least one
@@ -129,13 +127,13 @@ def warns(
     each warning emitted (regardless of whether it is an ``expected_warning`` or not).
     Since pytest 8.0, unmatched warnings are also re-emitted when the context closes.
 
-    This function can be used as a context manager::
+    Use this function as a context manager::
 
         >>> import pytest
         >>> with pytest.warns(RuntimeWarning):
         ...    warnings.warn("my warning", RuntimeWarning)
 
-    In the context manager form you may use the keyword argument ``match`` to assert
+    You can use the keyword argument ``match`` to assert
     that the warning matches a text or regex::
 
         >>> with pytest.warns(UserWarning, match='must be 0 or None'):

src/_pytest/recwarn.py

@@ -6,5 +6,5 @@
 
 @pytest.fixture
 def arg2(request):
-    with pytest.raises(Exception):  # noqa: B017
+    with pytest.raises(Exception):  # noqa: B017  # too general exception
         request.getfixturevalue("arg1")

testing/example_scripts/fixtures/fill_fixtures/test_conftest_funcargs_only_available_in_subdir/sub2/conftest.py

@@ -310,7 +310,7 @@ def test_1():
         )
         child = pytester.spawn_pytest(f"--pdb {p1}")
         child.expect(".*def test_1")
-        child.expect(".*pytest.raises.*globalfunc")
+        child.expect(r"with pytest.raises\(ValueError\)")
         child.expect("Pdb")
         child.sendline("globalfunc")
         child.expect(".*function")