undo deprecation

Author: jakkdl

.coveragerc

@@ -27,7 +27,7 @@ exclude_lines =
     ^\s*assert False(,|$)
     ^\s*assert_never\(
 
-    ^\s*if TYPE_CHECKING:
+    ^\s*(el)?if TYPE_CHECKING:
     ^\s*@overload( |$)
     ^\s*def .+: \.\.\.$
 

doc/en/conf.py

@@ -97,6 +97,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

doc/en/how-to/assert.rst

@@ -282,6 +282,10 @@ exception at a specific level; exceptions contained directly in the top
 Alternate `pytest.raises` form (legacy)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. warning::
+   This will be deprecated and removed in a future release.
+
+
 There is an alternate form of :func:`pytest.raises` where you pass
 a function that will be executed, along with ``*args`` and ``**kwargs``. :func:`pytest.raises`
 will then execute the function with those arguments and assert that the given exception is raised:
@@ -301,7 +305,6 @@ 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/capture-warnings.rst

@@ -338,13 +338,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:

src/_pytest/python_api.py

@@ -16,6 +16,9 @@
 
 if TYPE_CHECKING:
     from numpy import ndarray
+    from typing_extensions import ParamSpec
+
+    P = ParamSpec("P")
 
 
 def _compare_approx(

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(
         >>> raises(ZeroDivisionError, f, x=0)
         <ExceptionInfo ...>
 
-    The form above is fully supported but discouraged for new code because the
+    The form above is going to be deprecated in a future pytest release as the
     context manager form is regarded as more readable and less error-prone.
 
     .. note::
@@ -272,7 +273,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))
@@ -289,11 +290,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(
@@ -67,6 +70,8 @@ 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
@@ -76,14 +81,17 @@ def deprecated_call(
     that the warning matches a text or regex.
 
     The context manager produces a list of :class:`warnings.WarningMessage` objects,
-    one for each warning raised.
+    one for each warning emitted
+    (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
-    )
+    # Potential QoL: allow `with deprecated_call:` - i.e. no parens
+    dep_warnings = (DeprecationWarning, PendingDeprecationWarning, FutureWarning)
+    if func is None:
+        return warns(dep_warnings, *args, **kwargs)
+
+    with warns(dep_warnings):
+        return func(*args, **kwargs)
 
 
 @overload
@@ -97,16 +105,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.
@@ -151,7 +159,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(
@@ -160,11 +169,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):

testing/_py/test_local.py

@@ -625,7 +625,8 @@ def test_chdir_gone(self, path1):
         p = path1.ensure("dir_to_be_removed", dir=1)
         p.chdir()
         p.remove()
-        pytest.raises(error.ENOENT, local)
+        with pytest.raises(error.ENOENT):
+            local()
         assert path1.chdir() is None
         assert os.getcwd() == str(path1)
 
@@ -998,8 +999,10 @@ def test_locked_make_numbered_dir(self, tmpdir):
                 assert numdir.new(ext=str(j)).check()
 
     def test_error_preservation(self, path1):
-        pytest.raises(EnvironmentError, path1.join("qwoeqiwe").mtime)
-        pytest.raises(EnvironmentError, path1.join("qwoeqiwe").read)
+        with pytest.raises(EnvironmentError):
+            path1.join("qwoeqiwe").mtime()
+        with pytest.raises(EnvironmentError):
+            path1.join("qwoeqiwe").read()
 
     # def test_parentdirmatch(self):
     #    local.parentdirmatch('std', startmodule=__name__)
@@ -1099,7 +1102,8 @@ def test_pyimport_check_filepath_consistency(self, monkeypatch, tmpdir):
         pseudopath = tmpdir.ensure(name + "123.py")
         mod.__file__ = str(pseudopath)
         monkeypatch.setitem(sys.modules, name, mod)
-        excinfo = pytest.raises(pseudopath.ImportMismatchError, p.pyimport)
+        with pytest.raises(pseudopath.ImportMismatchError) as excinfo:
+            p.pyimport()
         modname, modfile, orig = excinfo.value.args
         assert modname == name
         assert modfile == pseudopath
@@ -1397,7 +1401,8 @@ def test_stat_helpers(self, tmpdir, monkeypatch):
 
     def test_stat_non_raising(self, tmpdir):
         path1 = tmpdir.join("file")
-        pytest.raises(error.ENOENT, lambda: path1.stat())
+        with pytest.raises(error.ENOENT):
+            path1.stat()
         res = path1.stat(raising=False)
         assert res is None
 

testing/code/test_code.py

@@ -85,10 +85,8 @@ def test_code_from_func() -> None:
 def test_unicode_handling() -> None:
     value = "ąć".encode()
 
-    def f() -> None:
+    with pytest.raises(Exception) as excinfo:
         raise Exception(value)
-
-    excinfo = pytest.raises(Exception, f)
     str(excinfo)