Skip to content

Commit 91b3d68

Browse files
LumabotsLumabots
committed
comment
1 parent 198556d commit 91b3d68

File tree

3 files changed

+148
-41
lines changed

3 files changed

+148
-41
lines changed

‎discord/client.py‎

Lines changed: 43 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
Generator,
4040
Sequence,
4141
TypeVar,
42+
overload,
4243
)
4344

4445
import aiohttp
@@ -68,7 +69,7 @@
6869
from .threads import Thread
6970
from .ui.view import View
7071
from .user import ClientUser, User
71-
from .utils import _FETCHABLE, MISSING
72+
from .utils import _FETCHABLE, MISSING, _D
7273
from .voice_client import VoiceClient
7374
from .webhook import Webhook
7475
from .widget import Widget
@@ -247,9 +248,9 @@ def __init__(
247248
self.loop: asyncio.AbstractEventLoop = (
248249
asyncio.get_event_loop() if loop is None else loop
249250
)
250-
self._listeners: dict[str, list[tuple[asyncio.Future, Callable[..., bool]]]] = (
251-
{}
252-
)
251+
self._listeners: dict[
252+
str, list[tuple[asyncio.Future, Callable[..., bool]]]
253+
] = {}
253254
self.shard_id: int | None = options.get("shard_id")
254255
self.shard_count: int | None = options.get("shard_count")
255256

@@ -1186,37 +1187,64 @@ async def get_or_fetch_user(self, id: int, /) -> User | None: # TODO: Remove in
11861187

11871188
return await self.get_or_fetch(object_type=User, object_id=id, default=None)
11881189

1190+
@overload
1191+
async def get_or_fetch(
1192+
self: Client,
1193+
object_type: type[_FETCHABLE],
1194+
object_id: None,
1195+
default: _D = ...,
1196+
) -> None | _D: ...
1197+
1198+
@overload
11891199
async def get_or_fetch(
11901200
self: Client,
11911201
object_type: type[_FETCHABLE],
1202+
object_id: int,
1203+
default: _D,
1204+
) -> _FETCHABLE | _D: ...
1205+
1206+
@overload
1207+
async def get_or_fetch(
1208+
self: "Client",
1209+
object_type: type[_FETCHABLE],
1210+
object_id: int,
1211+
) -> _FETCHABLE: ...
1212+
1213+
async def get_or_fetch(
1214+
self: "Client",
1215+
object_type: type[_FETCHABLE],
11921216
object_id: int | None,
1193-
default: Any = MISSING,
1194-
) -> _FETCHABLE | None:
1217+
default: _D = MISSING,
1218+
) -> _FETCHABLE | _D | None:
11951219
"""
11961220
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.
11971221
11981222
Parameters
11991223
----------
1200-
object_type: Union[:class:`VoiceChannel`, :class:`TextChannel`, :class:`ForumChannel`, :class:`StageChannel`, :class:`CategoryChannel`, :class:`Thread`, :class:`User`, :class:`Guild`, :class:`GuildEmoji`, :class:`AppEmoji`]
1224+
object_type: VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | User | Guild | GuildEmoji | AppEmoji
12011225
Type of object to fetch or get.
1202-
object_id: :class:`int`
1203-
ID of object to get.
1204-
default : Any, optional
1226+
object_id: int | None
1227+
ID of object to get. If None, returns default if provided, else None.
1228+
default: Any, optional
12051229
A default to return instead of raising if fetch fails.
12061230
12071231
Returns
12081232
-------
1209-
Optional[Union[:class:`VoiceChannel`, :class:`TextChannel`, :class:`ForumChannel`, :class:`StageChannel`, :class:`CategoryChannel`, :class:`Thread`, :class:`User`, :class:`Guild`, :class:`GuildEmoji`, :class:`AppEmoji`]]
1210-
The object of type that was specified or ``None`` if not found.
1233+
VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | User | Guild | GuildEmoji | AppEmoji | None
1234+
The object of the specified type, or default if provided and not found, or None if not found and no default is provided.
12111235
12121236
Raises
12131237
------
1238+
:exc:`TypeError`
1239+
Raised when required parameters are missing or invalid types are provided.
1240+
:exc:`InvalidArgument`
1241+
Raised when an unsupported or incompatible object type is used.
12141242
:exc:`NotFound`
1215-
Invalid ID for the object
1243+
Invalid ID for the object.
12161244
:exc:`HTTPException`
1217-
An error occurred fetching the object
1245+
An error occurred fetching the object.
12181246
:exc:`Forbidden`
1219-
You do not have permission to fetch the object
1247+
You do not have permission to fetch the object.
12201248
"""
12211249
return await utils.get_or_fetch(
12221250
obj=self, object_type=object_type, object_id=object_id, default=default

‎discord/guild.py‎

Lines changed: 45 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@
8585
from .sticker import GuildSticker
8686
from .threads import Thread, ThreadMember
8787
from .user import User
88-
from .utils import _FETCHABLE
88+
from .utils import _FETCHABLE, _D
8989
from .welcome_screen import WelcomeScreen, WelcomeScreenChannel
9090
from .widget import Widget
9191

@@ -864,43 +864,72 @@ def get_member(self, user_id: int, /) -> Member | None:
864864
"""
865865
return self._members.get(user_id)
866866

867+
@overload
868+
async def get_or_fetch(
869+
self: Guild,
870+
object_type: type[_FETCHABLE],
871+
object_id: None,
872+
default: _D = ...,
873+
) -> None | _D: ...
874+
@overload
875+
async def get_or_fetch(
876+
self: Guild,
877+
object_type: type[_FETCHABLE],
878+
object_id: int,
879+
default: _D,
880+
) -> _FETCHABLE | _D: ...
881+
@overload
882+
async def get_or_fetch(
883+
self: Guild,
884+
object_type: type[_FETCHABLE],
885+
object_id: int,
886+
) -> _FETCHABLE: ...
887+
867888
async def get_or_fetch(
868889
self: Guild,
869890
object_type: type[_FETCHABLE],
870891
object_id: int | None,
871-
default: Any = MISSING,
872-
) -> _FETCHABLE | None:
892+
default: _D = MISSING,
893+
) -> _FETCHABLE | _D | None:
873894
"""
874-
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.
895+
Shortcut method to get data from this guild either by returning the cached version,
896+
or if it does not exist, attempting to fetch it from the API.
875897
876898
Parameters
877899
----------
878-
object_type: Union[:class:`VoiceChannel`, :class:`TextChannel`, :class:`ForumChannel`, :class:`StageChannel`, :class:`CategoryChannel`, :class:`Thread`, :class:`Role`, :class:`Member`, :class:`GuildEmoji`]
900+
object_type: VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | Role | Member | GuildEmoji
879901
Type of object to fetch or get.
880902
881-
object_id: :class:`int`
882-
ID of object to get.
903+
object_id: :class:`int` | None
904+
ID of the object to get. If ``None``, returns ``default`` if provided, otherwise ``None``.
883905
884-
default : Any, optional
885-
A default to return instead of raising if fetch fails.
906+
default : Any | None
907+
The value to return instead of raising if fetching fails or if ``object_id`` is ``None``.
886908
887909
Returns
888910
-------
889-
890-
Optional[Union[:class:`VoiceChannel`, :class:`TextChannel`, :class:`ForumChannel`, :class:`StageChannel`, :class:`CategoryChannel`, :class:`Thread`, :class:`Role`, :class:`Member`, :class:`GuildEmoji`]]
891-
The object of type that was specified or ``None`` if not found.
911+
VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | Role | Member | GuildEmoji | None
912+
The object if found, or ``default`` if provided when not found.
913+
Returns ``None`` only if ``object_id`` is ``None`` and no ``default`` is given.
892914
893915
Raises
894916
------
917+
:exc:`TypeError`
918+
Raised when required parameters are missing or invalid types are provided.
919+
:exc:`InvalidArgument`
920+
Raised when an unsupported or incompatible object type is used.
895921
:exc:`NotFound`
896-
Invalid ID for the object
922+
Invalid ID for the object.
897923
:exc:`HTTPException`
898-
An error occurred fetching the object
924+
An error occurred fetching the object.
899925
:exc:`Forbidden`
900-
You do not have permission to fetch the object
926+
You do not have permission to fetch the object.
901927
"""
902928
return await utils.get_or_fetch(
903-
obj=self, object_type=object_type, object_id=object_id, default=default
929+
obj=self,
930+
object_type=object_type,
931+
object_id=object_id,
932+
default=default,
904933
)
905934

906935
@property

‎discord/utils.py‎

Lines changed: 60 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -587,28 +587,73 @@ def get(iterable: Iterable[T], **attrs: Any) -> T | None:
587587

588588
_FETCHABLE = TypeVar(
589589
"_FETCHABLE",
590-
bound="VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | Member | User | Guild | Role | GuildEmoji | AppEmoji",
590+
bound=VoiceChannel
591+
| TextChannel
592+
| ForumChannel
593+
| StageChannel
594+
| CategoryChannel
595+
| Thread
596+
| Member
597+
| User
598+
| Guild
599+
| Role
600+
| GuildEmoji
601+
| AppEmoji,
591602
)
603+
_D = TypeVar("_D")
592604

593605

594606
# TODO: In version 3.0, remove the 'attr' and 'id' arguments.
595607
# Also, eliminate the default 'MISSING' value for both 'object_type' and 'object_id'.
608+
@overload
609+
async def get_or_fetch(
610+
obj: Guild | Client,
611+
object_type: type[_FETCHABLE],
612+
object_id: None,
613+
default: _D = ...,
614+
attr: str = ...,
615+
id: int = ...,
616+
) -> None | _D: ...
617+
618+
619+
@overload
620+
async def get_or_fetch(
621+
obj: Guild | Client,
622+
object_type: type[_FETCHABLE],
623+
object_id: int,
624+
default: _D,
625+
attr: str = ...,
626+
id: int = ...,
627+
) -> _FETCHABLE | _D: ...
628+
629+
630+
@overload
631+
async def get_or_fetch(
632+
obj: Guild | Client,
633+
object_type: type[_FETCHABLE],
634+
object_id: int,
635+
*,
636+
attr: str = ...,
637+
id: int = ...,
638+
) -> _FETCHABLE: ...
639+
640+
596641
async def get_or_fetch(
597642
obj: Guild | Client,
598643
object_type: type[_FETCHABLE] = MISSING,
599644
object_id: int | None = MISSING,
600-
default: Any = MISSING,
645+
default: _D = MISSING,
601646
attr: str = MISSING,
602647
id: int = MISSING,
603-
) -> _FETCHABLE | None:
648+
) -> _FETCHABLE | _D | None:
604649
"""
605650
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.
606651
607652
Parameters
608653
----------
609654
obj : Guild | Client
610655
The object to operate on.
611-
object_type: Union[:class:`VoiceChannel`, :class:`TextChannel`, :class:`ForumChannel`, :class:`StageChannel`, :class:`CategoryChannel`, :class:`Thread`, :class:`User`, :class:`Guild`, :class:`Role`, :class:`Member`, :class:`GuildEmoji`, :class:`AppEmoji`]
656+
object_type: VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | User | Guild | Role | Member | GuildEmoji | AppEmoji
612657
Type of object to fetch or get.
613658
614659
object_id: :class:`int`
@@ -620,22 +665,27 @@ async def get_or_fetch(
620665
Returns
621666
-------
622667
623-
Optional[Union[:class:`VoiceChannel`, :class:`TextChannel`, :class:`ForumChannel`, :class:`StageChannel`, :class:`CategoryChannel`, :class:`Thread`, :class:`User`, :class:`Guild`, :class:`Role`, :class:`Member`, :class:`GuildEmoji`, :class:`AppEmoji`]]
624-
The object of type that was specified or ``None`` if not found.
668+
VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | User | Guild | Role | Member | GuildEmoji | AppEmoji | None
669+
The object if found, or `default` if provided when not found.
670+
Returns `None` only if `object_id` is None and no `default` is given.
625671
626672
Raises
627673
------
674+
:exc:`TypeError`
675+
Raised when required parameters are missing or invalid types are provided.
676+
:exc:`InvalidArgument`
677+
Raised when an unsupported or incompatible object type is used.
628678
:exc:`NotFound`
629-
Invalid ID for the object
679+
Invalid ID for the object.
630680
:exc:`HTTPException`
631-
An error occurred fetching the object
681+
An error occurred fetching the object.
632682
:exc:`Forbidden`
633-
You do not have permission to fetch the object
683+
You do not have permission to fetch the object.
634684
"""
635685
from discord import AppEmoji, Client, Guild, Member, Role, User, abc, emoji
636686

637687
if object_id is None:
638-
return None
688+
return default if default is not MISSING else None
639689

640690
string_to_type = {
641691
"channel": abc.GuildChannel,

0 commit comments

Comments
 (0)