fixes after review by nicoddemus

Author: jakkdl

doc/en/deprecations.rst

@@ -14,7 +14,7 @@ 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>`
+Legacy callable form of :func:`raises <pytest.raises>`, :func:`warns <pytest.warns>` and :func:`deprecated_call <pytest.deprecated_call>`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. deprecated:: 8.4
@@ -30,13 +30,13 @@ to read and doesn't allow passing `match` or other parameters.
         return 6.28
 
 
-    # deprecated callable form
+    # Deprecated form, using callable + arguments
 
     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
+    # The calls above can be upgraded to the context-manager form
 
     with pytest.raises(ValueError) as excinfo:
         int("hello")
@@ -46,6 +46,10 @@ to read and doesn't allow passing `match` or other parameters.
         ret2 = my_warns("d", "e", "f")
 
 
+.. note::
+   This feature is not fully deprecated as of yet, awaiting the availability of an
+   automated tool to automatically fix code making extensive use of it.
+
 .. _sync-test-async-fixture:
 
 sync test depending on async fixture

src/_pytest/deprecated.py

@@ -11,7 +11,6 @@
 
 from __future__ import annotations
 
-import sys
 from typing import TYPE_CHECKING
 from warnings import warn
 
@@ -23,37 +22,40 @@
 
 # the `as` indicates explicit re-export to type checkers
 # mypy currently does not support overload+deprecated
-if sys.version_info >= (3, 13):
-    from warnings import deprecated as deprecated
-elif TYPE_CHECKING:
+if TYPE_CHECKING:
     from typing_extensions import deprecated as deprecated
 else:
 
     def deprecated(reason: str = "") -> object:
-        def decorator(func: object) -> object:
-            return func
-
-        return decorator
+        raise AssertionError(
+            "This decorator should only be used to indicate that overloads are deprecated"
+        )
+        # once py<3.13 is no longer supported, or when somebody wants to use decorators
+        # to deprecated, we can consider adapting this function to raise warnings
+        # at runtime
 
 
 CALLABLE_RAISES = PytestPendingDeprecationWarning(
     "The callable form of pytest.raises will be deprecated in a future version.\n"
     "Use `with pytest.raises(...):` instead.\n"
     "Full deprecation will not be made until there's a tool to automatically update"
-    " code to use the context-manager form"
+    " code to use the context-manager form.\n"
+    "See https://docs.pytest.org/en/stable/reference/deprecations.html#legacy-callable-form-of-raises-warns-and-deprecated-call"
 )
 
 CALLABLE_WARNS = PytestPendingDeprecationWarning(
     "The callable form of pytest.warns will be deprecated in a future version.\n"
     "Use `with pytest.warns(...):` instead."
     "Full deprecation will not be made until there's a tool to automatically update"
-    " code to use the context-manager form"
+    " code to use the context-manager form.\n"
+    "See https://docs.pytest.org/en/stable/reference/deprecations.html#legacy-callable-form-of-raises-warns-and-deprecated-call"
 )
 CALLABLE_DEPRECATED_CALL = PytestPendingDeprecationWarning(
     "The callable form of pytest.deprecated_call will be deprecated in a future version.\n"
     "Use `with pytest.deprecated_call():` instead."
     "Full deprecation will not be made until there's a tool to automatically update"
-    " code to use the context-manager form"
+    " code to use the context-manager form.\n"
+    "See https://docs.pytest.org/en/stable/reference/deprecations.html#legacy-callable-form-of-raises-warns-and-deprecated-call"
 )
 
 

src/_pytest/recwarn.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 a code block produces a ``DeprecationWarning`` or ``PendingDeprecationWarning`` or ``FutureWarning``.
+    """Assert that code produces a ``DeprecationWarning`` or ``PendingDeprecationWarning`` or ``FutureWarning``.
 
-    This function is used as a context manager::
+    This function can be used as a context manager::
 
         >>> import warnings
         >>> def api_call_v2():
@@ -77,14 +77,19 @@ def deprecated_call(
         >>> with pytest.deprecated_call(match="^use v3 of this api$") as warning_messages:
         ...    assert api_call_v2() == 200
 
-    You may use the keyword argument ``match`` to assert
+    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
     that the warning matches a text or regex.
 
-    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).
+    The context manager 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
+    # 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)
@@ -118,7 +123,7 @@ def warns(
     *args: Any,
     **kwargs: Any,
 ) -> WarningsChecker | Any:
-    r"""Assert that a code block raises a particular class of warning.
+    r"""Assert that code 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
@@ -128,13 +133,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.
 
-    Use this function as a context manager::
+    This function can be used as a context manager::
 
         >>> import pytest
         >>> with pytest.warns(RuntimeWarning):
         ...    warnings.warn("my warning", RuntimeWarning)
 
-    You can use the keyword argument ``match`` to assert
+    In the context manager form you may 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'):