compat: add compat for @warnings.deprecated

We intend to start using it.

Author: bluetech

src/_pytest/compat.py

@@ -15,6 +15,7 @@
 from typing import Any
 from typing import Final
 from typing import NoReturn
+from typing import TYPE_CHECKING
 
 import py
 
@@ -311,3 +312,17 @@ def running_on_ci() -> bool:
     # Only enable CI mode if one of these env variables is defined and non-empty.
     env_vars = ["CI", "BUILD_NUMBER"]
     return any(os.environ.get(var) for var in env_vars)
+
+
+if sys.version_info >= (3, 13):
+    from warnings import deprecated as deprecated
+else:
+    if TYPE_CHECKING:
+        from typing_extensions import deprecated as deprecated
+    else:
+
+        def deprecated(msg, /, *, category=None, stacklevel=1):
+            def decorator(func):
+                return func
+
+            return decorator

testing/test_compat.py

@@ -5,20 +5,18 @@
 from functools import cached_property
 from functools import partial
 from functools import wraps
-from typing import TYPE_CHECKING
+from typing import Literal
+import warnings
 
 from _pytest.compat import assert_never
+from _pytest.compat import deprecated
 from _pytest.compat import get_real_func
 from _pytest.compat import safe_getattr
 from _pytest.compat import safe_isclass
 from _pytest.outcomes import OutcomeException
 import pytest
 
 
-if TYPE_CHECKING:
-    from typing import Literal
-
-
 def test_real_func_loop_limit() -> None:
     class Evil:
         def __init__(self):
@@ -192,3 +190,15 @@ def test_assert_never_literal() -> None:
         pass
     else:
         assert_never(x)
+
+
+def test_deprecated() -> None:
+    # This test is mostly for coverage.
+
+    @deprecated("This is deprecated!")
+    def old_way() -> str:
+        return "human intelligence"
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", DeprecationWarning)
+        assert old_way() == "human intelligence"  # type: ignore[deprecated]