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/guild.py

@@ -36,6 +36,8 @@
     Optional,
     Sequence,
     Tuple,
+    Type,
+    TypeVar,
     Union,
     overload,
 )
@@ -863,6 +865,48 @@ def get_member(self, user_id: int, /) -> Member | None:
         """
         return self._members.get(user_id)
 
+    _FETCHABLE = TypeVar(
+        "_FETCHABLE",
+        bound=Union[
+            VoiceChannel,
+            TextChannel,
+            ForumChannel,
+            StageChannel,
+            CategoryChannel,
+            Thread,
+            Member,
+        ],
+    )
+
+    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`]
+            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`]]
+            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."""

discord/utils.py

@@ -56,13 +56,29 @@
     Iterator,
     Literal,
     Mapping,
+    Optional,
     Protocol,
     Sequence,
+    Type,
     TypeVar,
     Union,
     overload,
 )
 
+if TYPE_CHECKING:
+    from discord import (
+        Client,
+        VoiceChannel,
+        TextChannel,
+        ForumChannel,
+        StageChannel,
+        CategoryChannel,
+        Thread,
+        Member,
+        User,
+        Guild,
+    )
+
 from .errors import HTTPException, InvalidArgument
 
 try:
@@ -573,64 +589,82 @@ 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=Union[
+        VoiceChannel,
+        TextChannel,
+        ForumChannel,
+        StageChannel,
+        CategoryChannel,
+        Thread,
+        Member,
+        User,
+        Guild,
+    ],
+)
 
-    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.
+
+async def get_or_fetch(
+    obj: Guild | 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
     ----------
-    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:`Member`]
+        Type of object to fetch or get.
 
-    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
+    object_id: :class:`int`
+        ID of object to get.
 
-    Examples
-    --------
+    default : Any, optional
+        A default to return instead of raising if fetch fails.
 
-    Getting a guild from a guild ID: ::
+    Returns
+    -------
 
-        guild = await utils.get_or_fetch(client, 'guild', guild_id)
+    Optional[Union[:class:`VoiceChannel`, :class:`TextChannel`, :class:`ForumChannel`, :class:`StageChannel`, :class:`CategoryChannel`, :class:`Thread`, :class:`Member`]]
+        The object of type that was specified or ``None`` if not found.
+    """
+    if object_type.__name__ in {"Member", "User", "Guild"}:
+        attr = object_type.__name__.lower()
+    elif object_type.__name__ in {
+        "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()"
+        )
 
-    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]: