From 1a734442758625b2ab730cd03c7c2fabdbc9d24a Mon Sep 17 00:00:00 2001 From: Chiggy-Playz <49774426+Chiggy-Playz@users.noreply.github.com> Date: Wed, 9 Mar 2022 07:55:28 +0530 Subject: [PATCH] Categorize events in the documentation --- docs/api.rst | 1361 ++++++++++++++++++++++++++------------------------ 1 file changed, 708 insertions(+), 653 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index f849c72dd..91a763a07 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -195,6 +195,96 @@ 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. +Channels +~~~~~~~~~ + +.. 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_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_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_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_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` + +Connection +~~~~~~~~~~~ + .. function:: on_connect() Called when the client has successfully connected to Discord. This is not @@ -202,6 +292,14 @@ to handle it, which defaults to print a traceback and ignoring the exception. 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_shard_connect(shard_id) Similar to :func:`on_connect` except used by :class:`AutoShardedClient` @@ -212,13 +310,6 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param shard_id: The shard ID that has connected. :type shard_id: :class:`int` -.. 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_shard_disconnect(shard_id) @@ -230,39 +321,8 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param shard_id: The shard ID that has disconnected. :type shard_id: :class:`int` -.. 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_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_resumed() - - Called when the client has resumed a session. - -.. 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` +Debug +~~~~~~ .. function:: on_error(event, *args, **kwargs) @@ -307,7 +367,7 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param event_type: The event type from Discord that is received, e.g. ``'READY'``. :type event_type: :class:`str` - + .. function:: on_socket_raw_receive(msg) Called whenever a message is completely received from the WebSocket, before @@ -347,527 +407,57 @@ 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. +Gateway +~~~~~~~~ - The ``channel`` parameter can be a :class:`abc.Messageable` instance. - Which could either be :class:`TextChannel`, :class:`GroupChannel`, or - :class:`DMChannel`. +.. function:: on_ready() - 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_message(message) - - Called when a :class:`Message` is created and sent. - - This requires :attr:`Intents.messages` to be enabled. + 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:: - 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. + 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. - :param message: The current message. - :type message: :class:`Message` +.. function:: on_resumed() -.. function:: on_message_delete(message) + Called when the client has resumed a session. - 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. +.. function:: on_shard_ready(shard_id) - If this occurs increase the :class:`max_messages ` parameter - or use the :func:`on_raw_message_delete` event instead. + Similar to :func:`on_ready` except used by :class:`AutoShardedClient` + to denote when a particular shard ID has become ready. - This requires :attr:`Intents.messages` to be enabled. + :param shard_id: The shard ID that is ready. + :type shard_id: :class:`int` - :param message: The deleted message. - :type message: :class:`Message` -.. function:: on_bulk_message_delete(messages) +.. function:: on_shard_resumed(shard_id) - 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` - -.. function:: on_reaction_add(reaction, user) - - Called when a message has a reaction added to it. Similar to :func:`on_message_edit`, - if the message is not found in the internal message cache, then this - event will not be called. Consider using :func:`on_raw_reaction_add` instead. - - .. note:: - - To get the :class:`Message` being reacted, access it via :attr:`Reaction.message`. - - This requires :attr:`Intents.reactions` to be enabled. - - .. note:: - - This doesn't require :attr:`Intents.members` within a guild context, - but due to Discord not providing updated user information in a direct message - it's required for direct messages to receive this event. - Consider using :func:`on_raw_reaction_add` if you need this and do not otherwise want - to enable the members intent. - - :param reaction: The current state of the reaction. - :type reaction: :class:`Reaction` - :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, - if the message is not found in the internal message cache, then this event - will not be called. - - .. note:: - - To get the message being reacted, access it via :attr:`Reaction.message`. - - This requires both :attr:`Intents.reactions` and :attr:`Intents.members` to be enabled. - - .. note:: - - Consider using :func:`on_raw_reaction_remove` if you need this and do not want - to enable the members intent. - - :param reaction: The current state of the reaction. - :type reaction: :class:`Reaction` - :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`, - if the message is not found in the internal message cache, then this event - will not be called. Consider using :func:`on_raw_reaction_clear` instead. - - This requires :attr:`Intents.reactions` to be enabled. - - :param message: The message that had its reactions cleared. - :type message: :class:`Message` - :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`, - if the message is not found in the internal message cache, then this event - will not be called. Consider using :func:`on_raw_reaction_clear_emoji` instead. - - This requires :attr:`Intents.reactions` to be enabled. - - .. versionadded:: 1.3 - - :param reaction: The reaction that got cleared. - :type reaction: :class:`Reaction` - -.. 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 - regardless of the state of the internal message cache. - - This requires :attr:`Intents.reactions` to be enabled. - - .. versionadded:: 1.3 - - :param payload: The raw event payload data. - :type payload: :class:`RawReactionClearEmojiEvent` - -.. function:: on_interaction(interaction) - - Called when an interaction happened. - - This currently happens due to slash command invocations or components being used. - - .. warning:: - - 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. - - .. versionadded:: 2.0 - - :param interaction: The interaction data. - :type interaction: :class:`Interaction` - -.. 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_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_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) - - Called whenever a thread is joined or created. Note that from the API's perspective there is no way to - differentiate between a thread being created or the bot joining a thread. - - Note that you can get the guild from :attr:`Thread.guild`. - - This requires :attr:`Intents.guilds` to be enabled. - - .. versionadded:: 2.0 - - :param thread: The thread that got joined. - :type thread: :class:`Thread` - -.. function:: on_thread_remove(thread) - - Called whenever a thread is removed. This is different from a thread being deleted. - - Note that you can get the guild from :attr:`Thread.guild`. - - This requires :attr:`Intents.guilds` to be enabled. - - .. warning:: - - Due to technical limitations, this event might not be called - as soon as one expects. Since the library tracks thread membership - locally, the API only sends updated thread membership status upon being - synced by joining a thread. - - .. versionadded:: 2.0 - - :param thread: The thread that got removed. - :type thread: :class:`Thread` - -.. function:: on_thread_delete(thread) - - Called whenever a thread is deleted. - - Note that you can get the guild from :attr:`Thread.guild`. - - This requires :attr:`Intents.guilds` to be enabled. - - .. versionadded:: 2.0 - - :param thread: The thread that got deleted. - :type thread: :class:`Thread` - -.. function:: on_thread_member_join(member) - on_thread_member_remove(member) - - Called when a :class:`ThreadMember` leaves or joins a :class:`Thread`. - - You can get the thread a member belongs in by accessing :attr:`ThreadMember.thread`. - - This requires :attr:`Intents.members` to be enabled. - - .. versionadded:: 2.0 - - :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. + 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 guild: The guild that had its integrations updated. - :type guild: :class:`Guild` + :param shard_id: The shard ID that has resumed. + :type shard_id: :class:`int` -.. function:: on_integration_create(integration) +Guilds +~~~~~~~ - Called when an integration is created. +.. function:: on_guild_available(guild) + on_guild_unavailable(guild) - This requires :attr:`Intents.integrations` to be enabled. + Called when a guild becomes available or unavailable. The guild must have + existed in the :attr:`Client.guilds` cache. - .. versionadded:: 2.0 + This requires :attr:`Intents.guilds` to be enabled. - :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` + :param guild: The :class:`Guild` that has changed availability. .. function:: on_guild_join(guild) @@ -914,29 +504,6 @@ to handle it, which defaults to print a traceback and ignoring the exception. :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`. @@ -965,61 +532,489 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param after: A list of stickers after the update. :type after: Sequence[:class:`GuildSticker`] -.. function:: on_guild_available(guild) - on_guild_unavailable(guild) +.. function:: on_invite_create(invite) - Called when a guild becomes available or unavailable. The guild must have - existed in the :attr:`Client.guilds` cache. + 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 guild: The guild that had its integrations updated. + :type guild: :class:`Guild` + +.. 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_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` + +Interactions +~~~~~~~~~~~~~ + +.. function:: on_interaction(interaction) + + Called when an interaction happened. + + This currently happens due to slash command invocations or components being used. + + .. warning:: + + 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. + + .. versionadded:: 2.0 + + :param interaction: The interaction data. + :type interaction: :class:`Interaction` + +Members +~~~~~~~~ + +.. function:: on_member_join(member) + on_member_remove(member) + + Called when a :class:`Member` join or leaves 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_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` + +Reactions +~~~~~~~~~~ + +.. function:: on_reaction_add(reaction, user) + + Called when a message has a reaction added to it. Similar to :func:`on_message_edit`, + if the message is not found in the internal message cache, then this + event will not be called. Consider using :func:`on_raw_reaction_add` instead. + + .. note:: + + To get the :class:`Message` being reacted, access it via :attr:`Reaction.message`. + + This requires :attr:`Intents.reactions` to be enabled. + + .. note:: + + This doesn't require :attr:`Intents.members` within a guild context, + but due to Discord not providing updated user information in a direct message + it's required for direct messages to receive this event. + Consider using :func:`on_raw_reaction_add` if you need this and do not otherwise want + to enable the members intent. + + :param reaction: The current state of the reaction. + :type reaction: :class:`Reaction` + :param user: The user who added the reaction. + :type user: Union[:class:`Member`, :class:`User`] + +.. function:: on_reaction_remove(reaction, user) + + Called when a message has a reaction removed from it. Similar to on_message_edit, + if the message is not found in the internal message cache, then this event + will not be called. + + .. note:: + + To get the message being reacted, access it via :attr:`Reaction.message`. + + This requires both :attr:`Intents.reactions` and :attr:`Intents.members` to be enabled. + + .. note:: + + Consider using :func:`on_raw_reaction_remove` if you need this and do not want + to enable the members intent. + + :param reaction: The current state of the reaction. + :type reaction: :class:`Reaction` + :param user: The user who added the reaction. + :type user: Union[:class:`Member`, :class:`User`] + +.. function:: on_reaction_clear(message, reactions) + + Called when a message has all its reactions removed from it. Similar to :func:`on_message_edit`, + if the message is not found in the internal message cache, then this event + will not be called. Consider using :func:`on_raw_reaction_clear` instead. + + This requires :attr:`Intents.reactions` to be enabled. + + :param message: The message that had its reactions cleared. + :type message: :class:`Message` + :param reactions: The reactions that were removed. + :type reactions: List[:class:`Reaction`] + +.. function:: on_reaction_clear_emoji(reaction) + + Called when a message has a specific reaction removed from it. Similar to :func:`on_message_edit`, + if the message is not found in the internal message cache, then this event + will not be called. Consider using :func:`on_raw_reaction_clear_emoji` instead. + + This requires :attr:`Intents.reactions` to be enabled. + + .. versionadded:: 1.3 + + :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 + regardless of the state of the internal message cache. + + This requires :attr:`Intents.reactions` to be enabled. + + .. versionadded:: 1.3 + + :param payload: The raw event payload data. + :type payload: :class:`RawReactionClearEmojiEvent` + + +Roles +~~~~~~ + +.. 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 guild: The :class:`Guild` that has changed availability. + :param role: The role that was created or deleted. + :type role: :class:`Role` -.. function:: on_voice_state_update(member, before, after) +.. function:: on_guild_role_update(before, after) - Called when a :class:`Member` changes their :class:`VoiceState`. + Called when a :class:`Role` is changed guild-wide. - The following, but not limited to, examples illustrate when this event is called: + This requires :attr:`Intents.guilds` to be enabled. - - A member joins a voice or stage channel. - - A member leaves a voice or stage channel. - - A member is muted or deafened by their own accord. - - A member is muted or deafened by a guild administrator. + :param before: The updated role's old info. + :type before: :class:`Role` + :param after: The updated role's updated info. + :type after: :class:`Role` - This requires :attr:`Intents.voice_states` to be enabled. - :param member: The member whose voice states changed. - :type member: :class:`Member` - :param before: The voice state prior to the changes. - :type before: :class:`VoiceState` - :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` +Scheduled Events +~~~~~~~~~~~~~~~~~ .. function:: on_scheduled_event_create(event) on_scheduled_event_delete(event) @@ -1068,76 +1063,136 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param user: The user that was added or removed. :type user: :class:`User` -.. function:: on_member_ban(guild, user) - Called when user gets banned from a :class:`Guild`. +Stages +~~~~~~~ - This requires :attr:`Intents.bans` to be enabled. +.. function:: on_stage_instance_create(stage_instance) + on_stage_instance_delete(stage_instance) - :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`] + Called when a :class:`StageInstance` is created or deleted for a :class:`StageChannel`. -.. function:: on_member_unban(guild, user) + .. versionadded:: 2.0 - Called when a :class:`User` gets unbanned from a :class:`Guild`. + :param stage_instance: The stage instance that was created or deleted. + :type stage_instance: :class:`StageInstance` - This requires :attr:`Intents.bans` to be enabled. +.. function:: on_stage_instance_update(before, after) - :param guild: The guild the user got unbanned from. - :type guild: :class:`Guild` - :param user: The user that got unbanned. - :type user: :class:`User` + Called when a :class:`StageInstance` is updated. -.. function:: on_invite_create(invite) + The following, but not limited to, examples illustrate when this event is called: - Called when an :class:`Invite` is created. - You must have the :attr:`~Permissions.manage_channels` permission to receive this. + - The topic is changed. + - The privacy level is changed. - .. versionadded:: 1.3 + .. versionadded:: 2.0 - .. note:: + :param before: The stage instance before the update. + :type before: :class:`StageInstance` + :param after: The stage instance after the update. + :type after: :class:`StageInstance` - 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. +Threads +~~~~~~~~ - This requires :attr:`Intents.invites` to be enabled. - :param invite: The invite that was created. - :type invite: :class:`Invite` +.. function:: on_thread_join(thread) -.. function:: on_invite_delete(invite) + Called whenever a thread is joined or created. Note that from the API's perspective there is no way to + differentiate between a thread being created or the bot joining a thread. - Called when an :class:`Invite` is deleted. - You must have the :attr:`~Permissions.manage_channels` permission to receive this. + Note that you can get the guild from :attr:`Thread.guild`. - .. versionadded:: 1.3 + This requires :attr:`Intents.guilds` to be enabled. - .. note:: + .. versionadded:: 2.0 - 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. + :param thread: The thread that got joined. + :type thread: :class:`Thread` - Outside of those two attributes, the only other attribute guaranteed to be - filled by the Discord gateway for this event is :attr:`Invite.code`. +.. function:: on_thread_update(before, after) - This requires :attr:`Intents.invites` to be enabled. + Called whenever a thread is updated. - :param invite: The invite that was deleted. - :type invite: :class:`Invite` + This requires :attr:`Intents.guilds` to be enabled. -.. function:: on_group_join(channel, user) - on_group_remove(channel, user) + .. versionadded:: 2.0 - Called when someone joins or leaves a :class:`GroupChannel`. + :param before: The updated thread's old info. + :type before: :class:`Thread` + :param after: The updated thread's new info. + :type after: :class:`Thread` - :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_thread_remove(thread) + + Called whenever a thread is removed. This is different from a thread being deleted. + + Note that you can get the guild from :attr:`Thread.guild`. + + This requires :attr:`Intents.guilds` to be enabled. + + .. warning:: + + Due to technical limitations, this event might not be called + as soon as one expects. Since the library tracks thread membership + locally, the API only sends updated thread membership status upon being + synced by joining a thread. + + .. versionadded:: 2.0 + + :param thread: The thread that got removed. + :type thread: :class:`Thread` + +.. function:: on_thread_delete(thread) + + Called whenever a thread is deleted. + + Note that you can get the guild from :attr:`Thread.guild`. + + This requires :attr:`Intents.guilds` to be enabled. + + .. versionadded:: 2.0 + + :param thread: The thread that got deleted. + :type thread: :class:`Thread` + +.. function:: on_thread_member_join(member) + on_thread_member_remove(member) + + Called when a :class:`ThreadMember` leaves or joins a :class:`Thread`. + + You can get the thread a member belongs in by accessing :attr:`ThreadMember.thread`. + + This requires :attr:`Intents.members` to be enabled. + + .. versionadded:: 2.0 + + :param member: The member who joined or left. + :type member: :class:`ThreadMember` + +Voice +~~~~~~ + +.. function:: on_voice_state_update(member, before, after) + + Called when a :class:`Member` changes their :class:`VoiceState`. + + The following, but not limited to, examples illustrate when this event is called: + + - A member joins a voice or stage channel. + - A member leaves a voice or stage channel. + - A member is muted or deafened by their own accord. + - A member is muted or deafened by a guild administrator. + + This requires :attr:`Intents.voice_states` to be enabled. + + :param member: The member whose voice states changed. + :type member: :class:`Member` + :param before: The voice state prior to the changes. + :type before: :class:`VoiceState` + :param after: The voice state after the changes. + :type after: :class:`VoiceState` .. _discord-api-utils: