chore: 🗑️ Deprecate deprecated (#3118)

* 🗑️ Deprecate `deprecated`

* Update discord/utils.py

Co-authored-by: Dorukyum <53639936+Dorukyum@users.noreply.github.com>
Signed-off-by: Paillat <jeremiecotti@ik.me>

* Update discord/utils.py

Co-authored-by: Dorukyum <53639936+Dorukyum@users.noreply.github.com>
Signed-off-by: Lala Sabathil <aiko@aitsys.dev>

---------

Signed-off-by: Paillat <jeremiecotti@ik.me>
Signed-off-by: Lala Sabathil <aiko@aitsys.dev>
Co-authored-by: Lala Sabathil <lala@pycord.dev>
Co-authored-by: Dorukyum <53639936+Dorukyum@users.noreply.github.com>

Author: 3 people

discord/utils.py

@@ -64,6 +64,8 @@
     overload,
 )
 
+from typing_extensions import deprecated as ext_deprecated
+
 if TYPE_CHECKING:
     from discord import (
         Client,
@@ -94,6 +96,7 @@
 __all__ = (
     "parse_time",
     "warn_deprecated",
+    "deprecated",
     "oauth_url",
     "snowflake_time",
     "time_snowflake",
@@ -344,6 +347,63 @@ def warn_deprecated(
     warnings.warn(message, stacklevel=stacklevel, category=DeprecationWarning)
 
 
+@ext_deprecated(
+    "deprecated is deprecated since version 2.8, consider using warnings.deprecated instead."
+)
+def deprecated(
+    instead: str | None = None,
+    since: str | None = None,
+    removed: str | None = None,
+    reference: str | None = None,
+    stacklevel: int = 3,
+    *,
+    use_qualname: bool = True,
+) -> Callable[[Callable[[P], T]], Callable[[P], T]]:
+    """A decorator implementation of :func:`warn_deprecated`. This will automatically call :func:`warn_deprecated` when
+    the decorated function is called.
+
+    .. deprecated:: 2.8
+        Deprecated in favor of :func:`warnings.deprecated`.
+
+    Parameters
+    ----------
+    instead: Optional[:class:`str`]
+        A recommended alternative to the function.
+    since: Optional[:class:`str`]
+        The version in which the function was deprecated. This should be in the format ``major.minor(.patch)``, where
+        the patch version is optional.
+    removed: Optional[:class:`str`]
+        The version in which the function is planned to be removed. This should be in the format
+        ``major.minor(.patch)``, where the patch version is optional.
+    reference: Optional[:class:`str`]
+        A reference that explains the deprecation, typically a URL to a page such as a changelog entry or a GitHub
+        issue/PR.
+    stacklevel: :class:`int`
+        The stacklevel kwarg passed to :func:`warnings.warn`. Defaults to 3.
+    use_qualname: :class:`bool`
+        Whether to use the qualified name of the function in the deprecation warning. If ``False``, the short name of
+        the function will be used instead. For example, __qualname__ will display as ``Client.login`` while __name__
+        will display as ``login``. Defaults to ``True``.
+    """
+
+    def actual_decorator(func: Callable[[P], T]) -> Callable[[P], T]:
+        @functools.wraps(func)
+        def decorated(*args: P.args, **kwargs: P.kwargs) -> T:
+            warn_deprecated(
+                name=func.__qualname__ if use_qualname else func.__name__,
+                instead=instead,
+                since=since,
+                removed=removed,
+                reference=reference,
+                stacklevel=stacklevel,
+            )
+            return func(*args, **kwargs)
+
+        return decorated
+
+    return actual_decorator
+
+
 def oauth_url(
     client_id: int | str,
     *,