From eca1d9a470fc888a07b34230dad0221b65bb4d29 Mon Sep 17 00:00:00 2001 From: Chiggy-Playz <49774426+Chiggy-Playz@users.noreply.github.com> Date: Thu, 7 Oct 2021 21:18:38 +0530 Subject: [PATCH] Sort events by categories (#88) --- docs/api.rst | 1274 ++++++++++++++++++++++++++------------------------ 1 file changed, 662 insertions(+), 612 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 5fc56af1..e513eb0a 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -197,74 +197,528 @@ to handle it, which defaults to print a traceback and ignoring the exception. errors. In order to turn a function into a coroutine they must be ``async def`` functions. -.. function:: on_connect() +Channels +~~~~~~~~~ - Called when the client has successfully connected to Discord. This is not - the same as the client being fully prepared, see :func:`on_ready` for that. +.. function:: on_guild_channel_delete(channel) + on_guild_channel_create(channel) - The warnings on :func:`on_ready` also apply. + Called whenever a guild channel is deleted or created. -.. function:: on_shard_connect(shard_id) + Note that you can get the guild from :attr:`~abc.GuildChannel.guild`. - Similar to :func:`on_connect` except used by :class:`AutoShardedClient` - to denote when a particular shard ID has connected to Discord. + This requires :attr:`Intents.guilds` to be enabled. + + :param channel: The guild channel that got created or deleted. + :type channel: :class:`abc.GuildChannel` + +.. function:: on_guild_channel_update(before, after) + + Called whenever a guild channel is updated. e.g. changed name, topic, permissions. + + This requires :attr:`Intents.guilds` to be enabled. + + :param before: The updated guild channel's old info. + :type before: :class:`abc.GuildChannel` + :param after: The updated guild channel's new info. + :type after: :class:`abc.GuildChannel` + +.. function:: on_group_join(channel, user) + on_group_remove(channel, user) + + Called when someone joins or leaves a :class:`GroupChannel`. + + :param channel: The group that the user joined or left. + :type channel: :class:`GroupChannel` + :param user: The user that joined or left. + :type user: :class:`User` + +.. function:: on_private_channel_update(before, after) + + Called whenever a private group DM is updated. e.g. changed name or topic. + + This requires :attr:`Intents.messages` to be enabled. + + :param before: The updated group channel's old info. + :type before: :class:`GroupChannel` + :param after: The updated group channel's new info. + :type after: :class:`GroupChannel` + +.. function:: on_guild_channel_pins_update(channel, last_pin) + + Called whenever a message is pinned or unpinned from a guild channel. + + This requires :attr:`Intents.guilds` to be enabled. + + :param channel: The guild channel that had its pins updated. + :type channel: Union[:class:`abc.GuildChannel`, :class:`Thread`] + :param last_pin: The latest message that was pinned as an aware datetime in UTC. Could be ``None``. + :type last_pin: Optional[:class:`datetime.datetime`] + +.. function:: on_private_channel_pins_update(channel, last_pin) + + Called whenever a message is pinned or unpinned from a private channel. + + :param channel: The private channel that had its pins updated. + :type channel: :class:`abc.PrivateChannel` + :param last_pin: The latest message that was pinned as an aware datetime in UTC. Could be ``None``. + :type last_pin: Optional[:class:`datetime.datetime`] + +.. function:: on_typing(channel, user, when) + + Called when someone begins typing a message. + + The ``channel`` parameter can be a :class:`abc.Messageable` instance. + Which could either be :class:`TextChannel`, :class:`GroupChannel`, or + :class:`DMChannel`. + + If the ``channel`` is a :class:`TextChannel` then the ``user`` parameter + is a :class:`Member`, otherwise it is a :class:`User`. + + This requires :attr:`Intents.typing` to be enabled. + + :param channel: The location where the typing originated from. + :type channel: :class:`abc.Messageable` + :param user: The user that started typing. + :type user: Union[:class:`User`, :class:`Member`] + :param when: When the typing started as an aware datetime in UTC. + :type when: :class:`datetime.datetime` + +.. function:: on_raw_typing(payload) + + Called when someone begins typing a message. Unlike :func:`on_typing`, this is + called regardless if the user can be found or not. This most often happens + when a user types in DMs. + + This requires :attr:`Intents.typing` to be enabled. + + :param payload: The raw typing payload. + :type payload: :class:`RawTypingEvent` + +Guilds +~~~~~~~ + +.. function:: on_guild_available(guild) + on_guild_unavailable(guild) + + Called when a guild becomes available or unavailable. The guild must have + existed in the :attr:`Client.guilds` cache. + + This requires :attr:`Intents.guilds` to be enabled. + + :param guild: The :class:`Guild` that has changed availability. + +.. function:: on_guild_join(guild) + + Called when a :class:`Guild` is either created by the :class:`Client` or when the + :class:`Client` joins a guild. + + This requires :attr:`Intents.guilds` to be enabled. + + :param guild: The guild that was joined. + :type guild: :class:`Guild` + +.. function:: on_guild_remove(guild) + + Called when a :class:`Guild` is removed from the :class:`Client`. + + This happens through, but not limited to, these circumstances: + + - The client got banned. + - The client got kicked. + - The client left the guild. + - The client or the guild owner deleted the guild. + + In order for this event to be invoked then the :class:`Client` must have + been part of the guild to begin with. (i.e. it is part of :attr:`Client.guilds`) + + This requires :attr:`Intents.guilds` to be enabled. + + :param guild: The guild that got removed. + :type guild: :class:`Guild` + +.. function:: on_guild_update(before, after) + + Called when a :class:`Guild` updates, for example: + + - Changed name + - Changed AFK channel + - Changed AFK timeout + - etc + + This requires :attr:`Intents.guilds` to be enabled. + + :param before: The guild prior to being updated. + :type before: :class:`Guild` + :param after: The guild after being updated. + :type after: :class:`Guild` + +.. function:: on_guild_emojis_update(guild, before, after) + + Called when a :class:`Guild` adds or removes :class:`Emoji`. + + This requires :attr:`Intents.emojis_and_stickers` to be enabled. + + :param guild: The guild who got their emojis updated. + :type guild: :class:`Guild` + :param before: A list of emojis before the update. + :type before: Sequence[:class:`Emoji`] + :param after: A list of emojis after the update. + :type after: Sequence[:class:`Emoji`] + +.. function:: on_guild_stickers_update(guild, before, after) + + Called when a :class:`Guild` updates its stickers. + + This requires :attr:`Intents.emojis_and_stickers` to be enabled. + + .. versionadded:: 2.0 + + :param guild: The guild who got their stickers updated. + :type guild: :class:`Guild` + :param before: A list of stickers before the update. + :type before: Sequence[:class:`GuildSticker`] + :param after: A list of stickers after the update. + :type after: Sequence[:class:`GuildSticker`] + + .. function:: on_invite_create(invite) + + Called when an :class:`Invite` is created. + You must have the :attr:`~Permissions.manage_channels` permission to receive this. + + .. versionadded:: 1.3 + + .. note:: + + There is a rare possibility that the :attr:`Invite.guild` and :attr:`Invite.channel` + attributes will be of :class:`Object` rather than the respective models. + + This requires :attr:`Intents.invites` to be enabled. + + :param invite: The invite that was created. + :type invite: :class:`Invite` + +.. function:: on_invite_delete(invite) + + Called when an :class:`Invite` is deleted. + You must have the :attr:`~Permissions.manage_channels` permission to receive this. + + .. versionadded:: 1.3 + + .. note:: + + There is a rare possibility that the :attr:`Invite.guild` and :attr:`Invite.channel` + attributes will be of :class:`Object` rather than the respective models. + + Outside of those two attributes, the only other attribute guaranteed to be + filled by the Discord gateway for this event is :attr:`Invite.code`. + + This requires :attr:`Intents.invites` to be enabled. + + :param invite: The invite that was deleted. + :type invite: :class:`Invite` + + +Integrations +~~~~~~~~~~~~~ + +.. function:: on_integration_create(integration) + + Called when an integration is created. + + This requires :attr:`Intents.integrations` to be enabled. + + .. versionadded:: 2.0 + + :param integration: The integration that was created. + :type integration: :class:`Integration` + +.. function:: on_integration_update(integration) + + Called when an integration is updated. + + This requires :attr:`Intents.integrations` to be enabled. + + .. versionadded:: 2.0 + + :param integration: The integration that was created. + :type integration: :class:`Integration` + +.. function:: on_guild_integrations_update(guild) + + Called whenever an integration is created, modified, or removed from a guild. + + This requires :attr:`Intents.integrations` to be enabled. .. versionadded:: 1.4 - :param shard_id: The shard ID that has connected. - :type shard_id: :class:`int` + :param guild: The guild that had its integrations updated. + :type guild: :class:`Guild` -.. function:: on_disconnect() +.. function:: on_webhooks_update(channel) - Called when the client has disconnected from Discord, or a connection attempt to Discord has failed. - This could happen either through the internet being disconnected, explicit calls to close, - or Discord terminating the connection one way or the other. + Called whenever a webhook is created, modified, or removed from a guild channel. - This function can be called many times without a corresponding :func:`on_connect` call. + This requires :attr:`Intents.webhooks` to be enabled. -.. function:: on_shard_disconnect(shard_id) + :param channel: The channel that had its webhooks updated. + :type channel: :class:`abc.GuildChannel` - Similar to :func:`on_disconnect` except used by :class:`AutoShardedClient` - to denote when a particular shard ID has disconnected from Discord. +.. function:: on_raw_integration_delete(payload) - .. versionadded:: 1.4 + Called when an integration is deleted. - :param shard_id: The shard ID that has disconnected. - :type shard_id: :class:`int` + This requires :attr:`Intents.integrations` to be enabled. -.. function:: on_ready() + .. versionadded:: 2.0 - Called when the client is done preparing the data received from Discord. Usually after login is successful - and the :attr:`Client.guilds` and co. are filled up. + :param payload: The raw event payload data. + :type payload: :class:`RawIntegrationDeleteEvent` + +Interactions +~~~~~~~~~~~~~ + +.. function:: on_interaction(interaction) + + Called when an interaction happened. + + This currently happens due to slash command invocations or components being used. .. warning:: - This function is not guaranteed to be the first event called. - Likewise, this function is **not** guaranteed to only be called - once. This library implements reconnection logic and thus will - end up calling this event whenever a RESUME request fails. + This is a low level function that is not generally meant to be used. + If you are working with components, consider using the callbacks associated + with the :class:`~discord.ui.View` instead as it provides a nicer user experience. -.. function:: on_shard_ready(shard_id) + .. versionadded:: 2.0 - Similar to :func:`on_ready` except used by :class:`AutoShardedClient` - to denote when a particular shard ID has become ready. + :param interaction: The interaction data. + :type interaction: :class:`Interaction` - :param shard_id: The shard ID that is ready. - :type shard_id: :class:`int` -.. function:: on_resumed() - Called when the client has resumed a session. +Members +~~~~~~~~ -.. function:: on_shard_resumed(shard_id) +.. function:: on_member_join(member) + on_member_remove(member) - Similar to :func:`on_resumed` except used by :class:`AutoShardedClient` - to denote when a particular shard ID has resumed a session. + Called when a :class:`Member` leaves or joins a :class:`Guild`. - .. versionadded:: 1.4 + This requires :attr:`Intents.members` to be enabled. - :param shard_id: The shard ID that has resumed. - :type shard_id: :class:`int` + :param member: The member who joined or left. + :type member: :class:`Member` + +.. function:: on_member_update(before, after) + + Called when a :class:`Member` updates their profile. + + This is called when one or more of the following things change: + + - nickname + - roles + - pending + + This requires :attr:`Intents.members` to be enabled. + + :param before: The updated member's old info. + :type before: :class:`Member` + :param after: The updated member's updated info. + :type after: :class:`Member` + +.. function:: on_user_update(before, after) + + Called when a :class:`User` updates their profile. + + This is called when one or more of the following things change: + + - avatar + - username + - discriminator + + This requires :attr:`Intents.members` to be enabled. + + :param before: The updated user's old info. + :type before: :class:`User` + :param after: The updated user's updated info. + :type after: :class:`User` + +.. function:: on_member_ban(guild, user) + + Called when user gets banned from a :class:`Guild`. + + This requires :attr:`Intents.bans` to be enabled. + + :param guild: The guild the user got banned from. + :type guild: :class:`Guild` + :param user: The user that got banned. + Can be either :class:`User` or :class:`Member` depending if + the user was in the guild or not at the time of removal. + :type user: Union[:class:`User`, :class:`Member`] + +.. function:: on_member_unban(guild, user) + + Called when a :class:`User` gets unbanned from a :class:`Guild`. + + This requires :attr:`Intents.bans` to be enabled. + + :param guild: The guild the user got unbanned from. + :type guild: :class:`Guild` + :param user: The user that got unbanned. + :type user: :class:`User` + +.. function:: on_presence_update(before, after) + + Called when a :class:`Member` updates their presence. + + This is called when one or more of the following things change: + + - status + - activity + + This requires :attr:`Intents.presences` and :attr:`Intents.members` to be enabled. + + .. versionadded:: 2.0 + + :param before: The updated member's old info. + :type before: :class:`Member` + :param after: The updated member's updated info. + :type after: :class:`Member` + +Messages +~~~~~~~~~ + +.. function:: on_message(message) + + Called when a :class:`Message` is created and sent. + + This requires :attr:`Intents.messages` to be enabled. + + .. warning:: + + Your bot's own messages and private messages are sent through this + event. This can lead cases of 'recursion' depending on how your bot was + programmed. If you want the bot to not reply to itself, consider + checking the user IDs. Note that :class:`~ext.commands.Bot` does not + have this problem. + + :param message: The current message. + :type message: :class:`Message` + +.. function:: on_message_edit(before, after) + + Called when a :class:`Message` receives an update event. If the message is not found + in the internal message cache, then these events will not be called. + Messages might not be in cache if the message is too old + or the client is participating in high traffic guilds. + + If this occurs increase the :class:`max_messages ` parameter + or use the :func:`on_raw_message_edit` event instead. + + The following non-exhaustive cases trigger this event: + + - A message has been pinned or unpinned. + - The message content has been changed. + - The message has received an embed. + + - For performance reasons, the embed server does not do this in a "consistent" manner. + + - The message's embeds were suppressed or unsuppressed. + - A call message has received an update to its participants or ending time. + + This requires :attr:`Intents.messages` to be enabled. + + :param before: The previous version of the message. + :type before: :class:`Message` + :param after: The current version of the message. + :type after: :class:`Message` + +.. function:: on_message_delete(message) + + Called when a message is deleted. If the message is not found in the + internal message cache, then this event will not be called. + Messages might not be in cache if the message is too old + or the client is participating in high traffic guilds. + + If this occurs increase the :class:`max_messages ` parameter + or use the :func:`on_raw_message_delete` event instead. + + This requires :attr:`Intents.messages` to be enabled. + + :param message: The deleted message. + :type message: :class:`Message` + +.. function:: on_bulk_message_delete(messages) + + Called when messages are bulk deleted. If none of the messages deleted + are found in the internal message cache, then this event will not be called. + If individual messages were not found in the internal message cache, + this event will still be called, but the messages not found will not be included in + the messages list. Messages might not be in cache if the message is too old + or the client is participating in high traffic guilds. + + If this occurs increase the :class:`max_messages ` parameter + or use the :func:`on_raw_bulk_message_delete` event instead. + + This requires :attr:`Intents.messages` to be enabled. + + :param messages: The messages that have been deleted. + :type messages: List[:class:`Message`] + +.. function:: on_raw_message_edit(payload) + + Called when a message is edited. Unlike :func:`on_message_edit`, this is called + regardless of the state of the internal message cache. + + If the message is found in the message cache, + it can be accessed via :attr:`RawMessageUpdateEvent.cached_message`. The cached message represents + the message before it has been edited. For example, if the content of a message is modified and + triggers the :func:`on_raw_message_edit` coroutine, the :attr:`RawMessageUpdateEvent.cached_message` + will return a :class:`Message` object that represents the message before the content was modified. + + Due to the inherently raw nature of this event, the data parameter coincides with + the raw data given by the `gateway `_. + + Since the data payload can be partial, care must be taken when accessing stuff in the dictionary. + One example of a common case of partial data is when the ``'content'`` key is inaccessible. This + denotes an "embed" only edit, which is an edit in which only the embeds are updated by the Discord + embed server. + + This requires :attr:`Intents.messages` to be enabled. + + :param payload: The raw event payload data. + :type payload: :class:`RawMessageUpdateEvent` + + +.. function:: on_raw_message_delete(payload) + + Called when a message is deleted. Unlike :func:`on_message_delete`, this is + called regardless of the message being in the internal message cache or not. + + If the message is found in the message cache, + it can be accessed via :attr:`RawMessageDeleteEvent.cached_message` + + This requires :attr:`Intents.messages` to be enabled. + + :param payload: The raw event payload data. + :type payload: :class:`RawMessageDeleteEvent` + +.. function:: on_raw_bulk_message_delete(payload) + + Called when a bulk delete is triggered. Unlike :func:`on_bulk_message_delete`, this is + called regardless of the messages being in the internal message cache or not. + + If the messages are found in the message cache, + they can be accessed via :attr:`RawBulkMessageDeleteEvent.cached_messages` + + This requires :attr:`Intents.messages` to be enabled. + + :param payload: The raw event payload data. + :type payload: :class:`RawBulkMessageDeleteEvent` + +Meta +~~~~~ .. function:: on_error(event, *args, **kwargs) @@ -298,6 +752,81 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param kwargs: The keyword arguments for the event that raised the exception. + +Networking +~~~~~~~~~~~ + +.. function:: on_connect() + + Called when the client has successfully connected to Discord. This is not + the same as the client being fully prepared, see :func:`on_ready` for that. + + The warnings on :func:`on_ready` also apply. + +.. function:: on_disconnect() + + Called when the client has disconnected from Discord, or a connection attempt to Discord has failed. + This could happen either through the internet being disconnected, explicit calls to close, + or Discord terminating the connection one way or the other. + + This function can be called many times without a corresponding :func:`on_connect` call. + +.. function:: on_ready() + + Called when the client is done preparing the data received from Discord. Usually after login is successful + and the :attr:`Client.guilds` and co. are filled up. + + .. warning:: + + This function is not guaranteed to be the first event called. + Likewise, this function is **not** guaranteed to only be called + once. This library implements reconnection logic and thus will + end up calling this event whenever a RESUME request fails. + +.. function:: on_resumed() + + Called when the client has resumed a session. + +.. function:: on_shard_connect(shard_id) + + Similar to :func:`on_connect` except used by :class:`AutoShardedClient` + to denote when a particular shard ID has connected to Discord. + + .. versionadded:: 1.4 + + :param shard_id: The shard ID that has connected. + :type shard_id: :class:`int` + + +.. function:: on_shard_disconnect(shard_id) + + Similar to :func:`on_disconnect` except used by :class:`AutoShardedClient` + to denote when a particular shard ID has disconnected from Discord. + + .. versionadded:: 1.4 + + :param shard_id: The shard ID that has disconnected. + :type shard_id: :class:`int` + +.. function:: on_shard_ready(shard_id) + + Similar to :func:`on_ready` except used by :class:`AutoShardedClient` + to denote when a particular shard ID has become ready. + + :param shard_id: The shard ID that is ready. + :type shard_id: :class:`int` + + +.. function:: on_shard_resumed(shard_id) + + Similar to :func:`on_resumed` except used by :class:`AutoShardedClient` + to denote when a particular shard ID has resumed a session. + + .. versionadded:: 1.4 + + :param shard_id: The shard ID that has resumed. + :type shard_id: :class:`int` + .. function:: on_socket_event_type(event_type) Called whenever a websocket event is received from the WebSocket. @@ -349,163 +878,8 @@ to handle it, which defaults to print a traceback and ignoring the exception. WebSocket library. It can be :class:`bytes` to denote a binary message or :class:`str` to denote a regular text message. -.. function:: on_typing(channel, user, when) - - Called when someone begins typing a message. - - The ``channel`` parameter can be a :class:`abc.Messageable` instance. - Which could either be :class:`TextChannel`, :class:`GroupChannel`, or - :class:`DMChannel`. - - If the ``channel`` is a :class:`TextChannel` then the ``user`` parameter - is a :class:`Member`, otherwise it is a :class:`User`. - - This requires :attr:`Intents.typing` to be enabled. - - :param channel: The location where the typing originated from. - :type channel: :class:`abc.Messageable` - :param user: The user that started typing. - :type user: Union[:class:`User`, :class:`Member`] - :param when: When the typing started as an aware datetime in UTC. - :type when: :class:`datetime.datetime` - -.. function:: on_raw_typing(payload) - - Called when someone begins typing a message. Unlike :func:`on_typing`, this is - called regardless if the user can be found or not. This most often happens - when a user types in DMs. - - This requires :attr:`Intents.typing` to be enabled. - - :param payload: The raw typing payload. - :type payload: :class:`RawTypingEvent` - -.. function:: on_message(message) - - Called when a :class:`Message` is created and sent. - - This requires :attr:`Intents.messages` to be enabled. - - .. warning:: - - Your bot's own messages and private messages are sent through this - event. This can lead cases of 'recursion' depending on how your bot was - programmed. If you want the bot to not reply to itself, consider - checking the user IDs. Note that :class:`~ext.commands.Bot` does not - have this problem. - - :param message: The current message. - :type message: :class:`Message` - -.. function:: on_message_delete(message) - - Called when a message is deleted. If the message is not found in the - internal message cache, then this event will not be called. - Messages might not be in cache if the message is too old - or the client is participating in high traffic guilds. - - If this occurs increase the :class:`max_messages ` parameter - or use the :func:`on_raw_message_delete` event instead. - - This requires :attr:`Intents.messages` to be enabled. - - :param message: The deleted message. - :type message: :class:`Message` - -.. function:: on_bulk_message_delete(messages) - - Called when messages are bulk deleted. If none of the messages deleted - are found in the internal message cache, then this event will not be called. - If individual messages were not found in the internal message cache, - this event will still be called, but the messages not found will not be included in - the messages list. Messages might not be in cache if the message is too old - or the client is participating in high traffic guilds. - - If this occurs increase the :class:`max_messages ` parameter - or use the :func:`on_raw_bulk_message_delete` event instead. - - This requires :attr:`Intents.messages` to be enabled. - - :param messages: The messages that have been deleted. - :type messages: List[:class:`Message`] - -.. function:: on_raw_message_delete(payload) - - Called when a message is deleted. Unlike :func:`on_message_delete`, this is - called regardless of the message being in the internal message cache or not. - - If the message is found in the message cache, - it can be accessed via :attr:`RawMessageDeleteEvent.cached_message` - - This requires :attr:`Intents.messages` to be enabled. - - :param payload: The raw event payload data. - :type payload: :class:`RawMessageDeleteEvent` - -.. function:: on_raw_bulk_message_delete(payload) - - Called when a bulk delete is triggered. Unlike :func:`on_bulk_message_delete`, this is - called regardless of the messages being in the internal message cache or not. - - If the messages are found in the message cache, - they can be accessed via :attr:`RawBulkMessageDeleteEvent.cached_messages` - - This requires :attr:`Intents.messages` to be enabled. - - :param payload: The raw event payload data. - :type payload: :class:`RawBulkMessageDeleteEvent` - -.. function:: on_message_edit(before, after) - - Called when a :class:`Message` receives an update event. If the message is not found - in the internal message cache, then these events will not be called. - Messages might not be in cache if the message is too old - or the client is participating in high traffic guilds. - - If this occurs increase the :class:`max_messages ` parameter - or use the :func:`on_raw_message_edit` event instead. - - The following non-exhaustive cases trigger this event: - - - A message has been pinned or unpinned. - - The message content has been changed. - - The message has received an embed. - - - For performance reasons, the embed server does not do this in a "consistent" manner. - - - The message's embeds were suppressed or unsuppressed. - - A call message has received an update to its participants or ending time. - - This requires :attr:`Intents.messages` to be enabled. - - :param before: The previous version of the message. - :type before: :class:`Message` - :param after: The current version of the message. - :type after: :class:`Message` - -.. function:: on_raw_message_edit(payload) - - Called when a message is edited. Unlike :func:`on_message_edit`, this is called - regardless of the state of the internal message cache. - - If the message is found in the message cache, - it can be accessed via :attr:`RawMessageUpdateEvent.cached_message`. The cached message represents - the message before it has been edited. For example, if the content of a message is modified and - triggers the :func:`on_raw_message_edit` coroutine, the :attr:`RawMessageUpdateEvent.cached_message` - will return a :class:`Message` object that represents the message before the content was modified. - - Due to the inherently raw nature of this event, the data parameter coincides with - the raw data given by the `gateway `_. - - Since the data payload can be partial, care must be taken when accessing stuff in the dictionary. - One example of a common case of partial data is when the ``'content'`` key is inaccessible. This - denotes an "embed" only edit, which is an edit in which only the embeds are updated by the Discord - embed server. - - This requires :attr:`Intents.messages` to be enabled. - - :param payload: The raw event payload data. - :type payload: :class:`RawMessageUpdateEvent` +Reactions +~~~~~~~~~~ .. function:: on_reaction_add(reaction, user) @@ -532,16 +906,6 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param user: The user who added the reaction. :type user: Union[:class:`Member`, :class:`User`] -.. function:: on_raw_reaction_add(payload) - - Called when a message has a reaction added. Unlike :func:`on_reaction_add`, this is - called regardless of the state of the internal message cache. - - This requires :attr:`Intents.reactions` to be enabled. - - :param payload: The raw event payload data. - :type payload: :class:`RawReactionActionEvent` - .. function:: on_reaction_remove(reaction, user) Called when a message has a reaction removed from it. Similar to on_message_edit, @@ -564,16 +928,6 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param user: The user who added the reaction. :type user: Union[:class:`Member`, :class:`User`] -.. function:: on_raw_reaction_remove(payload) - - Called when a message has a reaction removed. Unlike :func:`on_reaction_remove`, this is - called regardless of the state of the internal message cache. - - This requires :attr:`Intents.reactions` to be enabled. - - :param payload: The raw event payload data. - :type payload: :class:`RawReactionActionEvent` - .. function:: on_reaction_clear(message, reactions) Called when a message has all its reactions removed from it. Similar to :func:`on_message_edit`, @@ -587,16 +941,6 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param reactions: The reactions that were removed. :type reactions: List[:class:`Reaction`] -.. function:: on_raw_reaction_clear(payload) - - Called when a message has all its reactions removed. Unlike :func:`on_reaction_clear`, - this is called regardless of the state of the internal message cache. - - This requires :attr:`Intents.reactions` to be enabled. - - :param payload: The raw event payload data. - :type payload: :class:`RawReactionClearEvent` - .. function:: on_reaction_clear_emoji(reaction) Called when a message has a specific reaction removed from it. Similar to :func:`on_message_edit`, @@ -610,6 +954,37 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param reaction: The reaction that got cleared. :type reaction: :class:`Reaction` + +.. function:: on_raw_reaction_add(payload) + + Called when a message has a reaction added. Unlike :func:`on_reaction_add`, this is + called regardless of the state of the internal message cache. + + This requires :attr:`Intents.reactions` to be enabled. + + :param payload: The raw event payload data. + :type payload: :class:`RawReactionActionEvent` + +.. function:: on_raw_reaction_remove(payload) + + Called when a message has a reaction removed. Unlike :func:`on_reaction_remove`, this is + called regardless of the state of the internal message cache. + + This requires :attr:`Intents.reactions` to be enabled. + + :param payload: The raw event payload data. + :type payload: :class:`RawReactionActionEvent` + +.. function:: on_raw_reaction_clear(payload) + + Called when a message has all its reactions removed. Unlike :func:`on_reaction_clear`, + this is called regardless of the state of the internal message cache. + + This requires :attr:`Intents.reactions` to be enabled. + + :param payload: The raw event payload data. + :type payload: :class:`RawReactionClearEvent` + .. function:: on_raw_reaction_clear_emoji(payload) Called when a message has a specific reaction removed from it. Unlike :func:`on_reaction_clear_emoji` this is called @@ -622,76 +997,66 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param payload: The raw event payload data. :type payload: :class:`RawReactionClearEmojiEvent` -.. function:: on_interaction(interaction) - Called when an interaction happened. +Roles +~~~~~~ - This currently happens due to slash command invocations or components being used. +.. function:: on_guild_role_create(role) + on_guild_role_delete(role) - .. warning:: + Called when a :class:`Guild` creates or deletes a new :class:`Role`. - This is a low level function that is not generally meant to be used. - If you are working with components, consider using the callbacks associated - with the :class:`~discord.ui.View` instead as it provides a nicer user experience. + To get the guild it belongs to, use :attr:`Role.guild`. + + This requires :attr:`Intents.guilds` to be enabled. + + :param role: The role that was created or deleted. + :type role: :class:`Role` + +.. function:: on_guild_role_update(before, after) + + Called when a :class:`Role` is changed guild-wide. + + This requires :attr:`Intents.guilds` to be enabled. + + :param before: The updated role's old info. + :type before: :class:`Role` + :param after: The updated role's updated info. + :type after: :class:`Role` + + +Stages +~~~~~~~ + +.. function:: on_stage_instance_create(stage_instance) + on_stage_instance_delete(stage_instance) + + Called when a :class:`StageInstance` is created or deleted for a :class:`StageChannel`. .. versionadded:: 2.0 - :param interaction: The interaction data. - :type interaction: :class:`Interaction` + :param stage_instance: The stage instance that was created or deleted. + :type stage_instance: :class:`StageInstance` -.. function:: on_private_channel_update(before, after) +.. function:: on_stage_instance_update(before, after) - Called whenever a private group DM is updated. e.g. changed name or topic. + Called when a :class:`StageInstance` is updated. - This requires :attr:`Intents.messages` to be enabled. + The following, but not limited to, examples illustrate when this event is called: - :param before: The updated group channel's old info. - :type before: :class:`GroupChannel` - :param after: The updated group channel's new info. - :type after: :class:`GroupChannel` + - The topic is changed. + - The privacy level is changed. -.. function:: on_private_channel_pins_update(channel, last_pin) + .. versionadded:: 2.0 - Called whenever a message is pinned or unpinned from a private channel. + :param before: The stage instance before the update. + :type before: :class:`StageInstance` + :param after: The stage instance after the update. + :type after: :class:`StageInstance` - :param channel: The private channel that had its pins updated. - :type channel: :class:`abc.PrivateChannel` - :param last_pin: The latest message that was pinned as an aware datetime in UTC. Could be ``None``. - :type last_pin: Optional[:class:`datetime.datetime`] +Threads +~~~~~~~~ -.. function:: on_guild_channel_delete(channel) - on_guild_channel_create(channel) - - Called whenever a guild channel is deleted or created. - - Note that you can get the guild from :attr:`~abc.GuildChannel.guild`. - - This requires :attr:`Intents.guilds` to be enabled. - - :param channel: The guild channel that got created or deleted. - :type channel: :class:`abc.GuildChannel` - -.. function:: on_guild_channel_update(before, after) - - Called whenever a guild channel is updated. e.g. changed name, topic, permissions. - - This requires :attr:`Intents.guilds` to be enabled. - - :param before: The updated guild channel's old info. - :type before: :class:`abc.GuildChannel` - :param after: The updated guild channel's new info. - :type after: :class:`abc.GuildChannel` - -.. function:: on_guild_channel_pins_update(channel, last_pin) - - Called whenever a message is pinned or unpinned from a guild channel. - - This requires :attr:`Intents.guilds` to be enabled. - - :param channel: The guild channel that had its pins updated. - :type channel: Union[:class:`abc.GuildChannel`, :class:`Thread`] - :param last_pin: The latest message that was pinned as an aware datetime in UTC. Could be ``None``. - :type last_pin: Optional[:class:`datetime.datetime`] .. function:: on_thread_join(thread) @@ -707,6 +1072,19 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param thread: The thread that got joined. :type thread: :class:`Thread` +.. function:: on_thread_update(before, after) + + Called whenever a thread is updated. + + This requires :attr:`Intents.guilds` to be enabled. + + .. versionadded:: 2.0 + + :param before: The updated thread's old info. + :type before: :class:`Thread` + :param after: The updated thread's new info. + :type after: :class:`Thread` + .. function:: on_thread_remove(thread) Called whenever a thread is removed. This is different from a thread being deleted. @@ -754,239 +1132,8 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param member: The member who joined or left. :type member: :class:`ThreadMember` -.. function:: on_thread_update(before, after) - - Called whenever a thread is updated. - - This requires :attr:`Intents.guilds` to be enabled. - - .. versionadded:: 2.0 - - :param before: The updated thread's old info. - :type before: :class:`Thread` - :param after: The updated thread's new info. - :type after: :class:`Thread` - -.. function:: on_guild_integrations_update(guild) - - Called whenever an integration is created, modified, or removed from a guild. - - This requires :attr:`Intents.integrations` to be enabled. - - .. versionadded:: 1.4 - - :param guild: The guild that had its integrations updated. - :type guild: :class:`Guild` - -.. function:: on_integration_create(integration) - - Called when an integration is created. - - This requires :attr:`Intents.integrations` to be enabled. - - .. versionadded:: 2.0 - - :param integration: The integration that was created. - :type integration: :class:`Integration` - -.. function:: on_integration_update(integration) - - Called when an integration is updated. - - This requires :attr:`Intents.integrations` to be enabled. - - .. versionadded:: 2.0 - - :param integration: The integration that was created. - :type integration: :class:`Integration` - -.. function:: on_raw_integration_delete(payload) - - Called when an integration is deleted. - - This requires :attr:`Intents.integrations` to be enabled. - - .. versionadded:: 2.0 - - :param payload: The raw event payload data. - :type payload: :class:`RawIntegrationDeleteEvent` - -.. function:: on_webhooks_update(channel) - - Called whenever a webhook is created, modified, or removed from a guild channel. - - This requires :attr:`Intents.webhooks` to be enabled. - - :param channel: The channel that had its webhooks updated. - :type channel: :class:`abc.GuildChannel` - -.. function:: on_member_join(member) - on_member_remove(member) - - Called when a :class:`Member` leaves or joins a :class:`Guild`. - - This requires :attr:`Intents.members` to be enabled. - - :param member: The member who joined or left. - :type member: :class:`Member` - -.. function:: on_member_update(before, after) - - Called when a :class:`Member` updates their profile. - - This is called when one or more of the following things change: - - - nickname - - roles - - pending - - This requires :attr:`Intents.members` to be enabled. - - :param before: The updated member's old info. - :type before: :class:`Member` - :param after: The updated member's updated info. - :type after: :class:`Member` - -.. function:: on_presence_update(before, after) - - Called when a :class:`Member` updates their presence. - - This is called when one or more of the following things change: - - - status - - activity - - This requires :attr:`Intents.presences` and :attr:`Intents.members` to be enabled. - - .. versionadded:: 2.0 - - :param before: The updated member's old info. - :type before: :class:`Member` - :param after: The updated member's updated info. - :type after: :class:`Member` - -.. function:: on_user_update(before, after) - - Called when a :class:`User` updates their profile. - - This is called when one or more of the following things change: - - - avatar - - username - - discriminator - - This requires :attr:`Intents.members` to be enabled. - - :param before: The updated user's old info. - :type before: :class:`User` - :param after: The updated user's updated info. - :type after: :class:`User` - -.. function:: on_guild_join(guild) - - Called when a :class:`Guild` is either created by the :class:`Client` or when the - :class:`Client` joins a guild. - - This requires :attr:`Intents.guilds` to be enabled. - - :param guild: The guild that was joined. - :type guild: :class:`Guild` - -.. function:: on_guild_remove(guild) - - Called when a :class:`Guild` is removed from the :class:`Client`. - - This happens through, but not limited to, these circumstances: - - - The client got banned. - - The client got kicked. - - The client left the guild. - - The client or the guild owner deleted the guild. - - In order for this event to be invoked then the :class:`Client` must have - been part of the guild to begin with. (i.e. it is part of :attr:`Client.guilds`) - - This requires :attr:`Intents.guilds` to be enabled. - - :param guild: The guild that got removed. - :type guild: :class:`Guild` - -.. function:: on_guild_update(before, after) - - Called when a :class:`Guild` updates, for example: - - - Changed name - - Changed AFK channel - - Changed AFK timeout - - etc - - This requires :attr:`Intents.guilds` to be enabled. - - :param before: The guild prior to being updated. - :type before: :class:`Guild` - :param after: The guild after being updated. - :type after: :class:`Guild` - -.. function:: on_guild_role_create(role) - on_guild_role_delete(role) - - Called when a :class:`Guild` creates or deletes a new :class:`Role`. - - To get the guild it belongs to, use :attr:`Role.guild`. - - This requires :attr:`Intents.guilds` to be enabled. - - :param role: The role that was created or deleted. - :type role: :class:`Role` - -.. function:: on_guild_role_update(before, after) - - Called when a :class:`Role` is changed guild-wide. - - This requires :attr:`Intents.guilds` to be enabled. - - :param before: The updated role's old info. - :type before: :class:`Role` - :param after: The updated role's updated info. - :type after: :class:`Role` - -.. function:: on_guild_emojis_update(guild, before, after) - - Called when a :class:`Guild` adds or removes :class:`Emoji`. - - This requires :attr:`Intents.emojis_and_stickers` to be enabled. - - :param guild: The guild who got their emojis updated. - :type guild: :class:`Guild` - :param before: A list of emojis before the update. - :type before: Sequence[:class:`Emoji`] - :param after: A list of emojis after the update. - :type after: Sequence[:class:`Emoji`] - -.. function:: on_guild_stickers_update(guild, before, after) - - Called when a :class:`Guild` updates its stickers. - - This requires :attr:`Intents.emojis_and_stickers` to be enabled. - - .. versionadded:: 2.0 - - :param guild: The guild who got their stickers updated. - :type guild: :class:`Guild` - :param before: A list of stickers before the update. - :type before: Sequence[:class:`GuildSticker`] - :param after: A list of stickers after the update. - :type after: Sequence[:class:`GuildSticker`] - -.. function:: on_guild_available(guild) - on_guild_unavailable(guild) - - Called when a guild becomes available or unavailable. The guild must have - existed in the :attr:`Client.guilds` cache. - - This requires :attr:`Intents.guilds` to be enabled. - - :param guild: The :class:`Guild` that has changed availability. +Voice +~~~~~~ .. function:: on_voice_state_update(member, before, after) @@ -1008,103 +1155,6 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param after: The voice state after the changes. :type after: :class:`VoiceState` -.. function:: on_stage_instance_create(stage_instance) - on_stage_instance_delete(stage_instance) - - Called when a :class:`StageInstance` is created or deleted for a :class:`StageChannel`. - - .. versionadded:: 2.0 - - :param stage_instance: The stage instance that was created or deleted. - :type stage_instance: :class:`StageInstance` - -.. function:: on_stage_instance_update(before, after) - - Called when a :class:`StageInstance` is updated. - - The following, but not limited to, examples illustrate when this event is called: - - - The topic is changed. - - The privacy level is changed. - - .. versionadded:: 2.0 - - :param before: The stage instance before the update. - :type before: :class:`StageInstance` - :param after: The stage instance after the update. - :type after: :class:`StageInstance` - -.. function:: on_member_ban(guild, user) - - Called when user gets banned from a :class:`Guild`. - - This requires :attr:`Intents.bans` to be enabled. - - :param guild: The guild the user got banned from. - :type guild: :class:`Guild` - :param user: The user that got banned. - Can be either :class:`User` or :class:`Member` depending if - the user was in the guild or not at the time of removal. - :type user: Union[:class:`User`, :class:`Member`] - -.. function:: on_member_unban(guild, user) - - Called when a :class:`User` gets unbanned from a :class:`Guild`. - - This requires :attr:`Intents.bans` to be enabled. - - :param guild: The guild the user got unbanned from. - :type guild: :class:`Guild` - :param user: The user that got unbanned. - :type user: :class:`User` - -.. function:: on_invite_create(invite) - - Called when an :class:`Invite` is created. - You must have the :attr:`~Permissions.manage_channels` permission to receive this. - - .. versionadded:: 1.3 - - .. note:: - - There is a rare possibility that the :attr:`Invite.guild` and :attr:`Invite.channel` - attributes will be of :class:`Object` rather than the respective models. - - This requires :attr:`Intents.invites` to be enabled. - - :param invite: The invite that was created. - :type invite: :class:`Invite` - -.. function:: on_invite_delete(invite) - - Called when an :class:`Invite` is deleted. - You must have the :attr:`~Permissions.manage_channels` permission to receive this. - - .. versionadded:: 1.3 - - .. note:: - - There is a rare possibility that the :attr:`Invite.guild` and :attr:`Invite.channel` - attributes will be of :class:`Object` rather than the respective models. - - Outside of those two attributes, the only other attribute guaranteed to be - filled by the Discord gateway for this event is :attr:`Invite.code`. - - This requires :attr:`Intents.invites` to be enabled. - - :param invite: The invite that was deleted. - :type invite: :class:`Invite` - -.. function:: on_group_join(channel, user) - on_group_remove(channel, user) - - Called when someone joins or leaves a :class:`GroupChannel`. - - :param channel: The group that the user joined or left. - :type channel: :class:`GroupChannel` - :param user: The user that joined or left. - :type user: :class:`User` - .. _discord-api-utils: Utility Functions