diff --git a/hikari/api/cache.py b/hikari/api/cache.py index 7c622a931f..f5e8741a9d 100644 --- a/hikari/api/cache.py +++ b/hikari/api/cache.py @@ -71,11 +71,11 @@ class Cache(abc.ABC): This will be used by the gateway to cache specific types of objects that the application should attempt to remember for later, depending on how this is implemented. The requirement for this stems from the - assumption by Discord that bot applications will maintain some form of + assumption by Discord that gateway bot applications will maintain some form of "memory" of the events that occur. The implementation may choose to use a simple in-memory collection of - objects, or may decide to use a distributed system such as a Redis cache + objects, or may decide to use a distributed system such as a Redis or Valkey cache for cross-process bots. """ @@ -88,7 +88,7 @@ def settings(self) -> config.CacheSettings: @abc.abstractmethod def get_dm_channel_id(self, user: snowflakes.SnowflakeishOr[users.PartialUser], /) -> snowflakes.Snowflake | None: - """Get the DM channel ID for a user. + """Get the DM channel ID for a user from the cache. Parameters ---------- @@ -98,18 +98,17 @@ def get_dm_channel_id(self, user: snowflakes.SnowflakeishOr[users.PartialUser], Returns ------- typing.Optional[hikari.snowflakes.Snowflake] - ID of the DM channel which was found cached for the supplied user or - [`None`][]. + The DM channel ID for the specified user if found, otherwise [`None`][]. """ @abc.abstractmethod def get_dm_channel_ids_view(self) -> CacheView[snowflakes.Snowflake, snowflakes.Snowflake]: - """Get a view of the cached DM channel IDs. + """Get a view of the DM channel IDs in the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.snowflakes.Snowflake] - Cache view of user IDs to DM channel IDs. + A view of user IDs to DM channel IDs. """ @abc.abstractmethod @@ -119,84 +118,81 @@ def get_emoji(self, emoji: snowflakes.SnowflakeishOr[emojis.CustomEmoji], /) -> Parameters ---------- emoji - Object or ID of the emoji to get from the cache. + Object or ID of the emoji to get. Returns ------- typing.Optional[hikari.emojis.KnownCustomEmoji] - The object of the emoji that was found in the cache or [`None`][]. + The known custom emoji object if found, otherwise [`None`][]. """ @abc.abstractmethod def get_emojis_view(self) -> CacheView[snowflakes.Snowflake, emojis.KnownCustomEmoji]: - """Get a view of the known custom emoji objects in the cache. + """Get a view of the known custom emojis in the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.emojis.KnownCustomEmoji] - A view of emoji IDs to objects of the known custom emojis found in - the cache. + A view of known custom emoji IDs to objects. """ @abc.abstractmethod def get_emojis_view_for_guild( self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], / ) -> CacheView[snowflakes.Snowflake, emojis.KnownCustomEmoji]: - """Get a view of the known custom emojis cached for a specific guild. + """Get a view of the known custom emojis in the cache for a specific guild. Parameters ---------- guild - Object or ID of the guild to get the cached emoji objects for. + Object or ID of the guild to get the emojis for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.emojis.KnownCustomEmoji] - A view of emoji IDs to objects of emojis found in the cache for the - specified guild. + A view of known custom emoji IDs to objects for the specified guild. """ @abc.abstractmethod def get_sticker(self, sticker: snowflakes.SnowflakeishOr[stickers.GuildSticker], /) -> stickers.GuildSticker | None: - """Get a sticker from the cache. + """Get a guild sticker from the cache. Parameters ---------- sticker - Object or ID of the sticker to get from the cache. + Object or ID of the sticker to get. Returns ------- typing.Optional[hikari.stickers.GuildSticker] - The object of the sticker that was found in the cache or [`None`][]. + The guild sticker object if found, otherwise [`None`][]. """ @abc.abstractmethod def get_stickers_view(self) -> CacheView[snowflakes.Snowflake, stickers.GuildSticker]: - """Get a view of the sticker objects in the cache. + """Get a view of the guild stickers in the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.stickers.GuildSticker] - A view of sticker IDs to objects of the stickers found in the cache. + A view of guild sticker IDs to objects. """ @abc.abstractmethod def get_stickers_view_for_guild( self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], / ) -> CacheView[snowflakes.Snowflake, stickers.GuildSticker]: - """Get a view of the known custom emojis cached for a specific guild. + """Get a view of the guild stickers in the cache for a specific guild. Parameters ---------- guild - Object or ID of the guild to get the cached sticker objects for. + Object or ID of the guild to get the stickers for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.stickers.GuildSticker] - A view of sticker IDs to objects of stickers found in the cache for the - specified guild. + A view of guild sticker IDs to objects for the specified guild. """ @abc.abstractmethod @@ -204,7 +200,7 @@ def get_guild(self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], /) -> """Get a guild from the cache. !!! warning - This will return a guild regardless of whether it is available or + This may return a guild regardless of whether it is available or not. To only query available guilds, use [`hikari.api.cache.Cache.get_available_guild`][] instead. Likewise, to only query unavailable guilds, use [`hikari.api.cache.Cache.get_unavailable_guild`][]. @@ -212,39 +208,39 @@ def get_guild(self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], /) -> Parameters ---------- guild - Object or ID of the guild to get from the cache. + Object or ID of the guild to get. Returns ------- typing.Optional[hikari.guilds.GatewayGuild] - The object of the guild if found, else [`None`][]. + The guild object if found, otherwise [`None`][]. """ @abc.abstractmethod def get_available_guild( self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], / ) -> guilds.GatewayGuild | None: - """Get the object of an available guild from the cache. + """Get an available guild from the cache. Parameters ---------- guild - Object or ID of the guild to get from the cache. + Object or ID of the guild to get. Returns ------- typing.Optional[hikari.guilds.GatewayGuild] - The object of the guild if found, else [`None`][]. + The guild object if found, otherwise [`None`][]. """ @abc.abstractmethod def get_unavailable_guild( self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], / ) -> guilds.GatewayGuild | None: - """Get the object of an unavailable guild from the cache. + """Get an unavailable guild from the cache. !!! note - Unlike [`hikari.api.cache.Cache.get_available_guild`][], the objects returned by this + Unlike [`hikari.api.cache.Cache.get_available_guild`][], any object returned by this method will likely be out of date and inaccurate as they are considered unavailable, meaning that we are not receiving gateway events for this guild. @@ -252,40 +248,40 @@ def get_unavailable_guild( Parameters ---------- guild - Object or ID of the guild to get from the cache. + Object or ID of the guild to get. Returns ------- typing.Optional[hikari.guilds.GatewayGuild] - The object of the guild if found, else [`None`][]. + The guild object if found, otherwise [`None`][]. """ @abc.abstractmethod def get_guilds_view(self) -> CacheView[snowflakes.Snowflake, guilds.GatewayGuild]: - """Get a view of all the guild objects in the cache regardless if availability. + """Get a view of the guilds in the cache (regardless of availability). Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.guilds.GatewayGuild] - A view of guild IDs to the guild objects found in the cache. + A view of guild IDs to objects. """ @abc.abstractmethod def get_available_guilds_view(self) -> CacheView[snowflakes.Snowflake, guilds.GatewayGuild]: - """Get a view of the available guild objects in the cache. + """Get a view of the available guilds in the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.guilds.GatewayGuild] - A view of guild IDs to the guild objects found in the cache. + A view of guild IDs to objects. """ @abc.abstractmethod def get_unavailable_guilds_view(self) -> CacheView[snowflakes.Snowflake, guilds.GatewayGuild]: - """Get a view of the unavailable guild objects in the cache. + """Get a view of the unavailable guilds in the cache. !!! note - Unlike [`hikari.api.cache.Cache.get_available_guilds_view`][], the objects returned by + Unlike [`hikari.api.cache.Cache.get_available_guilds_view`][], any objects returned by this method will likely be out of date and inaccurate as they are considered unavailable, meaning that we are not receiving gateway events for this guild. @@ -293,7 +289,7 @@ def get_unavailable_guilds_view(self) -> CacheView[snowflakes.Snowflake, guilds. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.guilds.GatewayGuild] - A view of guild IDs to the guild objects found in the cache. + A view of guild IDs to objects. """ @abc.abstractmethod @@ -305,13 +301,12 @@ def get_guild_channel( Parameters ---------- channel - Object or ID of the guild channel to get from the cache. + Object or ID of the guild channel to get. Returns ------- typing.Optional[hikari.channels.PermissibleGuildChannel] - The object of the guild channel that was found in the cache or - [`None`][]. + The guild channel object if found, otherwise [`None`][]. """ @abc.abstractmethod @@ -321,8 +316,7 @@ def get_guild_channels_view(self) -> CacheView[snowflakes.Snowflake, channels.Pe Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.channels.PermissibleGuildChannel] - A view of channel IDs to objects of the guild channels found in the - cache. + A view of guild channel IDs to objects. """ @abc.abstractmethod @@ -334,13 +328,12 @@ def get_guild_channels_view_for_guild( Parameters ---------- guild - Object or ID of the guild to get the cached channels for. + Object or ID of the guild to get the channels for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.channels.PermissibleGuildChannel] - A view of channel IDs to objects of the guild channels found in the - cache for the specified guild. + A view of guild channel IDs to objects for the specified guild. """ @abc.abstractmethod @@ -352,13 +345,12 @@ def get_thread( Parameters ---------- thread - Object or ID of the thread to get from the cache. + Object or ID of the thread to get. Returns ------- typing.Optional[hikari.channels.GuildThreadChannel] - The object of the thread that was found in the cache - or [`None`][]. + The thread channel object if found, otherwise [`None`][]. """ @abc.abstractmethod @@ -368,8 +360,7 @@ def get_threads_view(self) -> CacheView[snowflakes.Snowflake, channels.GuildThre Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.channels.GuildThreadChannel] - A view of channel IDs to objects of the thread channels found in the - cache. + A view of thread channel IDs to objects. """ @abc.abstractmethod @@ -379,20 +370,19 @@ def get_threads_view_for_channel( channel: snowflakes.SnowflakeishOr[channels.PartialChannel], /, ) -> CacheView[snowflakes.Snowflake, channels.GuildThreadChannel]: - """Get a view of the thread channels in the cache for a specific guild. + """Get a view of the thread channels in the cache for a specific guild channel. Parameters ---------- guild - Object or ID of the guild to get the cached thread channels for. + Object or ID of the guild to get the thread channels for. channel - Object or ID of the channel to get the cached thread channels for. + Object or ID of the guild channel to get the thread channels for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.channels.GuildThreadChannel] - A view of channel IDs to objects of the thread channels found in the - cache for the specified channel. + A view of thread channel IDs to objects for the specified guild channel. """ @abc.abstractmethod @@ -404,57 +394,54 @@ def get_threads_view_for_guild( Parameters ---------- guild - Object or ID of the guild to get the cached thread channels for. + Object or ID of the guild to get the thread channels for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.channels.GuildThreadChannel] - A view of channel IDs to objects of the thread channels found in the - cache for the specified guild. + A view of thread channel IDs to objects for the specified guild. """ @abc.abstractmethod def get_invite(self, code: invites.InviteCode | str, /) -> invites.InviteWithMetadata | None: - """Get an invite object from the cache. + """Get an invite from the cache. Parameters ---------- code - The object or string code of the invite to get from the cache. + Object or string code of the invite to get. Returns ------- typing.Optional[hikari.invites.InviteWithMetadata] - The object of the invite that was found in the cache or [`None`][]. + The invite object if found, otherwise [`None`][]. """ @abc.abstractmethod def get_invites_view(self) -> CacheView[str, invites.InviteWithMetadata]: - """Get a view of the invite objects in the cache. + """Get a view of the invites in the cache. Returns ------- CacheView[str, hikari.invites.InviteWithMetadata] - A view of string codes to objects of the invites that were found in - the cache. + A view of invite string codes to objects. """ @abc.abstractmethod def get_invites_view_for_guild( self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], / ) -> CacheView[str, invites.InviteWithMetadata]: - """Get a view of the invite objects in the cache for a specific guild. + """Get a view of the invites in the cache for a specific guild. Parameters ---------- guild - Object or ID of the guild to get invite objects for. + Object or ID of the guild to get the invites for. Returns ------- CacheView[str, hikari.invites.InviteWithMetadata] - A view of string code to objects of the invites that were found in - the cache for the specified guild. + A view of invite string codes to objects for the specified guild. """ @abc.abstractmethod @@ -464,30 +451,29 @@ def get_invites_view_for_channel( channel: snowflakes.SnowflakeishOr[channels.PartialChannel], /, ) -> CacheView[str, invites.InviteWithMetadata]: - """Get a view of the invite objects in the cache for a specified channel. + """Get a view of the invites in the cache for a specific channel. Parameters ---------- guild - Object or ID of the guild to get invite objects for. + Object or ID of the guild to get the invites for. channel - Object or ID of the channel to get invite objects for. + Object or ID of the channel to get the invites for. Returns ------- CacheView[str, invites.InviteWithMetadata] - A view of string codes to objects of the invites there were found in - the cache for the specified channel. + A view of invite string codes to objects for the specified channel. """ @abc.abstractmethod def get_me(self) -> users.OwnUser | None: - """Get the own user object from the cache. + """Get the own user from the cache. Returns ------- typing.Optional[hikari.users.OwnUser] - The own user object that was found in the cache, else [`None`][]. + The own user object if found, otherwise [`None`][]. """ @abc.abstractmethod @@ -497,72 +483,71 @@ def get_member( user: snowflakes.SnowflakeishOr[users.PartialUser], /, ) -> guilds.Member | None: - """Get a member object from the cache. + """Get a member from the cache. Parameters ---------- guild - Object or ID of the guild to get a cached member for. + Object or ID of the guild to get the member for. user - Object or ID of the user to get a cached member for. + Object or ID of the user to get the member for. Returns ------- typing.Optional[hikari.guilds.Member] - The object of the member found in the cache, else [`None`][]. + The member object if found, otherwise [`None`][]. """ @abc.abstractmethod def get_members_view(self) -> CacheView[snowflakes.Snowflake, CacheView[snowflakes.Snowflake, guilds.Member]]: - """Get a view of all the members objects in the cache. + """Get a view of the members in the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, CacheView[hikari.snowflakes.Snowflake, hikari.guilds.Member]] - A view of guild IDs to views of user IDs to objects of the members - that were found from the cache. + A view of guild IDs to views of user IDs to member objects. """ @abc.abstractmethod def get_members_view_for_guild( self, guild_id: snowflakes.Snowflakeish, / ) -> CacheView[snowflakes.Snowflake, guilds.Member]: - """Get a view of the members cached for a specific guild. + """Get a view of the members in the cache for a specific guild. Parameters ---------- guild_id - The ID of the guild to get the cached member view for. + The ID of the guild to get the members for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.guilds.Member] - The view of user IDs to the members cached for the specified guild. + A view of user IDs to member objects for the specified guild. """ @abc.abstractmethod def get_message(self, message: snowflakes.SnowflakeishOr[messages.PartialMessage], /) -> messages.Message | None: - """Get a message object from the cache. + """Get a message from the cache. Parameters ---------- message - Object or ID of the message to get from the cache. + Object or ID of the message to get. Returns ------- typing.Optional[hikari.messages.Message] - The object of the message found in the cache or [`None`][]. + The message object if found, otherwise [`None`][]. """ @abc.abstractmethod def get_messages_view(self) -> CacheView[snowflakes.Snowflake, messages.Message]: - """Get a view of all the message objects in the cache. + """Get a view of the messages in the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.messages.Message] - A view of message objects found in the cache. + A view of message IDs to objects. """ @abc.abstractmethod @@ -572,76 +557,73 @@ def get_presence( user: snowflakes.SnowflakeishOr[users.PartialUser], /, ) -> presences.MemberPresence | None: - """Get a presence object from the cache. + """Get a presence from the cache. Parameters ---------- guild - Object or ID of the guild to get a presence for. + Object or ID of the guild to get the presence for. user - Object or ID of the user to get a presence for. + Object or ID of the user to get the presence for. Returns ------- typing.Optional[hikari.presences.MemberPresence] - The object of the presence that was found in the cache or - [`None`][]. + The presence object if found, otherwise [`None`][]. """ @abc.abstractmethod def get_presences_view( self, ) -> CacheView[snowflakes.Snowflake, CacheView[snowflakes.Snowflake, presences.MemberPresence]]: - """Get a view of all the presence objects in the cache. + """Get a view of the presences in the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, CacheView[hikari.snowflakes.Snowflake]] - A view of guild IDs to views of user IDs to objects of the presences - found in the cache. + A view of guild IDs to views of user IDs to presence objects. """ @abc.abstractmethod def get_presences_view_for_guild( self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], / ) -> CacheView[snowflakes.Snowflake, presences.MemberPresence]: - """Get a view of the presence objects in the cache for a specific guild. + """Get a view of the presences in the cache for a specific guild. Parameters ---------- guild - Object or ID of the guild to get the cached presence objects for. + Object or ID of the guild to get the presences for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.presences.MemberPresence] - A view of user IDs to objects of the presence found in the cache - for the specified guild. + A view of user IDs to presence objects for the specified guild. """ @abc.abstractmethod def get_role(self, role: snowflakes.SnowflakeishOr[guilds.PartialRole], /) -> guilds.Role | None: - """Get a role object from the cache. + """Get a role from the cache. Parameters ---------- role - Object or ID of the role to get from the cache. + Object or ID of the role to get. Returns ------- typing.Optional[hikari.guilds.Role] - The object of the role found in the cache or [`None`][]. + The role object if found, otherwise [`None`][]. """ @abc.abstractmethod def get_roles_view(self) -> CacheView[snowflakes.Snowflake, guilds.Role]: - """Get a view of all the role objects in the cache. + """Get a view of the roles in the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.guilds.Role] - A view of role IDs to objects of the roles found in the cache. + A view of role IDs to objects. """ @abc.abstractmethod @@ -653,39 +635,37 @@ def get_roles_view_for_guild( Parameters ---------- guild - Object or ID of the guild to get the cached roles for. + Object or ID of the guild to get the roles for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.guilds.Role] - A view of role IDs to objects of the roles that were found in the - cache for the specified guild. + A view of role IDs to objects for the specified guild. """ @abc.abstractmethod def get_user(self, user: snowflakes.SnowflakeishOr[users.PartialUser], /) -> users.User | None: - """Get a user object from the cache. + """Get a user from the cache. Parameters ---------- user - Object or ID of the user to get from the cache. + Object or ID of the user to get. Returns ------- typing.Optional[hikari.users.User] - The object of the user that was found in the cache, else - [`None`][]. + The user object if found, otherwise [`None`][]. """ @abc.abstractmethod def get_users_view(self) -> CacheView[snowflakes.Snowflake, users.User]: - """Get a view of the user objects in the cache. + """Get a view of the users in the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.users.User] - The view of user IDs to the users found in the cache. + A view of user IDs to objects. """ @abc.abstractmethod @@ -695,33 +675,31 @@ def get_voice_state( user: snowflakes.SnowflakeishOr[users.PartialUser], /, ) -> voices.VoiceState | None: - """Get a voice state object from the cache. + """Get a voice state from the cache. Parameters ---------- guild - Object or ID of the guild to get a voice state for. + Object or ID of the guild to get the voice state for. user - Object or ID of the user to get a voice state for. + Object or ID of the user to get the voice state for. Returns ------- typing.Optional[hikari.voices.VoiceState] - The object of the voice state that was found in the cache, or - [`None`][]. + The voice state object if found, otherwise [`None`][]. """ @abc.abstractmethod def get_voice_states_view( self, ) -> CacheView[snowflakes.Snowflake, CacheView[snowflakes.Snowflake, voices.VoiceState]]: - """Get a view of all the voice state objects in the cache. + """Get a view of all voice states in the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, CacheView[hikari.snowflakes.Snowflake, hikari.voices.VoiceState]] - A view of guild IDs to views of user IDs to objects of the voice - states that were found in the cache. + A view of guild IDs to views of user IDs to voice state objects. """ @abc.abstractmethod @@ -731,38 +709,36 @@ def get_voice_states_view_for_channel( channel: snowflakes.SnowflakeishOr[channels.PartialChannel], /, ) -> CacheView[snowflakes.Snowflake, voices.VoiceState]: - """Get a view of the voice states cached for a specific channel. + """Get a view of the voice states for a specific channel. Parameters ---------- guild - Object or ID of the guild to get the cached voice states for. + Object or ID of the guild to get the voice states for. channel - Object or ID of the channel to get the cached voice states for. + Object or ID of the channel to get the voice states for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.voices.VoiceState] - A view of user IDs to objects of the voice states found cached for - the specified channel. + A view of user IDs to voice state objects for the specified channel. """ @abc.abstractmethod def get_voice_states_view_for_guild( self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], / ) -> CacheView[snowflakes.Snowflake, voices.VoiceState]: - """Get a view of the voice states cached for a specific guild. + """Get a view of the voice states for a specific guild. Parameters ---------- guild - Object or ID of the guild to get the cached voice states for. + Object or ID of the guild to get the voice states for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.voices.VoiceState] - A view of user IDs to objects of the voice states found cached for - the specified guild. + A view of user IDs to voice state objects for the specified guild. """ @@ -777,17 +753,16 @@ class MutableCache(Cache, abc.ABC): @abc.abstractmethod def clear(self) -> None: - """Clear the full cache.""" + """Clear the entire cache.""" @abc.abstractmethod def clear_dm_channel_ids(self) -> CacheView[snowflakes.Snowflake, snowflakes.Snowflake]: - """Remove all the cached DM channel IDs. + """Remove all the DM channel IDs from the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.snowflakes.Snowflake] - Cache view of user IDs to DM channel IDs which were cleared from - the cache. + A view of user IDs to DM channel IDs that were removed. """ @abc.abstractmethod @@ -799,13 +774,12 @@ def delete_dm_channel_id( Parameters ---------- user - Object or ID of the user to remove the cached DM channel ID for. + Object or ID of the user to remove the DM channel ID for. Returns ------- typing.Optional[hikari.snowflakes.Snowflake] - The DM channel ID which was removed from the cache if found, else - [`None`][]. + The DM channel ID that was removed if found, otherwise [`None`][]. """ @abc.abstractmethod @@ -820,46 +794,44 @@ def set_dm_channel_id( Parameters ---------- user - Object or ID of the user to add a DM channel ID to the cache for. + Object or ID of the user to add a DM channel ID for. channel - Object or ID of the DM channel to add to the cache. + Object or ID of the DM channel to add. """ @abc.abstractmethod def clear_emojis(self) -> CacheView[snowflakes.Snowflake, emojis.KnownCustomEmoji]: - """Remove all the known custom emoji objects from the cache. + """Remove all the known custom emojis from the cache. !!! note - This will skip emojis that are being kept alive by a reference + This will not remove emojis that are being kept alive by a reference on a presence entry. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.emojis.KnownCustomEmoji] - A cache view of emoji IDs to objects of the emojis that were - removed from the cache. + A view of known custom emoji IDs to objects that were removed. """ @abc.abstractmethod def clear_emojis_for_guild( self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], / ) -> CacheView[snowflakes.Snowflake, emojis.KnownCustomEmoji]: - """Remove the known custom emoji objects cached for a specific guild. + """Remove all the known custom emojis from the cache for a specific guild. !!! note - This will skip emojis that are being kept alive by a reference + This will not remove emojis that are being kept alive by a reference on a presence entry. Parameters ---------- guild - Object or ID of the guild to remove the cached emoji objects for. + Object or ID of the guild to remove the emojis for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.emojis.KnownCustomEmoji] - A view of emoji IDs to objects of the emojis that were removed - from the cache. + A view of known custom emoji IDs to objects that were removed. """ @abc.abstractmethod @@ -867,19 +839,18 @@ def delete_emoji(self, emoji: snowflakes.SnowflakeishOr[emojis.CustomEmoji], /) """Remove a known custom emoji from the cache. !!! note - This will not delete emojis that are being kept alive by a reference + This will not remove emojis that are being kept alive by a reference on a presence entry. Parameters ---------- emoji - Object or ID of the emoji to remove from the cache. + Object or ID of the emoji to remove. Returns ------- typing.Optional[hikari.emojis.KnownCustomEmoji] - The object of the emoji that was removed from the cache or - [`None`][]. + The known custom emoji object that was removed if found, otherwise [`None`][]. """ @abc.abstractmethod @@ -889,61 +860,58 @@ def set_emoji(self, emoji: emojis.KnownCustomEmoji, /) -> None: Parameters ---------- emoji - The object of the known custom emoji to add to the cache. + The emoji object to add. """ @abc.abstractmethod def update_emoji( self, emoji: emojis.KnownCustomEmoji, / ) -> tuple[emojis.KnownCustomEmoji | None, emojis.KnownCustomEmoji | None]: - """Update an emoji object in the cache. + """Update a known custom emoji in the cache. Parameters ---------- emoji - The object of the emoji to update in the cache. + The emoji object to update. Returns ------- typing.Tuple[typing.Optional[hikari.emojis.KnownCustomEmoji], typing.Optional[hikari.emojis.KnownCustomEmoji]] - A tuple of the old cached emoji object if found (else [`None`][]) - and the new cached emoji object if it could be cached (else - [`None`][]). + A tuple of the old emoji object that was cached if found (otherwise [`None`][]) + and the new emoji object if it could be cached (otherwise [`None`][]). """ @abc.abstractmethod def clear_stickers(self) -> CacheView[snowflakes.Snowflake, stickers.GuildSticker]: - """Remove all the sticker objects from the cache. + """Remove all the stickers from the cache. !!! note - This will skip stickers that are being kept alive by a reference. + This will not remove stickers that are being kept alive by a reference. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.stickers.GuildSticker] - A cache view of sticker IDs to objects of the stickers that were - removed from the cache. + A view of sticker IDs to objects that were removed. """ @abc.abstractmethod def clear_stickers_for_guild( self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], / ) -> CacheView[snowflakes.Snowflake, stickers.GuildSticker]: - """Remove the known custom emoji objects cached for a specific guild. + """Remove all the known custom emojis from the cache for a specific guild. !!! note - This will skip stickers that are being kept alive by a reference. + This will not remove stickers that are being kept alive by a reference. Parameters ---------- guild - Object or ID of the guild to remove the cached sticker objects for. + Object or ID of the guild to remove the stickers for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.stickers.GuildSticker] - A view of sticker IDs to objects of the stickers that were removed - from the cache. + A view of sticker IDs to objects that were removed. """ @abc.abstractmethod @@ -953,18 +921,17 @@ def delete_sticker( """Remove a sticker from the cache. !!! note - This will not delete stickers that are being kept alive by a reference. + This will not remove stickers that are being kept alive by a reference. Parameters ---------- sticker - Object or ID of the sticker to remove from the cache. + Object or ID of the sticker to remove. Returns ------- typing.Optional[hikari.stickers.GuildSticker] - The object of the sticker that was removed from the cache or - [`None`][]. + The sticker object that was removed if found, otherwise [`None`][]. """ @abc.abstractmethod @@ -974,44 +941,42 @@ def set_sticker(self, sticker: stickers.GuildSticker, /) -> None: Parameters ---------- sticker - The object of the sticker to add to the cache. + The sticker object to add. """ @abc.abstractmethod def clear_guilds(self) -> CacheView[snowflakes.Snowflake, guilds.GatewayGuild]: - """Remove all the guild objects from the cache. + """Remove all the guilds from the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.guilds.GatewayGuild] - The cache view of guild IDs to guild objects that were removed from - the cache. + A view of guild IDs to objects that were removed. """ @abc.abstractmethod def delete_guild(self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], /) -> guilds.GatewayGuild | None: - """Remove a guild object from the cache. + """Remove a guild from the cache. Parameters ---------- guild - Object or ID of the guild to remove from the cache. + Object or ID of the guild to remove. Returns ------- typing.Optional[hikari.guilds.GatewayGuild] - The object of the guild that was removed from the cache, will be - [`None`][] if not found. + The guild object that was removed from the cache if found, otherwise [`None`][]. """ @abc.abstractmethod def set_guild(self, guild: guilds.GatewayGuild, /) -> None: - """Add a guild object to the cache. + """Add a guild to the cache. Parameters ---------- guild - The object of the guild to add to the cache. + The guild object to add. """ @abc.abstractmethod @@ -1021,7 +986,7 @@ def set_guild_availability( is_available: bool, # noqa: FBT001 - Boolean-typed positional argument /, ) -> None: - """Set whether a cached guild is available or not. + """Set whether a guild is available or not in the cache. Parameters ---------- @@ -1040,43 +1005,40 @@ def update_guild( Parameters ---------- guild - The object of the guild to update in the cache. + The guild object to update. Returns ------- typing.Tuple[typing.Optional[hikari.guilds.GatewayGuild], typing.Optional[hikari.guilds.GatewayGuild]] - A tuple of the old cached guild object if found (else [`None`][]) - and the object of the guild that was added to the cache if it could - be added (else [`None`][]). + A tuple of the old guild object that was cached if found (otherwise [`None`][]) + and the new guild object if it could be cached (otherwise [`None`][]). """ @abc.abstractmethod def clear_guild_channels(self) -> CacheView[snowflakes.Snowflake, channels.PermissibleGuildChannel]: - """Remove all guild channels from the cache. + """Remove all the guild channels from the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.channels.PermissibleGuildChannel] - A view of channel IDs to objects of the guild channels that were - removed from the cache. + A view of guild channel IDs to objects that were removed. """ @abc.abstractmethod def clear_guild_channels_for_guild( self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], / ) -> CacheView[snowflakes.Snowflake, channels.PermissibleGuildChannel]: - """Remove guild channels from the cache for a specific guild. + """Remove all the guild channels from the cache for a specific guild. Parameters ---------- guild - Object or ID of the guild to remove cached channels for. + Object or ID of the guild to remove the channels for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.channels.PermissibleGuildChannel] - A view of channel IDs to objects of the guild channels that were - removed from the cache. + A view of guild channel IDs to objects that were removed. """ @abc.abstractmethod @@ -1088,13 +1050,12 @@ def delete_guild_channel( Parameters ---------- channel - Object or ID of the guild channel to remove from the cache. + Object or ID of the guild channel to remove. Returns ------- typing.Optional[hikari.channels.PermissibleGuildChannel] - The object of the guild channel that was removed from the cache if - found, else [`None`][]. + The guild channel object that was removed if found, otherwise [`None`][]. """ @abc.abstractmethod @@ -1104,7 +1065,7 @@ def set_guild_channel(self, channel: channels.PermissibleGuildChannel, /) -> Non Parameters ---------- channel - The guild channel based object to add to the cache. + The guild channel object to add. """ @abc.abstractmethod @@ -1116,25 +1077,23 @@ def update_guild_channel( Parameters ---------- channel - The object of the channel to update in the cache. + The guild channel object to update. Returns ------- typing.Tuple[typing.Optional[hikari.channels.PermissibleGuildChannel], typing.Optional[hikari.channels.PermissibleGuildChannel]] - A tuple of the old cached guild channel if found (else [`None`][]) - and the new cached guild channel if it could be cached - (else [`None`][]). + A tuple of the old guild channel object that was cached if found (otherwise [`None`][]) + and the new guild channel object if it could be cached (otherwise [`None`][]). """ # noqa: E501 - Line too long @abc.abstractmethod def clear_threads(self) -> CacheView[snowflakes.Snowflake, channels.GuildThreadChannel]: - """Remove all thread channels from the cache. + """Remove all the thread channels from the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.channels.GuildThreadChannel] - A view of channel IDs to objects of the thread channels that were - removed from the cache. + A view of thread channel IDs to objects that were removed. """ @abc.abstractmethod @@ -1149,15 +1108,14 @@ def clear_threads_for_channel( Parameters ---------- guild - Object or ID of the guild to remove cached threads for. + Object or ID of the guild to remove the threads for. channel - Object or ID of the channel to remove cached threads for. + Object or ID of the channel to remove the threads for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.channels.GuildThreadChannel] - A view of channel IDs to objects of the thread channels that were - removed from the cache. + A view of thread channel IDs to objects that were removed. """ @abc.abstractmethod @@ -1169,13 +1127,12 @@ def clear_threads_for_guild( Parameters ---------- guild - Object or ID of the guild to remove cached threads for. + Object or ID of the guild to remove the threads for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.channels.GuildThreadChannel] - A view of channel IDs to objects of the thread channels that were - removed from the cache. + A view of thread channel IDs to objects that were removed. """ @abc.abstractmethod @@ -1187,13 +1144,12 @@ def delete_thread( Parameters ---------- thread - Object or ID of the thread to remove from the cache. + Object or ID of the thread to remove. Returns ------- typing.Optional[hikari.channels.GuildThreadChannel] - The object of the thread that was removed from the cache if - found, else [`None`][]. + The thread object removed if found, otherwise [`None`][]. """ @abc.abstractmethod @@ -1203,7 +1159,7 @@ def set_thread(self, channel: channels.GuildThreadChannel, /) -> None: Parameters ---------- channel - The thread channel based object to add to the cache. + The thread channel object to add. """ @abc.abstractmethod @@ -1215,43 +1171,40 @@ def update_thread( Parameters ---------- thread - The object of the thread channel to update in the cache. + The object of the thread channel to update. Returns ------- typing.Tuple[typing.Optional[hikari.channels.GuildThreadChannel], typing.Optional[hikari.channels.GuildThreadChannel]] - A tuple of the old cached thread channel if found (else [`None`][]) - and the new cached thread channel if it could be cached - (else [`None`][]). - """ # noqa: E501 + A tuple of the old thread channel object that was cached if found (otherwise [`None`][]) + and the new thread channel object if it could be cached (otherwise [`None`][]). + """ # noqa: E501 - Line too long @abc.abstractmethod def clear_invites(self) -> CacheView[str, invites.InviteWithMetadata]: - """Remove all the invite objects from the cache. + """Remove all the invites from the cache. Returns ------- CacheView[str, hikari.invites.InviteWithMetadata] - A view of invite code strings to objects of the invites that were - removed from the cache. + A view of invite code strings to objects that were removed. """ @abc.abstractmethod def clear_invites_for_guild( self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], / ) -> CacheView[str, invites.InviteWithMetadata]: - """Remove the invite objects in the cache for a specific guild. + """Remove all the invites from the cache for a specific guild. Parameters ---------- guild - Object or ID of the guild to remove invite objects for. + Object or ID of the guild to remove invites for. Returns ------- CacheView[str, hikari.invites.InviteWithMetadata] - A view of invite code strings to objects of the invites that were - removed from the cache for the specified guild. + A view of invite code strings to objects that were removed for the specified guild. """ @abc.abstractmethod @@ -1261,46 +1214,44 @@ def clear_invites_for_channel( channel: snowflakes.SnowflakeishOr[channels.PartialChannel], /, ) -> CacheView[str, invites.InviteWithMetadata]: - """Remove the invite objects in the cache for a specific channel. + """Remove all the invites from the cache for a specific channel. Parameters ---------- guild - Object or ID of the guild to remove invite objects for. + Object or ID of the guild to remove invites for. channel - Object or ID of the channel to remove invite objects for. + Object or ID of the channel to remove invites for. Returns ------- CacheView[str, hikari.invites.InviteWithMetadata] - A view of invite code strings to objects of the invites that were - removed from the cache for the specified channel. + A view of invite code strings to objects that were removed for the specified channel. """ @abc.abstractmethod def delete_invite(self, code: invites.InviteCode | str, /) -> invites.InviteWithMetadata | None: - """Remove an invite object from the cache. + """Remove an invite from the cache. Parameters ---------- code - Object or string code of the invite to remove from the cache. + Object or string code of the invite to remove. Returns ------- typing.Optional[hikari.invites.InviteWithMetadata] - The object of the invite that was removed from the cache if found, - else [`None`][]. + The invite object removed from the cache if found, otherwise [`None`][]. """ @abc.abstractmethod def set_invite(self, invite: invites.InviteWithMetadata, /) -> None: - """Add an invite object to the cache. + """Add an invite to the cache. Parameters ---------- invite - The object of the invite to add to the cache. + The object of the invite to add. """ @abc.abstractmethod @@ -1312,52 +1263,49 @@ def update_invite( Parameters ---------- invite - The object of the invite to update in the cache. + The object of the invite to update. Returns ------- typing.Tuple[typing.Optional[hikari.invites.InviteWithMetadata], typing.Optional[hikari.invites.InviteWithMetadata]] - A tuple of the old cached invite object if found (else - [`None`][]) and the new cached invite object if it could be - cached (else [`None`][]). - """ # noqa: E501 + A tuple of the old invite object that was cached if found (otherwise [`None`][]) + and the new invite object if it could be cached (otherwise [`None`][]). + """ # noqa: E501 - Line too long @abc.abstractmethod def delete_me(self) -> users.OwnUser | None: - """Remove the own user object from the cache. + """Remove the own user from the cache. Returns ------- typing.Optional[hikari.users.OwnUser] - The own user object that was removed from the cache if found, - else [`None`][]. + The own user object that was removed if found, otherwise [`None`][]. """ @abc.abstractmethod def set_me(self, user: users.OwnUser, /) -> None: - """Set the own user object in the cache. + """Set the own user in the cache. Parameters ---------- user - The own user object to set in the cache. + The own user object to set. """ @abc.abstractmethod def update_me(self, user: users.OwnUser, /) -> tuple[users.OwnUser | None, users.OwnUser | None]: - """Update the own user entry in the cache. + """Update the own user in the cache. Parameters ---------- user - The own user object to update in the cache. + The own user object to update. Returns ------- typing.Tuple[typing.Optional[hikari.users.OwnUser], typing.Optional[hikari.users.OwnUser]] - A tuple of the old cached own user object if found (else - [`None`][]) and the new cached own user object if it could be - cached, else [`None`][]. + A tuple of the old own user object that was cached if found (otherwise [`None`][]) + and the new own user object if it could be cached, otherwise [`None`][]. """ @abc.abstractmethod @@ -1367,30 +1315,28 @@ def clear_members(self) -> CacheView[snowflakes.Snowflake, CacheView[snowflakes. Returns ------- CacheView[hikari.snowflakes.Snowflake, CacheView[hikari.snowflakes.Snowflake, hikari.guilds.Member]] - A view of guild IDs to views of user IDs to objects of the members - that were removed from the cache. + A view of guild IDs to views of user IDs to member objects that were removed from the cache. """ @abc.abstractmethod def clear_members_for_guild( self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], / ) -> CacheView[snowflakes.Snowflake, guilds.Member]: - """Remove the members for a specific guild from the cache. + """Remove all the members from the cache for a specific guild. !!! note - This will skip members that are being referenced by other entries in + This will not remove members that are being referenced by other entries in the cache; a matching voice state will keep a member entry alive. Parameters ---------- guild - Object or ID of the guild to remove cached members for. + Object or ID of the guild to remove the members for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.guilds.Member] - The view of user IDs to the member objects that were removed from - the cache. + A view of user IDs to the member objects that were removed. """ @abc.abstractmethod @@ -1400,35 +1346,33 @@ def delete_member( user: snowflakes.SnowflakeishOr[users.PartialUser], /, ) -> guilds.Member | None: - """Remove a member object from the cache. + """Remove a member from the cache. !!! note - You cannot delete a member entry that's being referenced by other - entries in the cache; a matching voice state will keep a member - entry alive. + This will not remove a member that is being referenced by other entries in + the cache; a matching voice state will keep a member entry alive. Parameters ---------- guild - Object or ID of the guild to remove a member from the cache for. + Object or ID of the guild to remove a member for. user - Object or ID of the user to remove a member from the cache for. + Object or ID of the user to remove a member for. Returns ------- typing.Optional[hikari.guilds.Member] - The object of the member that was removed from the cache if found, - else [`None`][]. + The member object that was removed if found, otherwise [`None`][]. """ @abc.abstractmethod def set_member(self, member: guilds.Member, /) -> None: - """Add a member object to the cache. + """Add a member to the cache. Parameters ---------- member - The object of the member to add to the cache. + The object of the member to add. """ @abc.abstractmethod @@ -1438,34 +1382,32 @@ def update_member(self, member: guilds.Member, /) -> tuple[guilds.Member | None, Parameters ---------- member - The object of the member to update in the cache. + The object of the member to update. Returns ------- typing.Tuple[typing.Optional[hikari.guilds.Member], typing.Optional[hikari.guilds.Member]] - A tuple of the old cached member object if found (else [`None`][]) - and the new cached member object if it could be cached (else - [`None`][]). + A tuple of the old member object that was cached if found (otherwise [`None`][]) + and the new member object if it could be cached (otherwise [`None`][]). """ @abc.abstractmethod def clear_presences( self, ) -> CacheView[snowflakes.Snowflake, CacheView[snowflakes.Snowflake, presences.MemberPresence]]: - """Remove all the presences in the cache. + """Remove all the presences from the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, CacheView[hikari.snowflakes.Snowflake, hikari.presences.MemberPresence]] - A view of guild IDs to views of user IDs to objects of the presences - that were removed from the cache. + A view of guild IDs to views of user IDs to presence objects that were removed. """ @abc.abstractmethod def clear_presences_for_guild( self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], / ) -> CacheView[snowflakes.Snowflake, presences.MemberPresence]: - """Remove the presences in the cache for a specific guild. + """Remove all the presences in the cache for a specific guild. Parameters ---------- @@ -1475,8 +1417,7 @@ def clear_presences_for_guild( Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.presences.MemberPresence] - A view of user IDs to objects of the presences that were removed - from the cache for the specified guild. + A view of user IDs to presence objects that were removed for the specified guild. """ @abc.abstractmethod @@ -1498,55 +1439,52 @@ def delete_presence( Returns ------- typing.Optional[hikari.presences.MemberPresence] - The object of the presence that was removed from the cache if found, - else [`None`][]. + The presence object that was removed if found, otherwise [`None`][]. """ @abc.abstractmethod def set_presence(self, presence: presences.MemberPresence, /) -> None: - """Add a presence object to the cache. + """Add a presence to the cache. Parameters ---------- presence - The object of the presence to add to the cache. + The object of the presence to add. """ @abc.abstractmethod def update_presence( self, presence: presences.MemberPresence, / ) -> tuple[presences.MemberPresence | None, presences.MemberPresence | None]: - """Update a presence object in the cache. + """Update a presence in the cache. Parameters ---------- presence - The object of the presence to update in the cache. + The object of the presence to update. Returns ------- typing.Tuple[typing.Optional[hikari.presences.MemberPresence], typing.Optional[hikari.presences.MemberPresence]] - A tuple of the old cached invite object if found (else [`None`][] - and the new cached invite object if it could be cached ( else - [`None`][]). + A tuple of the old invite object that was cached if found (otherwise [`None`][] + and the new invite object if it could be cached (otherwise [`None`][]). """ @abc.abstractmethod def clear_roles(self) -> CacheView[snowflakes.Snowflake, guilds.Role]: - """Remove all role objects from the cache. + """Remove all the roles from the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.guilds.Role] - A view of role IDs to objects of the roles that were removed from - the cache. + A view of role IDs to objects that were removed. """ @abc.abstractmethod def clear_roles_for_guild( self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], / ) -> CacheView[snowflakes.Snowflake, guilds.Role]: - """Remove role objects from the cache for a specific guild. + """Remove all the roles from the cache for a specific guild. Parameters ---------- @@ -1556,34 +1494,32 @@ def clear_roles_for_guild( Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.guilds.Role] - A view of role IDs to objects of the roles that were removed from - the cache for the specific guild. + A view of role IDs to objects that were removed for the specific guild. """ @abc.abstractmethod def delete_role(self, role: snowflakes.SnowflakeishOr[guilds.PartialRole], /) -> guilds.Role | None: - """Remove a role object form the cache. + """Remove a role from the cache. Parameters ---------- role - Object or ID of the role to remove from the cache. + Object or ID of the role to remove. Returns ------- typing.Optional[hikari.guilds.Role] - The object of the role that was removed from the cache if found, - else [`None`][]. + The role object that was removed if found, otherwise [`None`][]. """ @abc.abstractmethod def set_role(self, role: guilds.Role, /) -> None: - """Add a role object to the cache. + """Add a role to the cache. Parameters ---------- role - The object of the role to add to the cache. + Object of the role to add. """ @abc.abstractmethod @@ -1593,43 +1529,40 @@ def update_role(self, role: guilds.Role, /) -> tuple[guilds.Role | None, guilds. Parameters ---------- role - The object of the role to update in the cache. + Object of the role to update. Returns ------- typing.Tuple[typing.Optional[hikari.guilds.Role], typing.Optional[hikari.guilds.Role]] - A tuple of the old cached role object if found (else [`None`][] - and the new cached role object if it could be cached (else - [`None`][]). + A tuple of the old role object that was cached if found (otherwise [`None`][] + and the new role object if it could be cached (otherwise [`None`][]). """ @abc.abstractmethod def clear_voice_states(self) -> CacheView[snowflakes.Snowflake, CacheView[snowflakes.Snowflake, voices.VoiceState]]: - """Remove all voice state objects from the cache. + """Remove all the voice states from the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, CacheView[hikari.snowflakes.Snowflake, hikari.voices.VoiceState]] - A view of guild IDs to views of user IDs to objects of the voice - states that were removed from the states. + A view of guild IDs to views of user IDs to voice state objects that were removed. """ @abc.abstractmethod def clear_voice_states_for_guild( self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], / ) -> CacheView[snowflakes.Snowflake, voices.VoiceState]: - """Clear the voice state objects cached for a specific guild. + """Remove all the voice states from the cache for a specific guild. Parameters ---------- guild - Object or ID of the guild to remove cached voice states for. + Object or ID of the guild to remove the voice states for. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.voices.VoiceState] - A view of user IDs to the voice state objects that were removed from - the cache. + A view of user IDs to voice state objects that were removed. """ @abc.abstractmethod @@ -1639,7 +1572,7 @@ def clear_voice_states_for_channel( channel: snowflakes.SnowflakeishOr[channels.PartialChannel], /, ) -> CacheView[snowflakes.Snowflake, voices.VoiceState]: - """Remove the voice state objects cached for a specific channel. + """Remove the voice states from the cache for a specific channel. Parameters ---------- @@ -1651,8 +1584,7 @@ def clear_voice_states_for_channel( Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.voices.VoiceState] - A view of user IDs to objects of the voice state that were removed - from the cache for the specified channel. + A view of user IDs to voice state objects that were removed for the specified channel. """ @abc.abstractmethod @@ -1662,64 +1594,62 @@ def delete_voice_state( user: snowflakes.SnowflakeishOr[users.PartialUser], /, ) -> voices.VoiceState | None: - """Remove a voice state object from the cache. + """Remove a voice state from the cache. Parameters ---------- guild - Object or ID of the guild the voice state to remove is related to. + Object or ID of the guild to remove the voice state for. user - Object or ID of the user who the voice state to remove belongs to. + Object or ID of the user who to remove the voice state for. Returns ------- typing.Optional[hikari.voices.VoiceState] - The object of the voice state that was removed from the cache if - found, else [`None`][]. + The object of the voice state removed if found, otherwise [`None`][]. """ @abc.abstractmethod def set_voice_state(self, voice_state: voices.VoiceState, /) -> None: - """Add a voice state object to the cache. + """Add a voice state to the cache. Parameters ---------- voice_state - The object of the voice state to add to the cache. + Object of the voice state to add. """ @abc.abstractmethod def update_voice_state( self, voice_state: voices.VoiceState, / ) -> tuple[voices.VoiceState | None, voices.VoiceState | None]: - """Update a voice state object in the cache. + """Update a voice state in the cache. Parameters ---------- voice_state - The object of the voice state to update in the cache. + Object of the voice state to update. Returns ------- typing.Tuple[typing.Optional[hikari.voices.VoiceState], typing.Optional[hikari.voices.VoiceState]] - A tuple of the old cached voice state if found (else [`None`][]) - and the new cached voice state object if it could be cached - (else [`None`][]). + A tuple of the old voice state object that was cached if found (otherwise [`None`][]) + and the new voice state object if it could be cached (otherwise [`None`][]). """ @abc.abstractmethod def clear_messages(self) -> CacheView[snowflakes.Snowflake, messages.Message]: - """Remove all message objects from the cache. + """Remove all the messages from the cache. Returns ------- CacheView[hikari.snowflakes.Snowflake, hikari.messages.Message] - A view of message objects that were removed from the cache. + A view of message IDs to objects that were removed. """ @abc.abstractmethod def delete_message(self, message: snowflakes.SnowflakeishOr[messages.PartialMessage], /) -> messages.Message | None: - """Remove a message object from the cache. + """Remove a message from the cache. Parameters ---------- @@ -1729,18 +1659,17 @@ def delete_message(self, message: snowflakes.SnowflakeishOr[messages.PartialMess Returns ------- typing.Optional[hikari.messages.Message] - The object of the message that was removed from the cache if found, - else [`None`][]. + The message object that was removed if found, otherwise [`None`][]. """ @abc.abstractmethod def set_message(self, message: messages.Message, /) -> None: - """Add a message object to the cache. + """Add a message to the cache. Parameters ---------- message - The object of the message to add to the cache. + Object of the message to add. """ @abc.abstractmethod @@ -1752,12 +1681,11 @@ def update_message( Parameters ---------- message - The object of the message to update in the cache. + Object of the message to update in the cache. Returns ------- typing.Tuple[typing.Optional[hikari.messages.Message], typing.Optional[hikari.messages.Message]] - A tuple of the old cached message object if found (else [`None`][]) - and the new cached message object if it could be cached (else - [`None`][]). + A tuple of the old message object that was cached if found (otherwise [`None`][]) + and the new message object if it could be cached (otherwise [`None`][]). """ diff --git a/hikari/api/config.py b/hikari/api/config.py index 8f580e8149..fa4258bfee 100644 --- a/hikari/api/config.py +++ b/hikari/api/config.py @@ -122,7 +122,7 @@ def trust_env(self) -> bool: !!! note For more details of using `netrc`, visit: - https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html + """ @@ -160,15 +160,15 @@ def ssl(self) -> ssl_.SSLContext: This may be assigned a [`bool`][] or an [`ssl.SSLContext`][] object. - If assigned to [`True`][], a default SSL context is generated by - this class that will enforce SSL verification. This is then stored in + If assigned [`True`][], a default SSL context is generated by + this class that will enforce SSL verification. It is then stored in this field. - If [`False`][], then a default SSL context is generated by this - class that will **NOT** enforce SSL verification. This is then stored + If assigned [`False`][], then a default SSL context is generated by this + class that will **NOT** enforce SSL verification. It is then stored in this field. - If an instance of [`ssl.SSLContext`][], then this context will be used. + If assigned an instance of [`ssl.SSLContext`][], then that context will be used. !!! warning Setting a custom value here may have security implications, or diff --git a/hikari/api/entity_factory.py b/hikari/api/entity_factory.py index 47e98bb361..a26fe2cad5 100644 --- a/hikari/api/entity_factory.py +++ b/hikari/api/entity_factory.py @@ -73,27 +73,27 @@ class GatewayGuildDefinition(abc.ABC): @property @abc.abstractmethod def id(self) -> snowflakes.Snowflake: - """ID of the guild the definition is for.""" + """The ID of the guild this definition is for.""" @abc.abstractmethod def channels(self) -> typing.Mapping[snowflakes.Snowflake, channel_models.PermissibleGuildChannel]: - """Get a mapping of channel IDs to the channels that belong to the guild.""" + """A mapping of channel IDs to objects for the guild.""" @abc.abstractmethod def emojis(self) -> typing.Mapping[snowflakes.Snowflake, emoji_models.KnownCustomEmoji]: - """Get a mapping of emoji IDs to the emojis that belong to the guild.""" + """A mapping of emoji IDs to objects for the guild.""" @abc.abstractmethod def stickers(self) -> typing.Mapping[snowflakes.Snowflake, sticker_models.GuildSticker]: - """Get a mapping of sticker IDs to the stickers that belong to the guild.""" + """A mapping of sticker IDs to objects for the guild.""" @abc.abstractmethod def guild(self) -> guild_models.GatewayGuild: - """Get the object of the guild this definition is for.""" + """The object of the guild this definition is for.""" @abc.abstractmethod def members(self) -> typing.Mapping[snowflakes.Snowflake, guild_models.Member]: - """Get a mapping of user IDs to the members that belong to the guild. + """A mapping of user IDs to member objects for the guild. !!! note This may be a partial mapping of members in the guild. @@ -101,7 +101,7 @@ def members(self) -> typing.Mapping[snowflakes.Snowflake, guild_models.Member]: @abc.abstractmethod def presences(self) -> typing.Mapping[snowflakes.Snowflake, presence_models.MemberPresence]: - """Get a mapping of user IDs to the presences that are active in the guild. + """A mapping of user IDs to the presences that are active in the guild. !!! note This may be a partial mapping of presences active in the guild. @@ -109,15 +109,15 @@ def presences(self) -> typing.Mapping[snowflakes.Snowflake, presence_models.Memb @abc.abstractmethod def roles(self) -> typing.Mapping[snowflakes.Snowflake, guild_models.Role]: - """Get a mapping of role IDs to the roles that belong to the guild.""" + """A mapping of role IDs to objects for the guild.""" @abc.abstractmethod def threads(self) -> typing.Mapping[snowflakes.Snowflake, channel_models.GuildThreadChannel]: - """Get a mapping of thread IDs to the public threads the bot can access in the guild.""" + """A mapping of thread IDs to objects the bot can access in the guild.""" @abc.abstractmethod def voice_states(self) -> typing.Mapping[snowflakes.Snowflake, voice_models.VoiceState]: - """Get a mapping of user IDs to the voice states that are active in the guild.""" + """A mapping of user IDs to voice state objects that are active in the guild.""" class EntityFactory(abc.ABC): @@ -141,7 +141,7 @@ def deserialize_own_connection(self, payload: data_binding.JSONObject) -> applic Returns ------- hikari.applications.OwnConnection - The deserialized "own connection" object. + The deserialized own connection object. """ @abc.abstractmethod @@ -156,7 +156,7 @@ def deserialize_own_guild(self, payload: data_binding.JSONObject) -> application Returns ------- hikari.applications.OwnGuild - The deserialized "own guild" object. + The deserialized own guild object. """ @abc.abstractmethod @@ -173,7 +173,7 @@ def deserialize_own_application_role_connection( Returns ------- hikari.applications.OwnApplicationRoleConnection - The deserialized "own application role connection" object. + The deserialized own application role connection object. """ @abc.abstractmethod @@ -222,14 +222,14 @@ def deserialize_application_connection_metadata_record( Returns ------- hikari.applications.ApplicationRoleConnectionMetadataRecord - The deserialized "application connection metadata record" object. + The deserialized application connection metadata record object. """ @abc.abstractmethod def serialize_application_connection_metadata_record( self, record: application_models.ApplicationRoleConnectionMetadataRecord ) -> data_binding.JSONObject: - """Serialize an application connection metadata record object to a json serializable dict. + """Serialize an application connection metadata record object into a JSON serializable dict. Parameters ---------- @@ -261,7 +261,7 @@ def deserialize_partial_token(self, payload: data_binding.JSONObject) -> applica def deserialize_authorization_token( self, payload: data_binding.JSONObject ) -> application_models.OAuth2AuthorizationToken: - """Parse a raw payload from Discord into an authorization token object. + """Parse a raw payload from Discord into an OAuth2 authorization token object. Parameters ---------- @@ -276,7 +276,7 @@ def deserialize_authorization_token( @abc.abstractmethod def deserialize_implicit_token(self, query: data_binding.Query) -> application_models.OAuth2ImplicitToken: - """Parse a query from Discord into an implicit token object. + """Parse a query from Discord into an OAuth2 implicit token object. Parameters ---------- @@ -327,7 +327,7 @@ def deserialize_audit_log_entry( The JSON payload to deserialize. guild_id The ID of the guild this entry belongs to. If passed then this - will be prioritised over `"guild_id"` in the payload. + will be prioritized over `"guild_id"` in the payload. Returns ------- @@ -377,7 +377,7 @@ def deserialize_permission_overwrite(self, payload: data_binding.JSONObject) -> @abc.abstractmethod def serialize_permission_overwrite(self, overwrite: channel_models.PermissionOverwrite) -> data_binding.JSONObject: - """Serialize a permission overwrite object to a json serializable dict. + """Serialize a permission overwrite object into a JSON serializable dict. Parameters ---------- @@ -402,7 +402,7 @@ def deserialize_partial_channel(self, payload: data_binding.JSONObject) -> chann Returns ------- hikari.channels.PartialChannel - The deserialized "partial channel" object. + The deserialized partial channel object. """ @abc.abstractmethod @@ -449,11 +449,12 @@ def deserialize_guild_category( payload The JSON payload to deserialize. guild_id - The ID of the guild this channel belongs to. If passed then this - will be prioritised over `"guild_id"` in the payload. + The ID of the guild this category belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. - This currently only covers the gateway `GUILD_CREATE` event, - where it is not included in the channel's payload. + !!! note + This currently only covers the gateway `GUILD_CREATE` event, + where `"guild_id"` is not included in the category's payload. Returns ------- @@ -481,11 +482,12 @@ def deserialize_guild_text_channel( payload The JSON payload to deserialize. guild_id - The ID of the guild this channel belongs to. If passed then this - will be prioritised over `"guild_id"` in the payload. + The ID of the guild this channel belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. - This currently only covers the gateway `GUILD_CREATE` event, - where it is not included in the channel's payload. + !!! note + This currently only covers the gateway `GUILD_CREATE` event, + where `"guild_id"` is not included in the channel's payload. Returns ------- @@ -513,11 +515,12 @@ def deserialize_guild_news_channel( payload The JSON payload to deserialize. guild_id - The ID of the guild this channel belongs to. If passed then this - will be prioritised over `"guild_id"` in the payload. + The ID of the guild this channel belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. - This currently only covers the gateway `GUILD_CREATE` event, - where it is not included in the channel's payload. + !!! note + This currently only covers the gateway `GUILD_CREATE` event, + where `"guild_id"` is not included in the channel's payload. Returns ------- @@ -545,11 +548,12 @@ def deserialize_guild_voice_channel( payload The JSON payload to deserialize. guild_id - The ID of the guild this channel belongs to. If passed then this - will be prioritised over `"guild_id"` in the payload. + The ID of the guild this channel belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. - This currently only covers the gateway `GUILD_CREATE` event, - where it is not included in the channel's payload. + !!! note + This currently only covers the gateway `GUILD_CREATE` event, + where `"guild_id"` is not included in the channel's payload. Returns ------- @@ -577,11 +581,12 @@ def deserialize_guild_stage_channel( payload The JSON payload to deserialize. guild_id - The ID of the guild this channel belongs to. If passed then this - will be prioritised over `"guild_id"` in the payload. + The ID of the guild this channel belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. - This currently only covers the gateway `GUILD_CREATE` event, - where it is not included in the channel's payload. + !!! note + This currently only covers the gateway `GUILD_CREATE` event, + where `"guild_id"` is not included in the channel's payload. Returns ------- @@ -609,11 +614,12 @@ def deserialize_guild_forum_channel( payload The JSON payload to deserialize. guild_id - The ID of the guild this channel belongs to. If passed then this - will be prioritised over `"guild_id"` in the payload. + The ID of the guild this channel belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. - This currently only covers the gateway `GUILD_CREATE` event, - where it is not included in the channel's payload. + !!! note + This currently only covers the gateway `GUILD_CREATE` event, + where `"guild_id"` is not included in the channel's payload. Returns ------- @@ -629,7 +635,7 @@ def deserialize_guild_forum_channel( @abc.abstractmethod def serialize_forum_tag(self, tag: channel_models.ForumTag) -> data_binding.JSONObject: - """Serialize a forum tag object to a json serializable dict. + """Serialize a forum tag object into a JSON serializable dict. Parameters ---------- @@ -656,12 +662,12 @@ def deserialize_thread_member( payload The JSON payload to deserialize. thread_id - ID of the thread this member belongs to. This will be - prioritised over `"id"` in the payload when passed. + The ID of the thread this member belongs to. + This will be prioritized over `"id"` in the payload when passed. !!! note - `thread_id` currently only covers the gateway `GUILD_CREATE` event - where the field are is included in the thread member's payload. + This currently only covers the gateway `GUILD_CREATE` event, + where `"id"` is not included in the thread member's payload. Returns ------- @@ -672,7 +678,7 @@ def deserialize_thread_member( ------ KeyError If `thread_id` is left as [`hikari.undefined.UNDEFINED`][] - when the relevant field isn't present in the passed payload. + when `"id"` is not present in the passed payload. """ @abc.abstractmethod @@ -688,15 +694,15 @@ def deserialize_guild_thread( Parameters ---------- guild_id - The ID of the guild this channel belongs to. If passed then this - will be prioritised over `"guild_id"` in the payload. + The ID of the guild this thread belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. !!! note - `guild_id` currently only covers the gateway `GUILD_CREATE` event - where `"guild_id"` is not included in the channel's payload. + This currently only covers the gateway `GUILD_CREATE` event, + where `"guild_id"` is not included in the thread's payload. member - The member object for the thread. If passed then this will be - prioritised over `"member"` in the payload when passed. + The member object for the thread. This will be prioritized over + `"member"` in the payload when passed. Returns ------- @@ -725,15 +731,15 @@ def deserialize_guild_news_thread( payload The JSON payload to deserialize. guild_id - The ID of the guild this channel belongs to. This will be - prioritised over `"guild_id"` in the payload when passed. + The ID of the guild this thread belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. !!! note - `guild_id` currently only covers the gateway `GUILD_CREATE` event - where `"guild_id"` is not included in the channel's payload. + This currently only covers the gateway `GUILD_CREATE` event, + where `"guild_id"` is not included in the thread's payload. member - The member object for the thread. If passed then this will be - prioritised over `"member"` in the payload when passed. + The member object for the thread. + This will be prioritized over `"member"` in the payload when passed. Returns ------- @@ -762,15 +768,15 @@ def deserialize_guild_public_thread( payload The JSON payload to deserialize. guild_id - The ID of the guild this channel belongs to. This will be - prioritised over `"guild_id"` in the payload when passed. + The ID of the guild this thread belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. !!! note - `guild_id` currently only covers the gateway `GUILD_CREATE` event - where `"guild_id"` is not included in the channel's payload. + This currently only covers the gateway `GUILD_CREATE` event, + where `"guild_id"` is not included in the thread's payload. member - The member object for the thread. If passed then this will be - prioritised over `"member"` in the payload when passed. + The member object for the thread. + This will be prioritized over `"member"` in the payload when passed. Returns ------- @@ -799,15 +805,15 @@ def deserialize_guild_private_thread( payload The JSON payload to deserialize. guild_id - The ID of the guild this channel belongs to. This will be - prioritised over `"guild_id"` in the payload when passed. + The ID of the guild this thread belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. !!! note - `guild_id` currently only covers the gateway `GUILD_CREATE` event - where `"guild_id"` is not included in the channel's payload. + This currently only covers the gateway `GUILD_CREATE` event, + where `"guild_id"` is not included in the thread's payload. member - The member object for the thread. If passed then this will be - prioritised over `"member"` in the payload when passed. + The member object for the thread. + This will be prioritized over `"member"` in the payload when passed. Returns ------- @@ -831,7 +837,7 @@ def deserialize_channel( """Parse a raw payload from Discord into a channel object. !!! note - This also deserializes to thread channels. + This also deserializes thread channels. Parameters ---------- @@ -839,23 +845,23 @@ def deserialize_channel( The JSON payload to deserialize. guild_id The ID of the guild this channel belongs to. This will be ignored - for DM and group DM channels and will be prioritised over + for DM and group DM channels and will be prioritized over `"guild_id"` in the payload when passed. - This is necessary in `GUILD_CREATE` events, where `"guild_id"` is not - included in the channel's payload + !!! note + This is necessary for gateway `GUILD_CREATE` events, + where `"guild_id"` is not included in the channel's payload. Returns ------- hikari.channels.PartialChannel - The deserialized partial channel-derived object. + The deserialized partial channel object. Raises ------ KeyError If `guild_id` is left as [`hikari.undefined.UNDEFINED`][] when - `"guild_id"` is not present in the passed payload of a guild - channel. + `"guild_id"` is not present in the passed payload. hikari.errors.UnrecognisedEntityError If the channel type is unknown. """ @@ -883,7 +889,7 @@ def deserialize_embed(self, payload: data_binding.JSONObject) -> embed_models.Em def serialize_embed( self, embed: embed_models.Embed ) -> tuple[data_binding.JSONObject, list[files.Resource[files.AsyncReader]]]: - """Serialize an embed object to a json serializable dict. + """Serialize an embed object into a JSON serializable dict. Parameters ---------- @@ -950,14 +956,12 @@ def deserialize_known_custom_emoji( for application emojis. This is used to ensure that the guild a known custom emoji belongs to - is remembered by allowing for a context based artificial `guild_id` attribute. - - + is remembered by allowing for a context-based artificial `guild_id` attribute. Returns ------- hikari.emojis.KnownCustomEmoji - The deserialized "known custom emoji" object. + The deserialized known custom emoji object. """ @abc.abstractmethod @@ -1032,7 +1036,7 @@ def deserialize_welcome_screen(self, payload: data_binding.JSONObject) -> guild_ @abc.abstractmethod def serialize_welcome_channel(self, welcome_channel: guild_models.WelcomeChannel) -> data_binding.JSONObject: - """Serialize a welcome channel object to a json serializable dict. + """Serialize a welcome channel object into a JSON serializable dict. Parameters ---------- @@ -1055,21 +1059,21 @@ def deserialize_member( ) -> guild_models.Member: """Parse a raw payload from Discord into a member object. - !!! note - `guild_id` covers cases such as the GUILD_CREATE gateway event and - GET Guild Member where `"guild_id"` is not included in the returned - payload. - Parameters ---------- payload The JSON payload to deserialize. user The user to attach to this member, should only be passed in - situations where "user" is not included in the payload. + situations where `"user"` is not included in the payload. guild_id - The ID of the guild this member belongs to. If this is specified - then this will be prioritised over `"guild_id"` in the payload. + The ID of the guild this member belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. + + !!! note + This currently only covers the gateway `GUILD_CREATE` event and + the REST API Get Guild Member endpoint, where is not included + in the payload. Returns ------- @@ -1096,7 +1100,7 @@ def deserialize_role( guild_id The ID of the guild this role belongs to. This is used to ensure that the guild a role belongs to is remembered by allowing for a - context based artificial `guild_id` attribute. + context-based artificial `guild_id` attribute. Returns ------- @@ -1133,8 +1137,8 @@ def deserialize_integration( payload The JSON payload to deserialize. guild_id - The ID of the guild this integration belongs to. If this is specified - then this will be prioritised over `"guild_id"` in the payload. + The ID of the guild this integration belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. Returns ------- @@ -1145,8 +1149,7 @@ def deserialize_integration( ------ KeyError If `guild_id` is left as [`hikari.undefined.UNDEFINED`][] when - `"guild_id"` is not present in the passed payload for the payload of - the integration. + `"guild_id"` is not present in the passed payload. """ @abc.abstractmethod @@ -1227,15 +1230,17 @@ def deserialize_gateway_guild( GatewayGuildDefinition The deserialized guild object and the internal collections as maps of [`hikari.snowflakes.Snowflake`][] mapping to - [`hikari.channels.GuildChannel`][], + [`hikari.channels.PermissibleGuildChannel`][], + [`hikari.emojis.KnownCustomEmoji`][], + [`hikari.stickers.GuildSticker`][], [`hikari.guilds.Member`][], [`hikari.presences.MemberPresence`][], [`hikari.guilds.Role`][], - [`hikari.emojis.KnownCustomEmoji`][], and - [`hikari.stickers.GuildSticker`][]. This is provided in - several components to allow separate caching and linking - between entities in various relational cache implementations - internally. + [`hikari.channels.GuildThreadChannel`][], and + [`hikari.voices.VoiceState`][]. + + This is provided in several components to allow separate caching and linking + between entities in various relational cache implementations internally. """ ###################### @@ -1256,8 +1261,8 @@ def deserialize_slash_command( payload The JSON payload to deserialize. guild_id - The ID of the guild this command belongs to. If this is specified - then this will be prioritised over `"guild_id"` in the payload. + The ID of the guild this command belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. Returns ------- @@ -1268,8 +1273,7 @@ def deserialize_slash_command( ------ KeyError If `guild_id` is left as [`hikari.undefined.UNDEFINED`][] when - `"guild_id"` is not present in the passed payload for the payload of - the integration. + `"guild_id"` is not present in the passed payload. """ @abc.abstractmethod @@ -1286,8 +1290,8 @@ def deserialize_context_menu_command( payload The JSON payload to deserialize. guild_id - The ID of the guild this command belongs to. If this is specified - then this will be prioritised over `"guild_id"` in the payload. + The ID of the guild this command belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. Returns ------- @@ -1298,8 +1302,7 @@ def deserialize_context_menu_command( ------ KeyError If `guild_id` is left as [`hikari.undefined.UNDEFINED`][] when - `"guild_id"` is not present in the passed payload for the payload of - the integration. + `"guild_id"` is not present in the passed payload. """ @abc.abstractmethod @@ -1316,8 +1319,8 @@ def deserialize_command( payload The JSON payload to deserialize. guild_id - The ID of the guild this command belongs to. If this is specified - then this will be prioritised over `"guild_id"` in the payload. + The ID of the guild this command belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. Returns ------- @@ -1328,8 +1331,7 @@ def deserialize_command( ------ KeyError If `guild_id` is left as [`hikari.undefined.UNDEFINED`][] when - `"guild_id"` is not present in the passed payload for the payload of - the integration. + `"guild_id"` is not present in the passed payload. hikari.errors.UnrecognisedEntityError If the command type is unknown. """ @@ -1338,7 +1340,7 @@ def deserialize_command( def deserialize_guild_command_permissions( self, payload: data_binding.JSONObject ) -> commands.GuildCommandPermissions: - """Parse a raw payload from Discord into guild command permissions object. + """Parse a raw payload from Discord into a guild command permissions object. Parameters ---------- @@ -1353,7 +1355,7 @@ def deserialize_guild_command_permissions( @abc.abstractmethod def serialize_command_permission(self, permission: commands.CommandPermission) -> data_binding.JSONObject: - """Serialize a command permission object to a json serializable dict. + """Serialize a command permission object into a JSON serializable dict. Parameters ---------- @@ -1441,7 +1443,7 @@ def deserialize_interaction(self, payload: data_binding.JSONObject) -> base_inte @abc.abstractmethod def serialize_command_option(self, option: commands.CommandOption) -> data_binding.JSONObject: - """Serialize a command option object to a json serializable dict. + """Serialize a command option object into a JSON serializable dict. Parameters ---------- @@ -1507,7 +1509,7 @@ def deserialize_invite(self, payload: data_binding.JSONObject) -> invite_models. @abc.abstractmethod def deserialize_invite_with_metadata(self, payload: data_binding.JSONObject) -> invite_models.InviteWithMetadata: - """Parse a raw payload from Discord into a invite with metadata object. + """Parse a raw payload from Discord into an invite with metadata object. Parameters ---------- @@ -1631,19 +1633,17 @@ def deserialize_member_presence( ) -> presence_models.MemberPresence: """Parse a raw payload from Discord into a member presence object. - !!! note - At the time of writing, the only place where `guild_id` will be - mandatory is when parsing presences sent in a `GUILD_CREATE` event - from Discord, since the `guild_id` attribute in the payload will - have been omitted for redundancy. - Parameters ---------- payload The JSON payload to deserialize. guild_id The ID of the guild the presence belongs to. If this is specified - then it is prioritised over `guild_id` in the payload. + then it is prioritized over `guild_id` in the payload. + + !!! note + This currently only covers the gateway `GUILD_CREATE` event, + where `"guild_id"` is not included in the presence's payload. Returns ------- @@ -1746,8 +1746,8 @@ def deserialize_scheduled_event_user( payload The JSON payload to deserialize. guild_id - The ID of the guild the user belongs to. If this is specified - then it is prioritised over `guild_id` in the payload. + The ID of the guild the user belongs to. + This will be prioritized over `guild_id` in the payload when passed. Returns ------- @@ -1822,23 +1822,25 @@ def deserialize_voice_state( ) -> voice_models.VoiceState: """Parse a raw payload from Discord into a voice state object. - !!! note - At the time of writing, `GUILD_CREATE` events are the only known - place where neither `guild_id` nor `member` will be keys on the - payload. In this case, you will need to provide the former - parameters explicitly. - Parameters ---------- payload The JSON payload to deserialize. guild_id - The ID of the guild this voice state belongs to. If this is specified - then this will be prioritised over `"guild_id"` in the payload. + The ID of the guild this voice state belongs to. + This will be prioritized over `"guild_id"` in the payload when passed. + + !!! note + This currently only covers the gateway `GUILD_CREATE` event, + where `"guild_id"` is not included in the voice state's payload. + member - The object of the member this voice state belongs to. If this is - specified then this will be prioritised over `"member"` in the - payload. + The object of the member this voice state belongs to. + This will be prioritized over `"member"` in the payload when passed. + + !!! note + This currently only covers the gateway `GUILD_CREATE` event, + where `"member"` is not included in the voice state's payload. Returns ------- @@ -1849,11 +1851,7 @@ def deserialize_voice_state( ------ KeyError If `guild_id` is left as [`hikari.undefined.UNDEFINED`][] when - `"guild_id"` is not present in the passed payload for the payload of - the voice state. - - This will also be raised if no `member` data was passed in any - acceptable place. + `"guild_id"` is not present in the passed payload. """ @abc.abstractmethod @@ -1877,7 +1875,7 @@ def deserialize_voice_region(self, payload: data_binding.JSONObject) -> voice_mo @abc.abstractmethod def deserialize_incoming_webhook(self, payload: data_binding.JSONObject) -> webhook_models.IncomingWebhook: - """Parse a raw payload from Discord into a incoming webhook object. + """Parse a raw payload from Discord into an incoming webhook object. Parameters ---------- @@ -1982,7 +1980,7 @@ def deserialize_sku(self, payload: data_binding.JSONObject) -> entitlement_model @abc.abstractmethod def deserialize_stage_instance(self, payload: data_binding.JSONObject) -> stage_instances.StageInstance: - """Parse a raw payload from Discord into a guild stage instance object. + """Parse a raw payload from Discord into a stage instance object. Parameters ---------- @@ -1991,8 +1989,8 @@ def deserialize_stage_instance(self, payload: data_binding.JSONObject) -> stage_ Returns ------- - hikari.stage_intances.StageInstance - The deserialized stage instance object + hikari.stage_instances.StageInstance + The deserialized stage instance object. """ ############### diff --git a/hikari/api/event_factory.py b/hikari/api/event_factory.py index 87460e6543..d4fbb735bb 100644 --- a/hikari/api/event_factory.py +++ b/hikari/api/event_factory.py @@ -18,7 +18,7 @@ # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. -"""Component that provides the ability to generate event models.""" +"""Core interface for an object that deserializes event objects.""" from __future__ import annotations @@ -61,7 +61,7 @@ class EventFactory(abc.ABC): - """Interface for components that deserialize JSON events.""" + """Interface for components that deserialize JSON payloads.""" __slots__: typing.Sequence[str] = () @@ -80,12 +80,12 @@ def deserialize_application_command_permission_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.application_events.ApplicationCommandPermissionsUpdateEvent - The parsed application command permissions update event. + The deserialized application command permissions update event object. """ ################## @@ -96,19 +96,19 @@ def deserialize_application_command_permission_update_event( def deserialize_guild_channel_create_event( self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject ) -> channel_events.GuildChannelCreateEvent: - """Parse a raw payload from Discord into a channel create event object. + """Parse a raw payload from Discord into a guild channel create event object. Parameters ---------- shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.channel_events.GuildChannelCreateEvent - The parsed channel create event object. + The deserialized guild channel create event object. """ @abc.abstractmethod @@ -119,40 +119,40 @@ def deserialize_guild_channel_update_event( *, old_channel: channel_models.PermissibleGuildChannel | None = None, ) -> channel_events.GuildChannelUpdateEvent: - """Parse a raw payload from Discord into a channel update event object. + """Parse a raw payload from Discord into a guild channel update event object. Parameters ---------- shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_channel - The guild channel object or [`None`][]. + The old guild channel object or [`None`][]. Returns ------- hikari.events.channel_events.GuildChannelUpdateEvent - The parsed event object. + The deserialized guild channel update event object. """ @abc.abstractmethod def deserialize_guild_channel_delete_event( self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject ) -> channel_events.GuildChannelDeleteEvent: - """Parse a raw payload from Discord into a channel delete event object. + """Parse a raw payload from Discord into a guild channel delete event object. Parameters ---------- shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.channel_events.GuildChannelDeleteEvent - The parsed channel delete event object. + The deserialized guild channel delete event object. """ @abc.abstractmethod @@ -166,12 +166,12 @@ def deserialize_channel_pins_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.channel_events.PinsUpdateEvent - The parsed channel pins update event object. + The deserialized channel pins update event object. """ @abc.abstractmethod @@ -185,12 +185,12 @@ def deserialize_guild_thread_create_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.channel_events.GuildThreadCreateEvent - The parsed guild thread create event object. + The deserialized guild thread create event object. """ @abc.abstractmethod @@ -204,12 +204,12 @@ def deserialize_guild_thread_access_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.channel_events.GuildThreadAccessEvent - The parsed guild thread create event object. + The deserialized guild thread access event object. """ @abc.abstractmethod @@ -223,12 +223,12 @@ def deserialize_guild_thread_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.channel_events.GuildThreadUpdateEvent - The parsed guild thread update event object. + The deserialized guild thread update event object. """ @abc.abstractmethod @@ -242,12 +242,12 @@ def deserialize_guild_thread_delete_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.channel_events.GuildThreadDeleteEvent - The parsed guild thread delete event object. + The deserialized guild thread delete event object. """ @abc.abstractmethod @@ -261,12 +261,12 @@ def deserialize_thread_members_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.channel_events.ThreadMembersUpdateEvent - The parsed thread members update event object. + The deserialized thread members update event object. """ @abc.abstractmethod @@ -280,12 +280,12 @@ def deserialize_thread_list_sync_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.channel_events.ThreadListSyncEvent - The parsed thread member list sync event object. + The deserialized thread list sync event object. """ @abc.abstractmethod @@ -299,12 +299,12 @@ def deserialize_webhook_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.channel_events.WebhookUpdateEvent - The parsed webhook update event object. + The deserialized webhook update event object. """ @abc.abstractmethod @@ -318,12 +318,12 @@ def deserialize_invite_create_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.channel_events.InviteCreateEvent - The parsed invite create event object. + The deserialized invite create event object. """ @abc.abstractmethod @@ -341,14 +341,14 @@ def deserialize_invite_delete_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_invite - The invite object or [`None`][]. + The deleted invite object or [`None`][]. Returns ------- hikari.events.channel_events.InviteDeleteEvent - The parsed invite delete event object. + The deserialized invite delete event object. """ ################# @@ -366,12 +366,12 @@ def deserialize_typing_start_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.typing_events.TypingEvent - The parsed typing start event object. + The deserialized typing start event object. """ ################ @@ -389,12 +389,12 @@ def deserialize_guild_available_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.guild_events.GuildAvailableEvent - The parsed guild create event object. + The deserialized guild available event object. """ @abc.abstractmethod @@ -408,12 +408,12 @@ def deserialize_guild_join_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.guild_events.GuildJoinEvent - The parsed guild join event object. + The deserialized guild join event object. """ @abc.abstractmethod @@ -431,14 +431,14 @@ def deserialize_guild_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_guild - The guild object or [`None`][]. + The old guild object or [`None`][]. Returns ------- hikari.events.guild_events.GuildUpdateEvent - The parsed guild update event object. + The deserialized guild update event object. """ @abc.abstractmethod @@ -456,14 +456,14 @@ def deserialize_guild_leave_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_guild - The guild object or [`None`][]. + The object of the guild that was left or [`None`][]. Returns ------- hikari.events.guild_events.GuildLeaveEvent - The parsed guild leave event object. + The deserialized guild leave event object. """ @abc.abstractmethod @@ -477,12 +477,12 @@ def deserialize_guild_unavailable_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.guild_events.GuildUnavailableEvent - The parsed guild unavailable event object. + The deserialized guild unavailable event object. """ @abc.abstractmethod @@ -496,12 +496,12 @@ def deserialize_guild_ban_add_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.guild_events.BanCreateEvent - The parsed guild ban add event object. + The deserialized guild ban add event object. """ @abc.abstractmethod @@ -515,12 +515,12 @@ def deserialize_guild_ban_remove_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.guild_events.BanDeleteEvent - The parsed guild ban remove event object. + The deserialized guild ban remove event object. """ @abc.abstractmethod @@ -538,14 +538,14 @@ def deserialize_guild_emojis_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_emojis - The sequence of emojis or [`None`][]. + The sequence of old emojis or [`None`][]. Returns ------- hikari.events.guild_events.EmojisUpdateEvent - The parsed guild emojis update event object. + The deserialized guild emojis update event object. """ @abc.abstractmethod @@ -563,14 +563,14 @@ def deserialize_guild_stickers_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_stickers - The sequence of stickers or [`None`][]. + The sequence of old stickers or [`None`][]. Returns ------- hikari.events.guild_events.StickersUpdateEvent - The parsed guild stickers update event object. + The deserialized guild stickers update event object. """ @abc.abstractmethod @@ -584,12 +584,12 @@ def deserialize_integration_create_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.guild_events.IntegrationCreateEvent - The parsed integration create event object. + The deserialized integration create event object. """ @abc.abstractmethod @@ -603,12 +603,12 @@ def deserialize_integration_delete_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.guild_events.IntegrationDeleteEvent - The parsed integration delete event object. + The deserialized integration delete event object. """ @abc.abstractmethod @@ -622,12 +622,12 @@ def deserialize_integration_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.guild_events.IntegrationUpdateEvent - The parsed integration update event object. + The deserialized integration update event object. """ @abc.abstractmethod @@ -645,14 +645,14 @@ def deserialize_presence_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_presence - The presence object or [`None`][]. + The old presence object or [`None`][]. Returns ------- hikari.events.guild_events.PresenceUpdateEvent - The parsed presence update event object. + The deserialized presence update event object. """ @abc.abstractmethod @@ -666,12 +666,12 @@ def deserialize_audit_log_entry_create_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.guild_events.AuditLogEntryCreateEvent - The parsed audit log entry create object. + The deserialized audit log entry create event object. """ ###################### @@ -689,12 +689,12 @@ def deserialize_interaction_create_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.interaction_events.InteractionCreateEvent - The parsed interaction create event object. + The deserialized interaction create event object. """ ################# @@ -712,12 +712,12 @@ def deserialize_guild_member_add_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.member_events.MemberCreateEvent - The parsed guild member add event object. + The deserialized guild member add event object. """ @abc.abstractmethod @@ -735,14 +735,14 @@ def deserialize_guild_member_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_member - The member object or [`None`][]. + The old member object or [`None`][]. Returns ------- hikari.events.member_events.MemberUpdateEvent - The parsed guild member update event object. + The deserialized guild member update event object. """ @abc.abstractmethod @@ -760,14 +760,14 @@ def deserialize_guild_member_remove_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_member - The member object or [`None`][]. + The removed member object or [`None`][]. Returns ------- hikari.events.member_events.MemberDeleteEvent - The parsed guild member remove event object. + The deserialized guild member remove event object. """ ############### @@ -785,12 +785,12 @@ def deserialize_guild_role_create_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.role_events.RoleCreateEvent - The parsed guild role create event object. + The deserialized guild role create event object. """ @abc.abstractmethod @@ -808,14 +808,14 @@ def deserialize_guild_role_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_role - The role object or [`None`][]. + The old role object or [`None`][]. Returns ------- hikari.events.role_events.RoleUpdateEvent - The parsed guild role update event object. + The deserialized guild role update event object. """ @abc.abstractmethod @@ -833,14 +833,14 @@ def deserialize_guild_role_delete_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_role - The role object or [`None`][]. + The deleted role object or [`None`][]. Returns ------- hikari.events.role_events.RoleDeleteEvent - The parsed guild role delete event object. + The deserialized guild role delete event object. """ ########################## @@ -858,12 +858,12 @@ def deserialize_scheduled_event_create_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.scheduled_events.ScheduledEventCreateEvent - The parsed scheduled event create event object. + The deserialized scheduled event create event object. """ @abc.abstractmethod @@ -877,12 +877,12 @@ def deserialize_scheduled_event_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.scheduled_events.ScheduledEventUpdateEvent - The parsed scheduled event update event object. + The deserialized scheduled event update event object. """ @abc.abstractmethod @@ -896,12 +896,12 @@ def deserialize_scheduled_event_delete_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.scheduled_events.ScheduledEventDeleteEvent - The parsed scheduled event delete event object. + The deserialized scheduled event delete event object. """ @abc.abstractmethod @@ -915,12 +915,12 @@ def deserialize_scheduled_event_user_add_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.scheduled_events.ScheduledEventUserAddEvent - The parsed scheduled event user add event object. + The deserialized scheduled event user add event object. """ @abc.abstractmethod @@ -934,12 +934,12 @@ def deserialize_scheduled_event_user_remove_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.scheduled_events.ScheduledEventUserRemoveEvent - The parsed scheduled event user remove event object. + The deserialized scheduled event user remove event object. """ ################### @@ -962,18 +962,18 @@ def deserialize_started_event(self) -> lifetime_events.StartedEvent: Returns ------- - hikari.events.lifetime_events.StartingEvent + hikari.events.lifetime_events.StartedEvent The built started event object. """ @abc.abstractmethod def deserialize_stopping_event(self) -> lifetime_events.StoppingEvent: - """Build a starting event object. + """Build a stopping event object. Returns ------- - hikari.events.lifetime_events.StartingEvent - The built starting event object. + hikari.events.lifetime_events.StoppingEvent + The built stopping event object. """ @abc.abstractmethod @@ -982,8 +982,8 @@ def deserialize_stopped_event(self) -> lifetime_events.StoppedEvent: Returns ------- - hikari.events.lifetime_events.StartingEvent - The built starting event object. + hikari.events.lifetime_events.StoppedEvent + The built stopped event object. """ ################## @@ -1001,12 +1001,12 @@ def deserialize_message_create_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.message_events.MessageCreateEvent - The parsed message create event object. + The deserialized message create event object. """ @abc.abstractmethod @@ -1024,14 +1024,14 @@ def deserialize_message_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_message - The message object or [`None`][]. + The old message object or [`None`][]. Returns ------- hikari.events.message_events.MessageUpdateEvent - The parsed message update event object. + The deserialized message update event object. """ @abc.abstractmethod @@ -1049,14 +1049,14 @@ def deserialize_message_delete_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_message - The old message object. + The deleted message object or [`None`][]. Returns ------- hikari.events.message_events.MessageDeleteEvent - The parsed message delete event object. + The deserialized message delete event object. """ @abc.abstractmethod @@ -1074,14 +1074,14 @@ def deserialize_guild_message_delete_bulk_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_messages - A mapping of the old message objects. + A mapping of the deleted message IDs to objects. Returns ------- hikari.events.message_events.GuildBulkMessageDeleteEvent - The parsed guild message delete bulk event object. + The deserialized guild message delete bulk event object. """ ################### @@ -1099,12 +1099,12 @@ def deserialize_message_reaction_add_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.reaction_events.ReactionAddEvent - The parsed message reaction add event object. + The deserialized message reaction add event object. """ @abc.abstractmethod @@ -1118,12 +1118,12 @@ def deserialize_message_reaction_remove_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.reaction_events.ReactionDeleteEvent - The parsed message reaction remove event object. + The deserialized message reaction remove event object. """ @abc.abstractmethod @@ -1137,12 +1137,12 @@ def deserialize_message_reaction_remove_all_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.reaction_events.ReactionDeleteAllEvent - The parsed message reaction remove all event object. + The deserialized message reaction remove all event object. """ @abc.abstractmethod @@ -1156,12 +1156,12 @@ def deserialize_message_reaction_remove_emoji_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.reaction_events.ReactionDeleteEmojiEvent - The parsed message reaction remove emoji event object. + The deserialized message reaction remove emoji event object. """ ################ @@ -1179,14 +1179,14 @@ def deserialize_shard_payload_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. name Name of the event. Returns ------- hikari.events.shard_events.ShardPayloadEvent - The parsed shard payload event object. + The deserialized shard payload event object. """ @abc.abstractmethod @@ -1200,12 +1200,12 @@ def deserialize_ready_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.shard_events.ShardReadyEvent - The parsed ready event object. + The deserialized ready event object. """ @abc.abstractmethod @@ -1219,7 +1219,7 @@ def deserialize_connected_event(self, shard: gateway_shard.GatewayShard) -> shar Returns ------- - hikari.events.shard_events.ShardReadyEvent + hikari.events.shard_events.ShardConnectedEvent The built shard connected event object. """ @@ -1234,7 +1234,7 @@ def deserialize_disconnected_event(self, shard: gateway_shard.GatewayShard) -> s Returns ------- - hikari.events.shard_events.ShardReadyEvent + hikari.events.shard_events.ShardDisconnectedEvent The built shard disconnected event object. """ @@ -1249,7 +1249,7 @@ def deserialize_resumed_event(self, shard: gateway_shard.GatewayShard) -> shard_ Returns ------- - hikari.events.shard_events.ShardReadyEvent + hikari.events.shard_events.ShardResumedEvent The built shard resumed event object. """ @@ -1264,12 +1264,12 @@ def deserialize_guild_member_chunk_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.shard_events.MemberChunkEvent - The parsed member chunk object. + The deserialized member chunk event object. """ ############### @@ -1284,21 +1284,21 @@ def deserialize_own_user_update_event( *, old_user: user_models.OwnUser | None = None, ) -> user_events.OwnUserUpdateEvent: - """Parse a raw payload from Discord into a own user update event object. + """Parse a raw payload from Discord into an own user update event object. Parameters ---------- shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_user - The OwnUser object or [`None`][]. + The old own user object or [`None`][]. Returns ------- hikari.events.user_events.OwnUserUpdateEvent - The parsed own user update event object. + The deserialized own user update event object. """ ################ @@ -1320,14 +1320,14 @@ def deserialize_voice_state_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. old_state - The VoiceState object or [`None`][]. + The old voice state object or [`None`][]. Returns ------- hikari.events.voice_events.VoiceStateUpdateEvent - The parsed voice state update event object. + The deserialized voice state update event object. """ @abc.abstractmethod @@ -1341,12 +1341,12 @@ def deserialize_voice_server_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.voice_events.VoiceServerUpdateEvent - The parsed voice server update event object. + The deserialized voice server update event object. """ @abc.abstractmethod @@ -1360,12 +1360,12 @@ def deserialize_auto_mod_rule_create_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.voice_events.AutoModRuleCreateEvent - The parsed auto-mod rule create event object. + The deserialized auto-mod rule create event object. """ @abc.abstractmethod @@ -1379,12 +1379,12 @@ def deserialize_auto_mod_rule_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.voice_events.AutoModRuleUpdateEvent - The parsed auto-mod rule update event object. + The deserialized auto-mod rule update event object. """ @abc.abstractmethod @@ -1398,12 +1398,12 @@ def deserialize_auto_mod_rule_delete_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.voice_events.AutoModRuleDeleteEvent - The parsed auto-mod rule delete event object. + The deserialized auto-mod rule delete event object. """ @abc.abstractmethod @@ -1417,12 +1417,12 @@ def deserialize_auto_mod_action_execution_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.voice_events.AutoModActionExecutionEvent - The parsed auto-mod action execution event object. + The deserialized auto-mod action execution event object. """ ################## @@ -1440,12 +1440,12 @@ def deserialize_entitlement_create_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.entitlement_events.EntitlementCreateEvent - The parsed entitlement create event object. + The deserialized entitlement create event object. """ @abc.abstractmethod @@ -1459,12 +1459,12 @@ def deserialize_entitlement_delete_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.entitlement_events.EntitlementDeleteEvent - The parsed entitlement delete event object. + The deserialized entitlement delete event object. """ @abc.abstractmethod @@ -1478,12 +1478,12 @@ def deserialize_entitlement_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.entitlement_events.EntitlementUpdateEvent - The parsed entitlement update event object. + The deserialized entitlement update event object. """ ######################### @@ -1501,12 +1501,12 @@ def deserialize_stage_instance_create_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.stage_events.StageInstanceCreateEvent - The parsed stage instance create event object. + The deserialized stage instance create event object. """ @abc.abstractmethod @@ -1520,12 +1520,12 @@ def deserialize_stage_instance_update_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.stage_events.StageInstanceUpdateEvent - The parsed stage instance update event object. + The deserialized stage instance update event object. """ @abc.abstractmethod @@ -1539,12 +1539,12 @@ def deserialize_stage_instance_delete_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.stage_events.StageInstanceDeleteEvent - The parsed stage instance delete event object. + The deserialized stage instance delete event object. """ ################ @@ -1562,12 +1562,12 @@ def deserialize_poll_vote_create_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.poll_events.PollVoteCreateEvent - The parsed poll vote create event object. + The deserialized poll vote create event object. """ @abc.abstractmethod @@ -1581,10 +1581,10 @@ def deserialize_poll_vote_delete_event( shard The shard that emitted this event. payload - The dict payload to parse. + The JSON payload to deserialize. Returns ------- hikari.events.poll_events.PollVoteDeleteEvent - The parsed poll vote delete event object. + The deserialized poll vote delete event object. """ diff --git a/hikari/api/event_manager.py b/hikari/api/event_manager.py index 302cfd3187..48d0ef8a6f 100644 --- a/hikari/api/event_manager.py +++ b/hikari/api/event_manager.py @@ -61,12 +61,12 @@ class EventStream(iterators.LazyIterator[base_events.EventT], abc.ABC): ```py with EventStream(app, EventType, timeout=50) as stream: - async for entry in stream: + async for event in stream: ... ``` - A streamer may also be directly started and closed using the [`hikari.api.event_manager.EventStream.close`][] - and [`hikari.api.event_manager.EventStream.open`][]. Note that if you don't call + A streamer may also be directly started and closed using the [`hikari.api.event_manager.EventStream.open`][] + and [`hikari.api.event_manager.EventStream.close`][]. Note that if you don't call [`hikari.api.event_manager.EventStream.close`][] after opening a streamer when you're finished with it then it may queue events in memory indefinitely. @@ -81,7 +81,7 @@ class EventStream(iterators.LazyIterator[base_events.EventT], abc.ABC): See Also -------- - LazyIterator : [`hikari.iterators.LazyIterator`][]. + [`hikari.iterators.LazyIterator`][] """ __slots__: typing.Sequence[str] = () @@ -93,7 +93,7 @@ def close(self) -> None: If called on an already closed streamer then this will do nothing. !!! note - `with streamer` may be used as a short-cut for opening and + `with streamer` may be used as a shortcut for opening and closing a streamer. """ @@ -104,8 +104,8 @@ def open(self) -> None: If called on an already started streamer then this will do nothing. !!! note - `with streamer` may be used as a short-cut for opening and - closing a stream. + `with streamer` may be used as a shortcut for opening and + closing a streamer. """ @abc.abstractmethod @@ -193,6 +193,14 @@ def dispatch(self, event: base_events.Event) -> asyncio.Future[typing.Any]: event The event to dispatch. + Returns + ------- + asyncio.Future[typing.Any] + A future that can be optionally awaited. If awaited, the future + will complete once all corresponding event listeners have been + invoked. If not awaited, this will schedule the dispatch of the + events in the background for later. + Examples -------- We can dispatch custom events by first defining a class that @@ -232,7 +240,7 @@ class EveryoneMentionedEvent(Event): @bot.listen(MessageCreateEvent) async def on_message(event): - if "@everyone" in event.content or "@here" in event.content: + if event.content is not None and "@everyone" in event.content or "@here" in event.content: event = EveryoneMentionedEvent( author=event.author, content=event.content, @@ -252,21 +260,13 @@ async def on_everyone_mentioned(event): print(event.user, "just pinged everyone in", event.channel_id) ``` - Returns - ------- - asyncio.Future[typing.Any] - A future that can be optionally awaited. If awaited, the future - will complete once all corresponding event listeners have been - invoked. If not awaited, this will schedule the dispatch of the - events in the background for later. - See Also -------- - Listen : [`hikari.api.event_manager.EventManager.listen`][]. - Stream : [`hikari.api.event_manager.EventManager.stream`][]. - Subscribe : [`hikari.api.event_manager.EventManager.subscribe`][]. - Unsubscribe : [`hikari.api.event_manager.EventManager.unsubscribe`][]. - Wait_for: [`hikari.api.event_manager.EventManager.wait_for`][]. + [`EventManager.listen`][hikari.api.event_manager.EventManager.listen], + [`EventManager.stream`][hikari.api.event_manager.EventManager.stream], + [`EventManager.subscribe`][hikari.api.event_manager.EventManager.subscribe], + [`EventManager.unsubscribe`][hikari.api.event_manager.EventManager.unsubscribe], + [`EventManager.wait_for`][hikari.api.event_manager.EventManager.wait_for]. """ # Yes, this is not generic. The reason for this is MyPy complains about @@ -294,7 +294,7 @@ def subscribe(self, event_type: type[typing.Any], callback: CallbackT[typing.Any events. ```py - from hikari.events.messages import MessageCreateEvent + from hikari.events.message_events import MessageCreateEvent async def on_message(event): ... @@ -305,11 +305,11 @@ async def on_message(event): ... See Also -------- - Dispatch : [`hikari.api.event_manager.EventManager.dispatch`][]. - Listen : [`hikari.api.event_manager.EventManager.listen`][]. - Stream : [`hikari.api.event_manager.EventManager.stream`][]. - Unsubscribe : [`hikari.api.event_manager.EventManager.unsubscribe`][]. - Wait_for : [`hikari.api.event_manager.EventManager.wait_for`][]. + [`EventManager.dispatch`][hikari.api.event_manager.EventManager.dispatch], + [`EventManager.listen`][hikari.api.event_manager.EventManager.listen], + [`EventManager.stream`][hikari.api.event_manager.EventManager.stream], + [`EventManager.unsubscribe`][hikari.api.event_manager.EventManager.unsubscribe], + [`EventManager.wait_for`][hikari.api.event_manager.EventManager.wait_for]. """ # Yes, this is not generic. The reason for this is MyPy complains about @@ -325,7 +325,7 @@ def unsubscribe(self, event_type: type[typing.Any], callback: CallbackT[typing.A event_type The event type to unsubscribe from. This must be the same exact type as was originally subscribed with to be removed correctly. - `T` must derive from [`hikari.events.base_events.Event`][]. + `T` must be a subclass of [`hikari.events.base_events.Event`][]. callback The callback to unsubscribe. @@ -335,7 +335,7 @@ def unsubscribe(self, event_type: type[typing.Any], callback: CallbackT[typing.A creation event. ```py - from hikari.events.messages import MessageCreateEvent + from hikari.events.message_events import MessageCreateEvent async def on_message(event): ... @@ -346,11 +346,11 @@ async def on_message(event): ... See Also -------- - Dispatch : [`hikari.api.event_manager.EventManager.dispatch`][]. - Listen : [`hikari.api.event_manager.EventManager.listen`][]. - Stream : [`hikari.api.event_manager.EventManager.stream`][]. - Subscribe : [`hikari.api.event_manager.EventManager.subscribe`][]. - Wait_for : [`hikari.api.event_manager.EventManager.wait_for`][]. + [`EventManager.dispatch`][hikari.api.event_manager.EventManager.dispatch], + [`EventManager.listen`][hikari.api.event_manager.EventManager.listen], + [`EventManager.stream`][hikari.api.event_manager.EventManager.stream], + [`EventManager.subscribe`][hikari.api.event_manager.EventManager.subscribe], + [`EventManager.wait_for`][hikari.api.event_manager.EventManager.wait_for]. """ @abc.abstractmethod @@ -402,11 +402,11 @@ def listen( See Also -------- - Dispatch : [`hikari.api.event_manager.EventManager.dispatch`][]. - Stream : [`hikari.api.event_manager.EventManager.stream`][]. - Subscribe : [`hikari.api.event_manager.EventManager.subscribe`][]. - Unsubscribe : [`hikari.api.event_manager.EventManager.unsubscribe`][]. - Wait_for : [`hikari.api.event_manager.EventManager.wait_for`][]. + [`EventManager.dispatch`][hikari.api.event_manager.EventManager.dispatch], + [`EventManager.stream`][hikari.api.event_manager.EventManager.stream], + [`EventManager.subscribe`][hikari.api.event_manager.EventManager.subscribe], + [`EventManager.unsubscribe`][hikari.api.event_manager.EventManager.unsubscribe], + [`EventManager.wait_for`][hikari.api.event_manager.EventManager.wait_for]. """ @abc.abstractmethod @@ -423,22 +423,22 @@ def stream( Parameters ---------- event_type - The event type to listen for. This will listen for subclasses of - this type additionally. + The event type to listen for. This will also listen for subclasses of + this type. timeout How long this streamer should wait for the next event before ending the iteration. If [`None`][] then this will continue until explicitly broken from. limit The limit for how many events this should queue at one time before - dropping extra incoming events, leave this as [`None`][] for + dropping extra incoming events. Leave this as [`None`][] for the cache size to be unlimited. Returns ------- EventStream[hikari.events.base_events.Event] The async iterator to handle streamed events. This must be started - with `with stream:` or [`stream.open`][hikari.api.event_manager.EventStream.open] + with `with stream` or [`stream.open`][hikari.api.event_manager.EventStream.open] before asynchronously iterating over it. Examples @@ -465,11 +465,11 @@ def stream( See Also -------- - Dispatch : [`hikari.api.event_manager.EventManager.dispatch`][]. - Listen : [`hikari.api.event_manager.EventManager.listen`][]. - Subscribe : [`hikari.api.event_manager.EventManager.subscribe`][]. - Unsubscribe : [`hikari.api.event_manager.EventManager.unsubscribe`][]. - Wait_for : [`hikari.api.event_manager.EventManager.wait_for`][]. + [`EventManager.dispatch`][hikari.api.event_manager.EventManager.dispatch], + [`EventManager.listen`][hikari.api.event_manager.EventManager.listen], + [`EventManager.subscribe`][hikari.api.event_manager.EventManager.subscribe], + [`EventManager.unsubscribe`][hikari.api.event_manager.EventManager.unsubscribe], + [`EventManager.wait_for`][hikari.api.event_manager.EventManager.wait_for]. """ @abc.abstractmethod @@ -482,20 +482,20 @@ async def wait_for( ) -> base_events.EventT: """Wait for a given event to occur once, then return the event. - !!! warning - Async predicates are not supported. - Parameters ---------- event_type - The event type to listen for. This will listen for subclasses of - this type additionally. + The event type to listen for. This will also listen for subclasses of + this type. predicate A function taking the event as the single parameter. This should return [`True`][] if the event is one you want to return, or [`False`][] if the event should not be returned. If left as [`None`][] (the default), then the first matching event type that the bot receives (or any subtype) will be the one returned. + + !!! warning + Async predicates are not supported. timeout The amount of time to wait before raising an [`asyncio.TimeoutError`][] and giving up instead. This is measured in seconds. If @@ -516,9 +516,9 @@ async def wait_for( See Also -------- - Dispatch : [`hikari.api.event_manager.EventManager.dispatch`][]. - Listen : [`hikari.api.event_manager.EventManager.listen`][]. - Stream : [`hikari.api.event_manager.EventManager.stream`][]. - Subscribe : [`hikari.api.event_manager.EventManager.subscribe`][]. - Unsubscribe : [`hikari.api.event_manager.EventManager.unsubscribe`][]. + [`EventManager.dispatch`][hikari.api.event_manager.EventManager.dispatch], + [`EventManager.listen`][hikari.api.event_manager.EventManager.listen], + [`EventManager.stream`][hikari.api.event_manager.EventManager.stream], + [`EventManager.subscribe`][hikari.api.event_manager.EventManager.subscribe], + [`EventManager.unsubscribe`][hikari.api.event_manager.EventManager.unsubscribe]. """