feat: Implement better get_or_fetch

CHANGELOG.md

@@ -63,6 +63,8 @@ These changes are available on the `master` branch, but have not yet been releas
   ([#2775](https://github.com/Pycord-Development/pycord/pull/2775))
 - Added `discord.Interaction.created_at`.
   ([#2801](https://github.com/Pycord-Development/pycord/pull/2801))
+- Added `Guild.get_or_fetch()` and `Client.get_or_fetch()` shortcut methods.
+  ([#2776](https://github.com/Pycord-Development/pycord/pull/2776))
 
 ### Fixed
 
@@ -161,6 +163,9 @@ These changes are available on the `master` branch, but have not yet been releas
   ([#2501](https://github.com/Pycord-Development/pycord/pull/2501))
 - Deprecated `Interaction.cached_channel` in favor of `Interaction.channel`.
   ([#2658](https://github.com/Pycord-Development/pycord/pull/2658))
+- Deprecated `utils.get_or_fetch(attr, id)` in favor of
+  `utils.get_or_fetch(object_type, object_id)`.
+  ([#2776](https://github.com/Pycord-Development/pycord/pull/2776))
 
 ### Removed
 

discord/client.py

@@ -31,7 +31,17 @@
 import sys
 import traceback
 from types import TracebackType
-from typing import TYPE_CHECKING, Any, Callable, Coroutine, Generator, Sequence, TypeVar
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Coroutine,
+    Generator,
+    Literal,
+    Sequence,
+    TypeVar,
+    overload,
+)
 
 import aiohttp
 
@@ -60,18 +70,26 @@
 from .threads import Thread
 from .ui.view import View
 from .user import ClientUser, User
-from .utils import MISSING
+from .utils import _D, _FETCHABLE, MISSING
 from .voice_client import VoiceClient
 from .webhook import Webhook
 from .widget import Widget
 
 if TYPE_CHECKING:
     from .abc import GuildChannel, PrivateChannel, Snowflake, SnowflakeTime
-    from .channel import DMChannel
+    from .channel import (
+        CategoryChannel,
+        DMChannel,
+        ForumChannel,
+        StageChannel,
+        TextChannel,
+        VoiceChannel,
+    )
     from .interaction import Interaction
     from .member import Member
     from .message import Message
     from .poll import Poll
+    from .threads import Thread, ThreadMember
     from .ui.item import Item
     from .voice_client import VoiceProtocol
 
@@ -1147,7 +1165,12 @@ def get_all_members(self) -> Generator[Member]:
         for guild in self.guilds:
             yield from guild.members
 
-    async def get_or_fetch_user(self, id: int, /) -> User | None:
+    @utils.deprecated(
+        instead="Client.get_or_fetch(User, id)",
+        since="2.7",
+        removed="3.0",
+    )
+    async def get_or_fetch_user(self, id: int, /) -> User | None:  # TODO: Remove in 3.0
         """|coro|
 
         Looks up a user in the user cache or fetches if not found.
@@ -1163,7 +1186,70 @@ 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 self.get_or_fetch(object_type=User, object_id=id, default=None)
+
+    @overload
+    async def get_or_fetch(
+        self: Client,
+        object_type: type[_FETCHABLE],
+        object_id: Literal[None],
+        default: _D = ...,
+    ) -> None | _D: ...
+
+    @overload
+    async def get_or_fetch(
+        self: Client,
+        object_type: type[_FETCHABLE],
+        object_id: int,
+        default: _D,
+    ) -> _FETCHABLE | _D: ...
+
+    @overload
+    async def get_or_fetch(
+        self: Client,
+        object_type: type[_FETCHABLE],
+        object_id: int,
+    ) -> _FETCHABLE: ...
+
+    async def get_or_fetch(
+        self: Client,
+        object_type: type[_FETCHABLE],
+        object_id: int | None,
+        default: _D = MISSING,
+    ) -> _FETCHABLE | _D | None:
+        """
+        Shortcut method to get data from an object either by returning the cached version, or if it does not exist, attempting to fetch it from the API.
+
+        Parameters
+        ----------
+        object_type: VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | User | Guild | GuildEmoji | AppEmoji
+            Type of object to fetch or get.
+        object_id: int | None
+            ID of object to get. If None, returns default if provided, else None.
+        default: Any | None
+            A default to return instead of raising if fetch fails.
+
+        Returns
+        -------
+        VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | User | Guild | GuildEmoji | AppEmoji | None
+            The object of the specified type, or default if provided and not found, or None if not found and no default is provided.
+
+        Raises
+        ------
+        :exc:`TypeError`
+            Raised when required parameters are missing or invalid types are provided.
+        :exc:`InvalidArgument`
+            Raised when an unsupported or incompatible object type is used.
+        :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.
+        """
+        return await utils.get_or_fetch(
+            obj=self, object_type=object_type, object_id=object_id, default=default
+        )
 
     # listeners/waiters
 

discord/guild.py

@@ -32,6 +32,7 @@
     Any,
     ClassVar,
     List,
+    Literal,
     NamedTuple,
     Optional,
     Sequence,
@@ -85,6 +86,7 @@
 from .sticker import GuildSticker
 from .threads import Thread, ThreadMember
 from .user import User
+from .utils import _D, _FETCHABLE
 from .welcome_screen import WelcomeScreen, WelcomeScreenChannel
 from .widget import Widget
 
@@ -863,6 +865,74 @@ def get_member(self, user_id: int, /) -> Member | None:
         """
         return self._members.get(user_id)
 
+    @overload
+    async def get_or_fetch(
+        self: Guild,
+        object_type: type[_FETCHABLE],
+        object_id: Literal[None],
+        default: _D = ...,
+    ) -> None | _D: ...
+    @overload
+    async def get_or_fetch(
+        self: Guild,
+        object_type: type[_FETCHABLE],
+        object_id: int,
+        default: _D,
+    ) -> _FETCHABLE | _D: ...
+    @overload
+    async def get_or_fetch(
+        self: Guild,
+        object_type: type[_FETCHABLE],
+        object_id: int,
+    ) -> _FETCHABLE: ...
+
+    async def get_or_fetch(
+        self: Guild,
+        object_type: type[_FETCHABLE],
+        object_id: int | None,
+        default: _D = MISSING,
+    ) -> _FETCHABLE | _D | None:
+        """
+        Shortcut method to get data from this guild either by returning the cached version,
+        or if it does not exist, attempting to fetch it from the API.
+
+        Parameters
+        ----------
+        object_type: VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | Role | Member | GuildEmoji
+            Type of object to fetch or get.
+
+        object_id: :class:`int` | None
+            ID of the object to get. If ``None``, returns ``default`` if provided, otherwise ``None``.
+
+        default : Any | None
+            The value to return instead of raising if fetching fails or if ``object_id`` is ``None``.
+
+        Returns
+        -------
+        VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | Role | Member | GuildEmoji | None
+            The object if found, or ``default`` if provided when not found.
+            Returns ``None`` only if ``object_id`` is ``None`` and no ``default`` is given.
+
+        Raises
+        ------
+        :exc:`TypeError`
+            Raised when required parameters are missing or invalid types are provided.
+        :exc:`InvalidArgument`
+            Raised when an unsupported or incompatible object type is used.
+        :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.
+        """
+        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."""
@@ -2699,6 +2769,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|