feat: Implement better get_or_fetch

CHANGELOG.md

@@ -53,6 +53,8 @@ These changes are available on the `master` branch, but have not yet been releas
   ([#2714](https://github.com/Pycord-Development/pycord/pull/2714))
 - Added the ability to pass a `datetime.time` object to `format_dt`
   ([#2747](https://github.com/Pycord-Development/pycord/pull/2747))
+- Added `Guild.get_or_fetch()` shortcut method and better get_or_fetch
+  ([#2776](https://github.com/Pycord-Development/pycord/pull/2776))
 
 ### Fixed
 

discord/client.py

@@ -67,10 +67,18 @@
 
 if TYPE_CHECKING:
     from .abc import GuildChannel, PrivateChannel, Snowflake, SnowflakeTime
-    from .channel import DMChannel
+    from .channel import (
+        CategoryChannel,
+        DMChannel,
+        ForumChannel,
+        StageChannel,
+        TextChannel,
+        VoiceChannel,
+    )
     from .member import Member
     from .message import Message
     from .poll import Poll
+    from .threads import Thread, ThreadMember
     from .voice_client import VoiceProtocol
 
 __all__ = ("Client",)
@@ -1113,6 +1121,10 @@ def get_all_members(self) -> Generator[Member]:
         for guild in self.guilds:
             yield from guild.members
 
+    @utils.deprecated(
+        instead="Client.get_or_fetch(User, id)",
+        since="2.7",
+    )
     async def get_or_fetch_user(self, id: int, /) -> User | None:
         """|coro|
 
@@ -1129,7 +1141,38 @@ async def get_or_fetch_user(self, id: int, /) -> User | None:
             The user or ``None`` if not found.
         """
 
-        return await utils.get_or_fetch(obj=self, attr="user", id=id, default=None)
+        return await utils.get_or_fetch(obj=self, attr=User, id=id, default=None)
+
+    _FETCHABLE = TypeVar(
+        "_FETCHABLE",
+        bound="VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | User | Guild | GuildEmoji | AppEmoji",
+    )
+
+    async def get_or_fetch(
+        self: Client,
+        object_type: type[_FETCHABLE],
+        object_id: int,
+        default: Any = MISSING,
+    ) -> _FETCHABLE | None:
+        """Shortcut method to get data from guild object either by returning the cached version, or if it does not exist, attempt to fetch it from the api.
+
+        Parameters
+        ----------
+        object_type: Union[:class:`VoiceChannel`, :class:`TextChannel`, :class:`ForumChannel`, :class:`StageChannel`, :class:`CategoryChannel`, :class:`Thread`, :class:`User`, :class:`Guild`, :class:`GuildEmoji`, :class:`AppEmoji`]
+            Type of object to fetch or get.
+        object_id: :class:`int`
+            ID of object to get.
+        default : Any, optional
+            A default to return instead of raising if fetch fails.
+
+        Returns
+        -------
+        Optional[Union[:class:`VoiceChannel`, :class:`TextChannel`, :class:`ForumChannel`, :class:`StageChannel`, :class:`CategoryChannel`, :class:`Thread`, :class:`User`, :class:`Guild`, :class:`GuildEmoji`, :class:`AppEmoji`]]
+            The object of type that was specified or ``None`` if not found.
+        """
+        return await utils.get_or_fetch(
+            obj=self, object_type=object_type, object_id=object_id, default=default
+        )
 
     # listeners/waiters
 

discord/guild.py

@@ -36,6 +36,7 @@
     Optional,
     Sequence,
     Tuple,
+    TypeVar,
     Union,
     overload,
 )
@@ -863,6 +864,40 @@ def get_member(self, user_id: int, /) -> Member | None:
         """
         return self._members.get(user_id)
 
+    _FETCHABLE = TypeVar(
+        "_FETCHABLE",
+        bound="VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | Member | GuildEmoji",
+    )
+
+    async def get_or_fetch(
+        self: Guild,
+        object_type: type[_FETCHABLE],
+        object_id: int,
+        default: Any = MISSING,
+    ) -> _FETCHABLE | None:
+        """Shortcut method to get data from guild object either by returning the cached version, or if it does not exist, attempt to fetch it from the api.
+
+        Parameters
+        ----------
+        object_type: Union[:class:`VoiceChannel`, :class:`TextChannel`, :class:`ForumChannel`, :class:`StageChannel`, :class:`CategoryChannel`, :class:`Thread`, :class:`Member`, :class:`GuildEmoji`]
+            Type of object to fetch or get.
+
+        object_id: :class:`int`
+            ID of object to get.
+
+        default : Any, optional
+            A default to return instead of raising if fetch fails.
+
+        Returns
+        -------
+
+        Optional[Union[:class:`VoiceChannel`, :class:`TextChannel`, :class:`ForumChannel`, :class:`StageChannel`, :class:`CategoryChannel`, :class:`Thread`, :class:`Member`, :class:`GuildEmoji`]]
+            The object of type that was specified or ``None`` if not found.
+        """
+        return await utils.get_or_fetch(
+            obj=self, object_type=object_type, object_id=object_id, default=default
+        )
+
     @property
     def premium_subscribers(self) -> list[Member]:
         """A list of members who have "boosted" this guild."""
@@ -2664,6 +2699,26 @@ async def delete_sticker(
         """
         await self._state.http.delete_guild_sticker(self.id, sticker.id, reason)
 
+    def get_emoji(self, emoji_id: int, /) -> GuildEmoji | None:
+        """Returns an emoji with the given ID.
+
+        .. versionadded:: 2.7
+
+        Parameters
+        ----------
+        emoji_id: int
+            The ID to search for.
+
+        Returns
+        -------
+        Optional[:class:`Emoji`]
+            The returned Emoji or ``None`` if not found.
+        """
+        emoji = self._state.get_emoji(emoji_id)
+        if emoji and emoji.guild == self:
+            return emoji
+        return None
+
     async def fetch_emojis(self) -> list[GuildEmoji]:
         r"""|coro|
 

discord/utils.py

@@ -63,6 +63,21 @@
     overload,
 )
 
+if TYPE_CHECKING:
+    from discord import (
+        Client,
+        VoiceChannel,
+        TextChannel,
+        ForumChannel,
+        StageChannel,
+        CategoryChannel,
+        Thread,
+        Member,
+        User,
+        Guild,
+        GuildEmoji,
+    )
+
 from .errors import HTTPException, InvalidArgument
 
 try:
@@ -573,64 +588,129 @@ def get(iterable: Iterable[T], **attrs: Any) -> T | None:
     return None
 
 
-async def get_or_fetch(obj, attr: str, id: int, *, default: Any = MISSING) -> Any:
-    """|coro|
+_FETCHABLE = TypeVar(
+    "_FETCHABLE",
+    bound="VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | Member | User | Guild | GuildEmoji | AppEmoji",
+)
+
 
-    Attempts to get an attribute from the object in cache. If it fails, it will attempt to fetch it.
-    If the fetch also fails, an error will be raised.
+# TODO REMOVE THE FOR object_type and object_id + remove both attr and id after depreciation
+async def get_or_fetch(
+    obj: Guild | Client,
+    object_type: type[_FETCHABLE] = MISSING,
+    object_id: int = MISSING,
+    default: Any = MISSING,
+    attr: str = MISSING,
+    id: int = MISSING,
+) -> _FETCHABLE | None:
+    """
+    Shortcut method to get data from guild object either by returning the cached version, or if it does not exist, attempt to fetch it from the api.
 
     Parameters
     ----------
-    obj: Any
-        The object to use the get or fetch methods in
-    attr: :class:`str`
-        The attribute to get or fetch. Note the object must have both a ``get_`` and ``fetch_`` method for this attribute.
-    id: :class:`int`
-        The ID of the object
-    default: Any
-        The default value to return if the object is not found, instead of raising an error.
+    obj : Guild | Client
+        The object to operate on.
+    object_type: Union[:class:`VoiceChannel`, :class:`TextChannel`, :class:`ForumChannel`, :class:`StageChannel`, :class:`CategoryChannel`, :class:`Thread`, :class:`User`, :class:`Guild`, :class:`Member`, :class:`GuildEmoji`, :class:`AppEmoji`]
+        Type of object to fetch or get.
+
+    object_id: :class:`int`
+        ID of object to get.
+
+    default : Any, optional
+        A default to return instead of raising if fetch fails.
 
     Returns
     -------
-    Any
-        The object found or the default value.
-
-    Raises
-    ------
-    :exc:`AttributeError`
-        The object is missing a ``get_`` or ``fetch_`` method
-    :exc:`NotFound`
-        Invalid ID for the object
-    :exc:`HTTPException`
-        An error occurred fetching the object
-    :exc:`Forbidden`
-        You do not have permission to fetch the object
-
-    Examples
-    --------
 
-    Getting a guild from a guild ID: ::
+    Optional[Union[:class:`VoiceChannel`, :class:`TextChannel`, :class:`ForumChannel`, :class:`StageChannel`, :class:`CategoryChannel`, :class:`Thread`, :class:`User`, :class:`Guild`, :class:`Member`, :class:`GuildEmoji`, :class:`AppEmoji`]]
+        The object of type that was specified or ``None`` if not found.
+    """
+    from discord import (
+        AppEmoji,
+        CategoryChannel,
+        ForumChannel,
+        Guild,
+        GuildEmoji,
+        Member,
+        StageChannel,
+        TextChannel,
+        Thread,
+        User,
+        VoiceChannel,
+    )
 
-        guild = await utils.get_or_fetch(client, 'guild', guild_id)
+    # TODO REMOVE THIS PART AfTER DEPREcIATION
+    string_to_type = {
+        "channel": TextChannel,
+        "member": Member,
+        "user": User,
+        "guild": Guild,
+        "emoji": GuildEmoji,
+        "appemoji": AppEmoji,
+    }
+
+    if attr is not MISSING or id is not MISSING or isinstance(object_type, str):
+        warn_deprecated(
+            name="get_or_fetch(obj, attr='type', id=...)",
+            instead="get_or_fetch(obj, object_type=Type, object_id=...)",
+            since="2.7",
+        )
+        attr = object_type if object_type is not MISSING else attr
+        mapped_type = string_to_type.get(attr.lower())
+        if mapped_type is None:
+            raise InvalidArgument(
+                f"Unknown type string '{attr}' passed as `attr`. Use a valid object class instead."
+            )
+        object_type = mapped_type
+        object_id = id
+
+    if object_type is MISSING or object_id is MISSING:
+        raise TypeError("required parameters: `object_type` and `object_id`.")
+    # Util here
+
+    if issubclass(object_type, (Member, User, Guild)):
+        attr = object_type.__name__.lower()
+    elif issubclass(object_type, (GuildEmoji, AppEmoji)):
+        attr = "emoji"
+    elif issubclass(
+        object_type,
+        (
+            VoiceChannel,
+            TextChannel,
+            ForumChannel,
+            StageChannel,
+            CategoryChannel,
+            Thread,
+        ),
+    ):
+        attr = "channel"
+    else:
+        raise InvalidArgument(
+            f"Class {object_type.__name__} cannot be used with discord.{type(obj).__name__}.get_or_fetch()"
+        )
+    if isinstance(obj, Guild) and object_type is User:
+        raise InvalidArgument(
+            "Guild cannot get_or_fetch discord.User. Use Client instead."
+        )
+    elif isinstance(obj, Client) and object_type is Member:
+        raise InvalidArgument("Client cannot get_or_fetch Member. Use Guild instead.")
 
-    Getting a channel from the guild. If the channel is not found, return None: ::
+    getter = getattr(obj, f"get_{attr}", None)
+    if getter:
+        result = getter(object_id)
+        if result is not None:
+            return result
 
-        channel = await utils.get_or_fetch(guild, 'channel', channel_id, default=None)
-    """
-    getter = getattr(obj, f"get_{attr}")(id)
-    if getter is None:
+    fetcher = getattr(obj, f"fetch_{attr}", None) or getattr(
+        obj, f"_fetch_{attr}", None
+    )
+    if fetcher:
         try:
-            getter = await getattr(obj, f"fetch_{attr}")(id)
-        except AttributeError:
-            getter = await getattr(obj, f"_fetch_{attr}")(id)
-            if getter is None:
-                raise ValueError(f"Could not find {attr} with id {id} on {obj}")
+            return await fetcher(object_id)
         except (HTTPException, ValueError):
             if default is not MISSING:
                 return default
-            else:
-                raise
-    return getter
+            raise
 
 
 def _unique(iterable: Iterable[T]) -> list[T]: