♻️ move deprecation utilities to private utils and update references

Paillat-dev · Paillat-dev · commit 162d1559ead4 · 2025-06-24T16:08:52.000+02:00
diff --git a/CHANGELOG-V3.md b/CHANGELOG-V3.md
@@ -17,4 +17,6 @@ release.
 - `utils.sleep_until`
 - `utils.resolve_invite`
 - `utils.parse_time`
-- `utils.time_snowflake` use `utils.generate_snowflake` instead
+- `utils.time_snowflake` use `utils.generate_snowflake` instead
+- `utils.warn_deprecated`
+- `utils.deprecated`
diff --git a/discord/__version.py b/discord/__version.py
@@ -35,7 +35,7 @@
 
 from typing import Literal, NamedTuple
 
-from .utils import deprecated
+from .utils.private import deprecated
 from ._version import __version__, __version_tuple__
 
 
diff --git a/discord/abc.py b/discord/abc.py
@@ -41,6 +41,7 @@
     runtime_checkable,
 )
 
+from .utils.private import warn_deprecated
 from . import utils
 from .context_managers import Typing
 from .enums import ChannelType
@@ -1529,7 +1530,7 @@ async def send(
                 from .message import MessageReference
 
                 if not isinstance(reference, MessageReference):
-                    utils.warn_deprecated(
+                    warn_deprecated(
                         f"Passing {type(reference).__name__} to reference",
                         "MessageReference",
                         "2.7",
diff --git a/discord/appinfo.py b/discord/appinfo.py
@@ -27,6 +27,7 @@
 
 from typing import TYPE_CHECKING
 
+from .utils.private import warn_deprecated
 from .utils.private import get_as_snowflake
 from . import utils
 from .asset import Asset
@@ -262,7 +263,7 @@ def summary(self) -> str | None:
         .. versionadded:: 1.3
         .. deprecated:: 2.7
         """
-        utils.warn_deprecated(
+        warn_deprecated(
             "summary",
             "description",
             reference="https://discord.com/developers/docs/resources/application#application-object-application-structure",
diff --git a/discord/commands/core.py b/discord/commands/core.py
@@ -68,7 +68,8 @@
 from ..role import Role
 from ..threads import Thread
 from ..user import User
-from ..utils import MISSING, async_all, find, maybe_coroutine, utcnow, warn_deprecated
+from ..utils import MISSING, async_all, find, maybe_coroutine, utcnow
+from ..utils.private import warn_deprecated
 from .context import ApplicationContext, AutocompleteContext
 from .options import Option, OptionChoice
 
diff --git a/discord/ext/bridge/core.py b/discord/ext/bridge/core.py
@@ -40,7 +40,8 @@
     SlashCommandOptionType,
 )
 
-from ...utils import MISSING, find, get, warn_deprecated
+from ...utils import MISSING, find, get
+from ...utils.private import warn_deprecated
 from ..commands import (
     BadArgument,
 )
diff --git a/discord/http.py b/discord/http.py
@@ -47,7 +47,8 @@
 )
 from .file import VoiceMessage
 from .gateway import DiscordClientWebSocketResponse
-from .utils import MISSING, warn_deprecated
+from .utils import MISSING
+from .utils.private import warn_deprecated
 
 _log = logging.getLogger(__name__)
 
diff --git a/discord/interactions.py b/discord/interactions.py
@@ -292,7 +292,7 @@ def is_component(self) -> bool:
         return self.type == InteractionType.component
 
     @utils.cached_slot_property("_cs_channel")
-    @utils.deprecated("Interaction.channel", "2.7", stacklevel=4)
+    @discord.utils.private.deprecated("Interaction.channel", "2.7", stacklevel=4)
     def cached_channel(self) -> InteractionChannel | None:
         """The cached channel from which the interaction was sent.
         DM channels are not resolved. These are :class:`PartialMessageable` instead.
@@ -428,7 +428,7 @@ async def original_response(self) -> InteractionMessage:
         self._original_response = message
         return message
 
-    @utils.deprecated("Interaction.original_response", "2.2")
+    @discord.utils.private.deprecated("Interaction.original_response", "2.2")
     async def original_message(self):
         """An alias for :meth:`original_response`.
 
@@ -555,7 +555,7 @@ async def edit_original_response(
 
         return message
 
-    @utils.deprecated("Interaction.edit_original_response", "2.2")
+    @discord.utils.private.deprecated("Interaction.edit_original_response", "2.2")
     async def edit_original_message(self, **kwargs):
         """An alias for :meth:`edit_original_response`.
 
@@ -613,7 +613,7 @@ async def delete_original_response(self, *, delay: float | None = None) -> None:
         else:
             await func
 
-    @utils.deprecated("Interaction.delete_original_response", "2.2")
+    @discord.utils.private.deprecated("Interaction.delete_original_response", "2.2")
     async def delete_original_message(self, **kwargs):
         """An alias for :meth:`delete_original_response`.
 
@@ -1238,7 +1238,7 @@ async def send_modal(self, modal: Modal) -> Interaction:
         self._parent._state.store_modal(modal, self._parent.user.id)
         return self._parent
 
-    @utils.deprecated("a button with type ButtonType.premium", "2.6")
+    @discord.utils.private.deprecated("a button with type ButtonType.premium", "2.6")
     async def premium_required(self) -> Interaction:
         """|coro|
 
diff --git a/discord/message.py b/discord/message.py
@@ -41,7 +41,7 @@
 )
 from urllib.parse import parse_qs, urlparse
 
-from .utils.private import get_as_snowflake, parse_time
+from .utils.private import get_as_snowflake, parse_time, warn_deprecated
 from . import utils
 from .channel import PartialMessageable
 from .components import _component_factory
@@ -1245,7 +1245,7 @@ def _rebind_cached_references(self, new_guild: Guild, new_channel: TextChannel |
 
     @property
     def interaction(self) -> MessageInteraction | None:
-        utils.warn_deprecated(
+        warn_deprecated(
             "interaction",
             "interaction_metadata",
             "2.6",
@@ -1255,7 +1255,7 @@ def interaction(self) -> MessageInteraction | None:
 
     @interaction.setter
     def interaction(self, value: MessageInteraction | None) -> None:
-        utils.warn_deprecated(
+        warn_deprecated(
             "interaction",
             "interaction_metadata",
             "2.6",
diff --git a/discord/utils/__init__.py b/discord/utils/__init__.py
@@ -29,12 +29,10 @@
 import asyncio
 import collections.abc
 import datetime
-import functools
 import json
 import re
 import sys
 import types
-import warnings
 from bisect import bisect_left
 from enum import Enum, auto
 from inspect import isawaitable as _isawaitable
@@ -73,8 +71,6 @@
 
 
 __all__ = (
-    "warn_deprecated",
-    "deprecated",
     "oauth_url",
     "snowflake_time",
     "find",
@@ -240,102 +236,6 @@ def decorator(overridden: T) -> T:
     return decorator
 
 
-def warn_deprecated(
-    name: str,
-    instead: str | None = None,
-    since: str | None = None,
-    removed: str | None = None,
-    reference: str | None = None,
-    stacklevel: int = 3,
-) -> None:
-    """Warn about a deprecated function, with the ability to specify details about the deprecation. Emits a
-    DeprecationWarning.
-
-    Parameters
-    ----------
-    name: str
-        The name of the deprecated function.
-    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.
-    """
-    warnings.simplefilter("always", DeprecationWarning)  # turn off filter
-    message = f"{name} is deprecated"
-    if since:
-        message += f" since version {since}"
-    if removed:
-        message += f" and will be removed in version {removed}"
-    if instead:
-        message += f", consider using {instead} instead"
-    message += "."
-    if reference:
-        message += f" See {reference} for more information."
-
-    warnings.warn(message, stacklevel=stacklevel, category=DeprecationWarning)
-    warnings.simplefilter("default", DeprecationWarning)  # reset filter
-
-
-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.
-
-    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,
     *,
diff --git a/discord/utils/private.py b/discord/utils/private.py
@@ -1,11 +1,14 @@
 from __future__ import annotations
 
 import datetime
+import functools
 import re
 import unicodedata
+import warnings
 from base64 import b64encode
-from typing import TYPE_CHECKING, Any, overload
+from typing import TYPE_CHECKING, Any, overload, Callable
 
+from . import P, T
 from ..errors import InvalidArgument
 
 if TYPE_CHECKING:
@@ -158,3 +161,99 @@ def parse_time(timestamp: str | None) -> datetime.datetime | None:
     if timestamp:
         return datetime.datetime.fromisoformat(timestamp)
     return None
+
+
+def warn_deprecated(
+    name: str,
+    instead: str | None = None,
+    since: str | None = None,
+    removed: str | None = None,
+    reference: str | None = None,
+    stacklevel: int = 3,
+) -> None:
+    """Warn about a deprecated function, with the ability to specify details about the deprecation. Emits a
+    DeprecationWarning.
+
+    Parameters
+    ----------
+    name: str
+        The name of the deprecated function.
+    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.
+    """
+    warnings.simplefilter("always", DeprecationWarning)  # turn off filter
+    message = f"{name} is deprecated"
+    if since:
+        message += f" since version {since}"
+    if removed:
+        message += f" and will be removed in version {removed}"
+    if instead:
+        message += f", consider using {instead} instead"
+    message += "."
+    if reference:
+        message += f" See {reference} for more information."
+
+    warnings.warn(message, stacklevel=stacklevel, category=DeprecationWarning)
+    warnings.simplefilter("default", DeprecationWarning)  # reset filter
+
+
+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.
+
+    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

Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,8 @@`
`40`	`40`	`SlashCommandOptionType,`
`41`	`41`	`)`
`42`	`42`
`43`		`-from ...utils import MISSING, find, get, warn_deprecated`
	`43`	`+from ...utils import MISSING, find, get`
	`44`	`+from ...utils.private import warn_deprecated`
`44`	`45`	`from ..commands import (`
`45`	`46`	`BadArgument,`
`46`	`47`	`)`
Original file line number	Diff line number	Diff line change
`@@ -47,7 +47,8 @@`
`47`	`47`	`)`
`48`	`48`	`from .file import VoiceMessage`
`49`	`49`	`from .gateway import DiscordClientWebSocketResponse`
`50`		`-from .utils import MISSING, warn_deprecated`
	`50`	`+from .utils import MISSING`
	`51`	`+from .utils.private import warn_deprecated`
`51`	`52`
`52`	`53`	`_log = logging.getLogger(__name__)`
`53`	`54`