♻️ move oauth_url and Undefined class to public.py; update imports

Author: Paillat-dev

discord/utils/__init__.py

@@ -58,7 +58,7 @@
 )
 
 from ..errors import HTTPException
-from .public import basic_autocomplete, generate_snowflake, utcnow, snowflake_time
+from .public import basic_autocomplete, generate_snowflake, utcnow, snowflake_time, oauth_url, Undefined, MISSING
 
 try:
     import msgspec
@@ -88,19 +88,11 @@
     "format_dt",
     "generate_snowflake",
     "basic_autocomplete",
+    "Undefined",
+    "MISSING",
 )
 
 
-class Undefined(Enum):
-    MISSING = auto()
-
-    def __bool__(self) -> Literal[False]:
-        return False
-
-
-MISSING: Literal[Undefined.MISSING] = Undefined.MISSING
-
-
 class _cached_property:
     def __init__(self, function):
         self.function = function
@@ -236,58 +228,6 @@ def decorator(overridden: T) -> T:
     return decorator
 
 
-def oauth_url(
-    client_id: int | str,
-    *,
-    permissions: Permissions | Undefined = MISSING,
-    guild: Snowflake | Undefined = MISSING,
-    redirect_uri: str | Undefined = MISSING,
-    scopes: Iterable[str] | Undefined = MISSING,
-    disable_guild_select: bool = False,
-) -> str:
-    """A helper function that returns the OAuth2 URL for inviting the bot
-    into guilds.
-
-    Parameters
-    ----------
-    client_id: Union[:class:`int`, :class:`str`]
-        The client ID for your bot.
-    permissions: :class:`~discord.Permissions`
-        The permissions you're requesting. If not given then you won't be requesting any
-        permissions.
-    guild: :class:`~discord.abc.Snowflake`
-        The guild to pre-select in the authorization screen, if available.
-    redirect_uri: :class:`str`
-        An optional valid redirect URI.
-    scopes: Iterable[:class:`str`]
-        An optional valid list of scopes. Defaults to ``('bot',)``.
-
-        .. versionadded:: 1.7
-    disable_guild_select: :class:`bool`
-        Whether to disallow the user from changing the guild dropdown.
-
-        .. versionadded:: 2.0
-
-    Returns
-    -------
-    :class:`str`
-        The OAuth2 URL for inviting the bot into guilds.
-    """
-    url = f"https://discord.com/oauth2/authorize?client_id={client_id}"
-    url += f"&scope={'+'.join(scopes or ('bot',))}"
-    if permissions is not MISSING:
-        url += f"&permissions={permissions.value}"
-    if guild is not MISSING:
-        url += f"&guild_id={guild.id}"
-    if redirect_uri is not MISSING:
-        from urllib.parse import urlencode
-
-        url += f"&response_type=code&{urlencode({'redirect_uri': redirect_uri})}"
-    if disable_guild_select:
-        url += "&disable_guild_select=true"
-    return url
-
-
 def find(predicate: Callable[[T], Any], seq: Iterable[T]) -> T | None:
     """A helper to return the first element found in the sequence
     that meets the predicate. For example: ::

discord/utils/private.py

@@ -6,9 +6,8 @@
 import unicodedata
 import warnings
 from base64 import b64encode
-from typing import TYPE_CHECKING, Any, overload, Callable
+from typing import TYPE_CHECKING, Any, overload, Callable, TypeVar, ParamSpec
 
-from . import P, T
 from ..errors import InvalidArgument
 
 if TYPE_CHECKING:
@@ -208,6 +207,10 @@ def warn_deprecated(
     warnings.simplefilter("default", DeprecationWarning)  # reset filter
 
 
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
 def deprecated(
     instead: str | None = None,
     since: str | None = None,

discord/utils/public.py

@@ -2,15 +2,27 @@
 
 import asyncio
 import datetime
+from enum import Enum, auto
 import itertools
 from collections.abc import Awaitable, Callable, Iterable
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Any, Literal, Iterable
 
-from . import DISCORD_EPOCH
 
 if TYPE_CHECKING:
+    from .abc import Snowflake
     from ..commands.context import AutocompleteContext
     from ..commands.options import OptionChoice
+    from ..permissions import Permissions
+
+
+class Undefined(Enum):
+    MISSING = auto()
+
+    def __bool__(self) -> Literal[False]:
+        return False
+
+
+MISSING: Literal[Undefined.MISSING] = Undefined.MISSING
 
 DISCORD_EPOCH = 1420070400000
 
@@ -195,3 +207,55 @@ def snowflake_time(id: int) -> datetime.datetime:
     """
     timestamp = ((id >> 22) + DISCORD_EPOCH) / 1000
     return datetime.datetime.fromtimestamp(timestamp, tz=datetime.timezone.utc)
+
+
+def oauth_url(
+    client_id: int | str,
+    *,
+    permissions: Permissions | Undefined = MISSING,
+    guild: Snowflake | Undefined = MISSING,
+    redirect_uri: str | Undefined = MISSING,
+    scopes: Iterable[str] | Undefined = MISSING,
+    disable_guild_select: bool = False,
+) -> str:
+    """A helper function that returns the OAuth2 URL for inviting the bot
+    into guilds.
+
+    Parameters
+    ----------
+    client_id: Union[:class:`int`, :class:`str`]
+        The client ID for your bot.
+    permissions: :class:`~discord.Permissions`
+        The permissions you're requesting. If not given then you won't be requesting any
+        permissions.
+    guild: :class:`~discord.abc.Snowflake`
+        The guild to pre-select in the authorization screen, if available.
+    redirect_uri: :class:`str`
+        An optional valid redirect URI.
+    scopes: Iterable[:class:`str`]
+        An optional valid list of scopes. Defaults to ``('bot',)``.
+
+        .. versionadded:: 1.7
+    disable_guild_select: :class:`bool`
+        Whether to disallow the user from changing the guild dropdown.
+
+        .. versionadded:: 2.0
+
+    Returns
+    -------
+    :class:`str`
+        The OAuth2 URL for inviting the bot into guilds.
+    """
+    url = f"https://discord.com/oauth2/authorize?client_id={client_id}"
+    url += f"&scope={'+'.join(scopes or ('bot',))}"
+    if permissions is not MISSING:
+        url += f"&permissions={permissions.value}"
+    if guild is not MISSING:
+        url += f"&guild_id={guild.id}"
+    if redirect_uri is not MISSING:
+        from urllib.parse import urlencode
+
+        url += f"&response_type=code&{urlencode({'redirect_uri': redirect_uri})}"
+    if disable_guild_select:
+        url += "&disable_guild_select=true"
+    return url