diff --git a/docs/api.rst b/docs/api.rst index c0e6210bf..b0c2df530 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -45,43 +45,6 @@ Client .. automethod:: Client.event() :decorator: - -Application Info ------------------- - -AppInfo -~~~~~~~~ - -.. attributetable:: AppInfo - -.. autoclass:: AppInfo() - :members: - -PartialAppInfo -~~~~~~~~~~~~~~~ - -.. attributetable:: PartialAppInfo - -.. autoclass:: PartialAppInfo() - :members: - -Team -~~~~~ - -.. attributetable:: Team - -.. autoclass:: Team() - :members: - -TeamMember -~~~~~~~~~~~ - -.. attributetable:: TeamMember - -.. autoclass:: TeamMember() - :members: - :inherited-members: - Voice Related --------------- @@ -172,7 +135,7 @@ overriding the specific events. For example: :: class MyClient(discord.Client): async def on_message(self, message): - if message.author == self.user: + if message.author != self.user: return if message.content.startswith('$hello'): @@ -197,8 +160,6 @@ Channels 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` @@ -206,44 +167,36 @@ Channels 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) +.. function:: on_private_channel_delete(channel) + on_private_channel_create(channel) + + Called whenever a private channel is deleted or created. - Called whenever a private group DM is updated. e.g. changed name or topic. + :param channel: The private channel that got created or deleted. + :type channel: :class:`abc.PrivateChannel` + +.. function:: on_private_channel_update(before, after) - This requires :attr:`Intents.messages` to be enabled. + Called whenever a private channel is updated. e.g. changed name or topic. - :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` + :param before: The updated private channel's old info. + :type before: :class:`abc.PrivateChannel` + :param after: The updated private channel's new info. + :type after: :class:`abc.PrivateChannel` .. function:: on_private_channel_pins_update(channel, last_pin) @@ -254,6 +207,16 @@ Channels :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_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_typing(channel, user, when) Called when someone begins typing a message. @@ -265,8 +228,6 @@ Channels 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. @@ -378,7 +339,6 @@ Debug WebSocket library. It can be :class:`bytes` to denote a binary message or :class:`str` to denote a regular text message. - Gateway ~~~~~~~~ @@ -398,6 +358,101 @@ Gateway Called when the client has resumed a session. +Client +~~~~~~ + +.. function:: on_settings_update(before, after) + + Called when your :class:`Settings` updates, for example: + + - Changed theme + - Changed custom activity + - Changed locale + - etc + + .. versionadded:: 2.0 + + :param before: The settings prior to being updated. + :type before: :class:`Settings` + :param after: The settings after being updated. + :type after: :class:`Settings` + +.. function:: on_guild_settings_update(before, after) + + Called when a :class:`Guild`'s :class:`GuildSettings` updates, for example: + + - Muted guild + - Changed guild notification settings + - etc + + Note that you can get the guild from :attr:`GuildSettings.guild`. + + .. versionadded:: 2.0 + + :param before: The guild settings prior to being updated. + :type before: :class:`GuildSettings` + :param after: The guild settings after being updated. + :type after: :class:`GuildSettings` + +.. function:: on_required_action_update(action) + + Called when Discord requires you to do something to verify ypur account. + + .. versionadded:: 2.0 + + :param action: The action required. + :type action: :class:`RequiredActionType` + +.. function:: on_connections_update() + + Called when your account connections are updated. + The updated connections are not provided and must be fetched by :func:`Client.connections`. + + .. versionadded:: 2.0 + +Relationships +~~~~~~~~~~~~~ + +.. function:: on_relationship_add(relationship) + on_relationship_remove(relationship) + + Called when a :class:`Relationship` is added or removed from the + :class:`ClientUser`. + + :param relationship: The relationship that was added or removed. + :type relationship: :class:`Relationship` + +.. function:: on_relationship_update(before, after) + + Called when a :class:`Relationship` is updated, e.g. when you + block a friend or a friendship is accepted. + + :param before: The previous relationship. + :type before: :class:`Relationship` + :param after: The updated relationship. + :type after: :class:`Relationship` + +Calls +~~~~~ + +.. function:: on_call_create(call) + on_call_delete(call) + + Called when a call is created in a :class:`abc.PrivateChannel`. + + :param call: The call that was created or deleted. + :type call: Union[:class:`PrivateCall`, :class:`GroupCall`] + +.. function:: on_call_update(before, after) + + Called when a :class:`Call` is updated, e.g. when a member is added + or another person is rung. + + :param before: The previous call. + :type before: :class:`Relationship` + :param after: The updated call. + :type after: :class:`Relationship` + Guilds ~~~~~~~ @@ -407,8 +462,6 @@ Guilds 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) @@ -416,8 +469,6 @@ Guilds Called when a :class:`Guild` is either created by the :class:`Client` or when the :class:`Client` joins a guild. - - :param guild: The guild that was joined. :type guild: :class:`Guild` @@ -435,8 +486,6 @@ Guilds 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`) - - :param guild: The guild that got removed. :type guild: :class:`Guild` @@ -449,8 +498,6 @@ Guilds - Changed AFK timeout - etc - - :param before: The guild prior to being updated. :type before: :class:`Guild` :param after: The guild after being updated. @@ -460,8 +507,6 @@ Guilds Called when a :class:`Guild` adds or removes :class:`Emoji`. - - :param guild: The guild who got their emojis updated. :type guild: :class:`Guild` :param before: A list of emojis before the update. @@ -473,8 +518,6 @@ Guilds Called when a :class:`Guild` updates its stickers. - - .. versionadded:: 2.0 :param guild: The guild who got their stickers updated. @@ -496,8 +539,6 @@ Guilds 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` @@ -516,8 +557,6 @@ Guilds 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` @@ -529,8 +568,6 @@ Integrations Called when an integration is created. - This requires :attr:`Intents.integrations` to be enabled. - .. versionadded:: 2.0 :param integration: The integration that was created. @@ -540,8 +577,6 @@ Integrations Called when an integration is updated. - This requires :attr:`Intents.integrations` to be enabled. - .. versionadded:: 2.0 :param integration: The integration that was created. @@ -551,8 +586,6 @@ Integrations 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. @@ -562,8 +595,6 @@ Integrations 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` @@ -571,8 +602,6 @@ Integrations Called when an integration is deleted. - This requires :attr:`Intents.integrations` to be enabled. - .. versionadded:: 2.0 :param payload: The raw event payload data. @@ -583,21 +612,35 @@ Interactions .. function:: on_interaction(interaction) - Called when an interaction happened. + Called when an interaction happens. - This currently happens due to slash command invocations or components being used. + This currently happens when an application command or component is used. - .. warning:: + .. versionadded:: 2.0 + + :param interaction: The interaction data. + :type interaction: :class:`Interaction` + +.. function:: on_interaction_finish(interaction) - 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. + Called when an interaction's result is finalized. .. versionadded:: 2.0 - :param interaction: The interaction data. + :param interaction: The interaction data with :attr:`Interaction.successful` filled. :type interaction: :class:`Interaction` +.. function:: on_modal(modal) + + Called when a modal is sent. + + This currently happens when an application command or component responds with a modal. + + .. versionadded:: 2.0 + + :param modal: The modal data. + :type modal: :class:`Modal` + Members ~~~~~~~~ @@ -606,8 +649,6 @@ Members 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` @@ -621,8 +662,6 @@ Members - 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. @@ -638,8 +677,6 @@ Members - 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. @@ -649,8 +686,6 @@ Members 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. @@ -662,8 +697,6 @@ Members 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. @@ -678,8 +711,6 @@ Members - 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. @@ -687,6 +718,15 @@ Members :param after: The updated member's updated info. :type after: :class:`Member` +.. function:: on_raw_member_list_update(data) + + Called when a member list update is received and parsed. + + .. versionadded:: 2.0 + + :param data: The raw member list update data. + :type data: :class:`dict` + Messages ~~~~~~~~~ @@ -694,8 +734,6 @@ Messages 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 @@ -728,8 +766,6 @@ Messages - 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. @@ -745,8 +781,6 @@ Messages 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` @@ -762,8 +796,6 @@ Messages 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`] @@ -786,12 +818,9 @@ Messages 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 @@ -800,8 +829,6 @@ Messages 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` @@ -813,8 +840,6 @@ Messages 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` @@ -831,8 +856,6 @@ Reactions 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, @@ -874,8 +897,6 @@ Reactions 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. @@ -887,21 +908,16 @@ Reactions 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` @@ -910,8 +926,6 @@ Reactions 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` @@ -920,8 +934,6 @@ Reactions 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` @@ -930,14 +942,11 @@ Reactions 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 ~~~~~~ @@ -948,8 +957,6 @@ Roles To get the guild it belongs to, use :attr:`Role.guild`. - - :param role: The role that was created or deleted. :type role: :class:`Role` @@ -957,8 +964,6 @@ Roles 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. @@ -973,8 +978,6 @@ Scheduled Events Called when a :class:`ScheduledEvent` is created or deleted. - This requires :attr:`Intents.guild_scheduled_events` to be enabled. - .. versionadded:: 2.0 :param event: The scheduled event that was created or deleted. @@ -984,8 +987,6 @@ Scheduled Events Called when a :class:`ScheduledEvent` is updated. - This requires :attr:`Intents.guild_scheduled_events` to be enabled. - The following, but not limited to, examples illustrate when this event is called: - The scheduled start/end times are changed. @@ -1006,8 +1007,6 @@ Scheduled Events Called when a user is added or removed from a :class:`ScheduledEvent`. - This requires :attr:`Intents.guild_scheduled_events` to be enabled. - .. versionadded:: 2.0 :param event: The scheduled event that the user was added or removed from. @@ -1015,7 +1014,6 @@ Scheduled Events :param user: The user that was added or removed. :type user: :class:`User` - Stages ~~~~~~~ @@ -1048,25 +1046,16 @@ Stages Threads ~~~~~~~~ -<<<<<<< HEAD -<<<<<<< HEAD - -======= ->>>>>>> upstream/master -======= .. function:: on_thread_create(thread) Called whenever a thread is created. 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 was created. :type thread: :class:`Thread` ->>>>>>> 95deb553328d4d1c3e8b6b50239b67c56c4576fa .. function:: on_thread_join(thread) @@ -1074,8 +1063,6 @@ Threads 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. @@ -1083,13 +1070,7 @@ Threads .. function:: on_thread_update(before, after) -<<<<<<< HEAD - -======= Called whenever a thread is updated. ->>>>>>> upstream/master - - This requires :attr:`Intents.guilds` to be enabled. .. versionadded:: 2.0 @@ -1104,8 +1085,6 @@ Threads 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 @@ -1124,8 +1103,6 @@ Threads 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. @@ -1138,8 +1115,6 @@ Threads 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. @@ -1159,8 +1134,6 @@ Voice - 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. @@ -1179,6 +1152,8 @@ Utility Functions .. autofunction:: discord.utils.snowflake_time +.. autofunction:: discord.utils.time_snowflake + .. autofunction:: discord.utils.oauth_url .. autofunction:: discord.utils.remove_markdown @@ -1215,6 +1190,8 @@ Utility Functions .. autofunction:: discord.utils.as_chunks +.. autofunction:: discord.utils.set_target + .. _discord-api-enums: Enumerations @@ -1421,6 +1398,11 @@ of :class:`enum.Enum`. .. attribute:: bug_hunter The user is a Bug Hunter. + .. attribute:: bug_hunter_level_1 + + The user is a Bug Hunter. + + .. versionadded:: 2.0 .. attribute:: mfa_sms The user has SMS recovery for Multi Factor Authentication enabled. @@ -1442,15 +1424,25 @@ of :class:`enum.Enum`. .. attribute:: team_user The user is a Team User. + .. attribute:: partner_or_verification_application + + The user has a partner or verification application. .. attribute:: system The user is a system user (i.e. represents Discord officially). + + .. versionadded:: 2.0 .. attribute:: has_unread_urgent_messages The user has an unread system message. .. attribute:: bug_hunter_level_2 The user is a Bug Hunter Level 2. + .. attribute:: underage_deleted + + The user has been flagged for deletion for being underage. + + .. versionadded:: 2.0 .. attribute:: verified_bot The user is a Verified Bot. @@ -1469,6 +1461,11 @@ of :class:`enum.Enum`. The user is flagged as a spammer by Discord. + .. versionadded:: 2.0 + .. attribute:: disable_premium + + The user bought premium but has it manually disabled. + .. versionadded:: 2.0 .. class:: ActivityType @@ -2383,7 +2380,30 @@ of :class:`enum.Enum`. .. class:: TeamMembershipState - Represents the membership state of a team member retrieved through :func:`Client.application_info`. + Represents the membership state of a :class:`TeamMember`. + +    .. container:: operations + +        .. versionadded:: 2.0 + +        .. describe:: x == y + +            Checks if two membership states are equal. +        .. describe:: x != y + +            Checks if two membership states are not equal. +        .. describe:: x > y + +            Checks if a membership state is higher than another. +        .. describe:: x < y + +            Checks if a membership state is lower than another. +        .. describe:: x >= y + +            Checks if a membership state is higher or equal to another. +        .. describe:: x <= y + +            Checks if a membership state is lower or equal to another. .. versionadded:: 1.3 @@ -2395,94 +2415,271 @@ of :class:`enum.Enum`. Represents a member currently in the team. -.. class:: WebhookType +.. class:: ApplicationType - Represents the type of webhook that can be received. + Represents the type of an application. - .. versionadded:: 1.3 + .. versionadded:: 2.0 - .. attribute:: incoming + .. attribute:: none - Represents a webhook that can post messages to channels with a token. + The application does not have a special type. - .. attribute:: channel_follower + .. attribute:: game - Represents a webhook that is internally managed by Discord, used for following channels. + The application is a game. - .. attribute:: application + .. attribute:: music + + The application is music-related. - Represents a webhook that is used for interactions or applications. + .. attribute:: ticketed_events - .. versionadded:: 2.0 + The application can use ticketed event. -.. class:: ExpireBehaviour +.. class:: ApplicationVerificationState - Represents the behaviour the :class:`Integration` should perform - when a user's subscription has finished. + Represents the verification application state of a :class:`Application`. - There is an alias for this called ``ExpireBehavior``. +    .. container:: operations - .. versionadded:: 1.4 +        .. versionadded:: 2.0 - .. attribute:: remove_role +        .. describe:: x == y - This will remove the :attr:`StreamIntegration.role` from the user - when their subscription is finished. +            Checks if two application states are equal. +        .. describe:: x != y - .. attribute:: kick +            Checks if two application states are not equal. +        .. describe:: x > y - This will kick the user when their subscription is finished. +            Checks if a application state is higher than another. +        .. describe:: x < y -.. class:: DefaultAvatar +            Checks if a application state is lower than another. +        .. describe:: x >= y - Represents the default avatar of a Discord :class:`User` +            Checks if a application state is higher or equal to another. +        .. describe:: x <= y - .. attribute:: blurple +            Checks if a application state is lower or equal to another. - Represents the default avatar with the color blurple. - See also :attr:`Colour.blurple` - .. attribute:: grey + .. versionadded:: 2.0 - Represents the default avatar with the color grey. - See also :attr:`Colour.greyple` - .. attribute:: gray + .. attribute:: ineligible - An alias for :attr:`grey`. - .. attribute:: green + The application is ineligible for verification. - Represents the default avatar with the color green. - See also :attr:`Colour.green` - .. attribute:: orange + .. attribute:: unsubmitted - Represents the default avatar with the color orange. - See also :attr:`Colour.orange` - .. attribute:: red + The application is has not submitted a verification request. - Represents the default avatar with the color red. - See also :attr:`Colour.red` + .. attribute:: submitted + + The application has submitted a verification request and is pending a response. - .. attribute:: pink + .. attribute:: succeeded - Represents the default avatar with the color pink. - This is not currently used in the client. + The application has been verified. -.. class:: StickerType +.. class:: StoreApplicationState - Represents the type of sticker. + Represents the commerce application state of a :class:`Application`. - .. versionadded:: 2.0 +    .. container:: operations - .. attribute:: standard +        .. versionadded:: 2.0 - Represents a standard sticker that all Nitro users can use. +        .. describe:: x == y - .. attribute:: guild +            Checks if two application states are equal. +        .. describe:: x != y - Represents a custom sticker created in a guild. +            Checks if two application states are not equal. +        .. describe:: x > y -.. class:: StickerFormatType +            Checks if a application state is higher than another. +        .. describe:: x < y - Represents the type of sticker images. +            Checks if a application state is lower than another. +        .. describe:: x >= y + +            Checks if a application state is higher or equal to another. +        .. describe:: x <= y + +            Checks if a application state is lower or equal to another. + + .. versionadded:: 2.0 + + .. attribute:: none + + The application has not applied for commerce features. + + .. attribute:: paid + + The application has paid the commerce feature fee. + + .. attribute:: submitted + + The application has submitted a commerce application and is pending a response. + + .. attribute:: approved + + The application has been approved for commerce features. + + .. attribute:: rejected + + The application has not been approved for commerce features. + + .. attribute:: blocked + + The application has been blocked from using commerce features. + +.. class:: RPCApplicationState + + Represents the RPC application state of a :class:`Application`. + +    .. container:: operations + +        .. versionadded:: 2.0 + +        .. describe:: x == y + +            Checks if two application states are equal. +        .. describe:: x != y + +            Checks if two application states are not equal. +        .. describe:: x > y + +            Checks if a application state is higher than another. +        .. describe:: x < y + +            Checks if a application state is lower than another. +        .. describe:: x >= y + +            Checks if a application state is higher or equal to another. +        .. describe:: x <= y + +            Checks if a application state is lower or equal to another. + + .. versionadded:: 2.0 + + .. attribute:: disabled + + The application has not applied for RPC functionality and cannot use the feature. + + .. attribute:: none + + The application has not applied for RPC functionality and cannot use the feature. + + .. attribute:: unsubmitted + + The application has not submitted a RPC application. + + .. attribute:: submitted + + The application has submitted a RPC application and is pending a response. + + .. attribute:: approved + + The application has been approved for RPC funcionality. + + .. attribute:: rejected + + The application has not been approved for RPC funcionality. + + .. attribute:: blocked + + The application has been blocked from using commerce features. + +.. class:: WebhookType + + Represents the type of webhook that can be received. + + .. versionadded:: 1.3 + + .. attribute:: incoming + + Represents a webhook that can post messages to channels with a token. + + .. attribute:: channel_follower + + Represents a webhook that is internally managed by Discord, used for following channels. + + .. attribute:: application + + Represents a webhook that is used for interactions or applications. + + .. versionadded:: 2.0 + +.. class:: ExpireBehaviour + + Represents the behaviour the :class:`Integration` should perform + when a user's subscription has finished. + + There is an alias for this called ``ExpireBehavior``. + + .. versionadded:: 1.4 + + .. attribute:: remove_role + + This will remove the :attr:`StreamIntegration.role` from the user + when their subscription is finished. + + .. attribute:: kick + + This will kick the user when their subscription is finished. + +.. class:: DefaultAvatar + + Represents the default avatar of a Discord :class:`User` + + .. attribute:: blurple + + Represents the default avatar with the color blurple. + See also :attr:`Colour.blurple` + .. attribute:: grey + + Represents the default avatar with the color grey. + See also :attr:`Colour.greyple` + .. attribute:: gray + + An alias for :attr:`grey`. + .. attribute:: green + + Represents the default avatar with the color green. + See also :attr:`Colour.green` + .. attribute:: orange + + Represents the default avatar with the color orange. + See also :attr:`Colour.orange` + .. attribute:: red + + Represents the default avatar with the color red. + See also :attr:`Colour.red` + + .. attribute:: pink + + Represents the default avatar with the color pink. + This is not currently used in the client. + +.. class:: StickerType + + Represents the type of sticker. + + .. versionadded:: 2.0 + + .. attribute:: standard + + Represents a standard sticker that all Nitro users can use. + + .. attribute:: guild + + Represents a custom sticker created in a guild. + +.. class:: StickerFormatType + + Represents the type of sticker images. .. versionadded:: 1.6 @@ -2583,6 +2780,115 @@ of :class:`enum.Enum`. The guild may contain NSFW content. +.. class:: RelationshipType + + Specifies the type of :class:`Relationship`. + + .. attribute:: friend + + You are friends with this user. + + .. attribute:: blocked + + You have blocked this user. + + .. attribute:: incoming_request + + The user has sent you a friend request. + + .. attribute:: outgoing_request + + You have sent a friend request to this user. + +.. class:: UserContentFilter + + Represents the options found in ``Settings > Privacy & Safety > Safe Direct Messaging`` + in the Discord client. + + .. attribute:: all_messages + + Scan all direct messages from everyone. + + .. attribute:: non_friends + + Scan all direct messages that aren't from friends. + + .. attribute:: disabled + + Don't scan any direct messages. + +.. class:: FriendFlags + + Represents the options found in ``Settings > Privacy & Safety > Who Can Add You As A Friend`` + in the Discord client. + + .. attribute:: noone + + This allows no-one to add you as a friend. + + .. attribute:: mutual_guilds + + This allows guild members to add you as a friend. + + .. attribute:: mutual_friends + + This allows friends of friends to add you as a friend. + + .. attribute:: guild_and_friends + + This is a superset of :attr:`mutual_guilds` and :attr:`mutual_friends`. + + .. attribute:: everyone + + This allows everyone to add you as a friend. + +.. class:: PremiumType + + Represents the user's Discord Nitro subscription type. + + .. container:: operations + + .. versionadded:: 2.0 + + .. describe:: x == y + + Checks if two premium types are equal. + .. describe:: x != y + + Checks if two premium types are not equal. + .. describe:: x > y + + Checks if a premium level is higher than another. + .. describe:: x < y + + Checks if a premium level is lower than another. + .. describe:: x >= y + + Checks if a premium level is higher or equal to another. + .. describe:: x <= y + + Checks if a premium level is lower or equal to another. + + .. attribute:: nitro + + Represents the Discord Nitro with Nitro-exclusive games. + + .. attribute:: nitro_classic + + Represents the Discord Nitro with no Nitro-exclusive games. + +.. class:: Theme + + Represents the theme synced across all Discord clients. + + .. attribute:: light + + Represents the Light theme on Discord. + + .. attribute:: dark + + Represents the Dark theme on Discord. + .. class:: Locale Supported locales by Discord. @@ -2789,88 +3095,263 @@ of :class:`enum.Enum`. An alias for :attr:`cancelled`. -.. _discord-api-audit-logs: +.. class:: RequiredActionType -Audit Log Data ----------------- + Represents an action Discord requires the user to take. -Working with :meth:`Guild.audit_logs` is a complicated process with a lot of machinery -involved. The library attempts to make it easy to use and friendly. In order to accomplish -this goal, it must make use of a couple of data classes that aid in this goal. + .. versionadded:: 2.0 -AuditLogEntry -~~~~~~~~~~~~~~~ + .. attribute:: verify_phone -.. attributetable:: AuditLogEntry + The user must verify their phone number. -.. autoclass:: AuditLogEntry - :members: + .. attribute:: verify_email -AuditLogChanges -~~~~~~~~~~~~~~~~~ + The user must verify their email address. -.. attributetable:: AuditLogChanges + .. attribute:: complete_captcha -.. class:: AuditLogChanges + The user must complete a captcha. - An audit log change set. + .. attribute:: accept_terms - .. attribute:: before + The user must accept Discord's terms of service. - The old value. The attribute has the type of :class:`AuditLogDiff`. +.. class:: InteractionType - Depending on the :class:`AuditLogActionCategory` retrieved by - :attr:`~AuditLogEntry.category`\, the data retrieved by this - attribute differs: + Specifies the type of :class:`Interaction`. - +----------------------------------------+---------------------------------------------------+ - | Category | Description | - +----------------------------------------+---------------------------------------------------+ - | :attr:`~AuditLogActionCategory.create` | All attributes are set to ``None``. | - +----------------------------------------+---------------------------------------------------+ - | :attr:`~AuditLogActionCategory.delete` | All attributes are set the value before deletion. | - +----------------------------------------+---------------------------------------------------+ - | :attr:`~AuditLogActionCategory.update` | All attributes are set the value before updating. | - +----------------------------------------+---------------------------------------------------+ - | ``None`` | No attributes are set. | - +----------------------------------------+---------------------------------------------------+ + .. versionadded:: 2.0 - .. attribute:: after + .. attribute:: application_command - The new value. The attribute has the type of :class:`AuditLogDiff`. + Represents a slash command interaction. + .. attribute:: component - Depending on the :class:`AuditLogActionCategory` retrieved by - :attr:`~AuditLogEntry.category`\, the data retrieved by this - attribute differs: + Represents a component based interaction, i.e. clicking a button. + .. attribute:: autocomplete - +----------------------------------------+--------------------------------------------------+ - | Category | Description | - +----------------------------------------+--------------------------------------------------+ - | :attr:`~AuditLogActionCategory.create` | All attributes are set to the created value | - +----------------------------------------+--------------------------------------------------+ - | :attr:`~AuditLogActionCategory.delete` | All attributes are set to ``None`` | - +----------------------------------------+--------------------------------------------------+ - | :attr:`~AuditLogActionCategory.update` | All attributes are set the value after updating. | - +----------------------------------------+--------------------------------------------------+ - | ``None`` | No attributes are set. | - +----------------------------------------+--------------------------------------------------+ + Represents an autocomplete interaction. + .. attribute:: modal_submit -AuditLogDiff -~~~~~~~~~~~~~ + Represents submission of a modal interaction. -.. attributetable:: AuditLogDiff +.. class:: ComponentType -.. class:: AuditLogDiff + Represents the component type of a component. - Represents an audit log "change" object. A change object has dynamic - attributes that depend on the type of action being done. Certain actions - map to certain attributes being set. + .. versionadded:: 2.0 - Note that accessing an attribute that does not match the specified action - will lead to an attribute error. + .. attribute:: action_row - To get a list of attributes that have been set, you can iterate over - them. To see a list of all possible attributes that could be set based + Represents the group component which holds different components in a row. + .. attribute:: button + + Represents a button component. + .. attribute:: select + + Represents a select component. + + .. attribute:: text_input + + Represents a text box component. + +.. class:: ButtonStyle + + Represents the style of the button component. + + .. versionadded:: 2.0 + + .. attribute:: primary + + Represents a blurple button for the primary action. + .. attribute:: secondary + + Represents a grey button for the secondary action. + .. attribute:: success + + Represents a green button for a successful action. + .. attribute:: danger + + Represents a red button for a dangerous action. + .. attribute:: link + + Represents a link button. + + .. attribute:: blurple + + An alias for :attr:`primary`. + .. attribute:: grey + + An alias for :attr:`secondary`. + .. attribute:: gray + + An alias for :attr:`secondary`. + .. attribute:: green + + An alias for :attr:`success`. + .. attribute:: red + + An alias for :attr:`danger`. + .. attribute:: url + + An alias for :attr:`link`. + +.. class:: TextStyle + + Represents the style of the text box component. + + .. versionadded:: 2.0 + + .. attribute:: short + + Represents a short text box. + .. attribute:: paragraph + + Represents a long form text box. + .. attribute:: long + + An alias for :attr:`paragraph`. + +.. class:: AppCommandOptionType + + The application command's option type. This is usually the type of parameter an application command takes. + + .. versionadded:: 2.0 + + .. attribute:: subcommand + + A subcommand. + .. attribute:: subcommand_group + + A subcommand group. + .. attribute:: string + + A string parameter. + .. attribute:: integer + + A integer parameter. + .. attribute:: boolean + + A boolean parameter. + .. attribute:: user + + A user parameter. + .. attribute:: channel + + A channel parameter. + .. attribute:: role + + A role parameter. + .. attribute:: mentionable + + A mentionable parameter. + .. attribute:: number + + A number parameter. + .. attribute:: attachment + + An attachment parameter. + +.. class:: AppCommandType + + The type of application command. + + .. versionadded:: 2.0 + + .. attribute:: chat_input + + A slash command. + .. attribute:: user + + A user context menu command. + .. attribute:: message + + A message context menu command. + + +.. _discord-api-audit-logs: + +Audit Log Data +---------------- + +Working with :meth:`Guild.audit_logs` is a complicated process with a lot of machinery +involved. The library attempts to make it easy to use and friendly. In order to accomplish +this goal, it must make use of a couple of data classes that aid in this goal. + +AuditLogEntry +~~~~~~~~~~~~~~~ + +.. attributetable:: AuditLogEntry + +.. autoclass:: AuditLogEntry + :members: + +AuditLogChanges +~~~~~~~~~~~~~~~~~ + +.. attributetable:: AuditLogChanges + +.. class:: AuditLogChanges + + An audit log change set. + + .. attribute:: before + + The old value. The attribute has the type of :class:`AuditLogDiff`. + + Depending on the :class:`AuditLogActionCategory` retrieved by + :attr:`~AuditLogEntry.category`\, the data retrieved by this + attribute differs: + + +----------------------------------------+---------------------------------------------------+ + | Category | Description | + +----------------------------------------+---------------------------------------------------+ + | :attr:`~AuditLogActionCategory.create` | All attributes are set to ``None``. | + +----------------------------------------+---------------------------------------------------+ + | :attr:`~AuditLogActionCategory.delete` | All attributes are set the value before deletion. | + +----------------------------------------+---------------------------------------------------+ + | :attr:`~AuditLogActionCategory.update` | All attributes are set the value before updating. | + +----------------------------------------+---------------------------------------------------+ + | ``None`` | No attributes are set. | + +----------------------------------------+---------------------------------------------------+ + + .. attribute:: after + + The new value. The attribute has the type of :class:`AuditLogDiff`. + + Depending on the :class:`AuditLogActionCategory` retrieved by + :attr:`~AuditLogEntry.category`\, the data retrieved by this + attribute differs: + + +----------------------------------------+--------------------------------------------------+ + | Category | Description | + +----------------------------------------+--------------------------------------------------+ + | :attr:`~AuditLogActionCategory.create` | All attributes are set to the created value | + +----------------------------------------+--------------------------------------------------+ + | :attr:`~AuditLogActionCategory.delete` | All attributes are set to ``None`` | + +----------------------------------------+--------------------------------------------------+ + | :attr:`~AuditLogActionCategory.update` | All attributes are set the value after updating. | + +----------------------------------------+--------------------------------------------------+ + | ``None`` | No attributes are set. | + +----------------------------------------+--------------------------------------------------+ + +AuditLogDiff +~~~~~~~~~~~~~ + +.. attributetable:: AuditLogDiff + +.. class:: AuditLogDiff + + Represents an audit log "change" object. A change object has dynamic + attributes that depend on the type of action being done. Certain actions + map to certain attributes being set. + + Note that accessing an attribute that does not match the specified action + will lead to an attribute error. + + To get a list of attributes that have been set, you can iterate over + them. To see a list of all possible attributes that could be set based on the action being done, check the documentation for :class:`AuditLogAction`, otherwise check the documentation below for all attributes that are possible. @@ -3382,7 +3863,7 @@ AuditLogDiff Webhook Support ------------------ -discord.py offers support for creating, editing, and executing webhooks through the :class:`Webhook` class. +discord.py-self offers support for creating, editing, and executing webhooks through the :class:`Webhook` class. Webhook ~~~~~~~~~ @@ -3418,6 +3899,22 @@ SyncWebhookMessage .. autoclass:: SyncWebhookMessage() :members: +PartialWebhookGuild +~~~~~~~~~~~~~~~~~~~~ + +.. attributetable:: PartialWebhookGuild + +.. autoclass:: PartialWebhookGuild() + :members: + +PartialWebhookChannel +~~~~~~~~~~~~~~~~~~~~~~~ + +.. attributetable:: PartialWebhookChannel + +.. autoclass:: PartialWebhookChannel() + :members: + .. _discord_api_abcs: Abstract Base Classes @@ -3482,6 +3979,14 @@ Connectable .. autoclass:: discord.abc.Connectable() :members: +ApplicationCommand +~~~~~~~~~~~~~~~~~~ + +.. attributetable:: discord.abc.ApplicationCommand + +.. autoclass:: discord.abc.ApplicationCommand() + :members: + .. _discord_api_models: Discord Models @@ -3508,9 +4013,8 @@ the user of the library. Nearly all classes here have :ref:`py:slots` defined which means that it is impossible to have dynamic attributes to the data classes. - -ClientUser -~~~~~~~~~~~~ +User +~~~~~ .. attributetable:: ClientUser @@ -3518,18 +4022,6 @@ ClientUser :members: :inherited-members: -UserSettings -~~~~~~~~~~~~~ - -.. attributetable:: UserSettings - -.. autoclass:: UserSettings() - :members: - :inherited-members: - -User -~~~~~ - .. attributetable:: User .. autoclass:: User() @@ -3540,126 +4032,151 @@ User .. automethod:: typing :async-with: -Profile -~~~~~~~~ - -.. attributetable:: Profile +.. attributetable:: UserProfile -.. autoclass:: Profile() +.. autoclass:: UserProfile() :members: :inherited-members: -Note -~~~~~ - .. attributetable:: Note .. autoclass:: Note() :members: - :inherited-members: -Relationship -~~~~~~~~~~~~~ +Connection +~~~~~~~~~~ -.. attributetable:: Relationship +.. attributetable:: Connection -.. autoclass:: Relationship() +.. autoclass:: Connection() :members: :inherited-members: -Attachment -~~~~~~~~~~~ - -.. attributetable:: Attachment +.. attributetable:: PartialConnection -.. autoclass:: Attachment() +.. autoclass:: PartialConnection() :members: -Asset -~~~~~ +Application +~~~~~~~~~~~ -.. attributetable:: Asset +.. attributetable:: Application -.. autoclass:: Asset() +.. autoclass:: Application() :members: :inherited-members: -Message -~~~~~~~ - -.. attributetable:: Message +.. attributetable:: ApplicationBot -.. autoclass:: Message() +.. autoclass:: ApplicationBot() :members: :inherited-members: -DeletedReferencedMessage -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. attributetable:: DeletedReferencedMessage +.. attributetable:: PartialApplication -.. autoclass:: DeletedReferencedMessage() +.. autoclass:: PartialApplication() :members: +.. attributetable:: InteractionApplication -Reaction -~~~~~~~~~ - -.. attributetable:: Reaction - -.. autoclass:: Reaction() +.. autoclass:: InteractionApplication() :members: -Guild -~~~~~~ +Team +~~~~~ -.. attributetable:: Guild +.. attributetable:: Team -.. autoclass:: Guild() +.. autoclass:: Team() :members: -.. class:: BanEntry +.. attributetable:: TeamMember - A namedtuple which represents a ban returned from :meth:`~Guild.bans`. +.. autoclass:: TeamMember() + :members: + :inherited-members: - .. attribute:: reason +Relationship +~~~~~~~~~~~~~ - The reason this user was banned. +.. attributetable:: Relationship - :type: Optional[:class:`str`] - .. attribute:: user +.. autoclass:: Relationship() + :members: - The :class:`User` that was banned. +Settings +~~~~~~~~ - :type: :class:`User` +.. attributetable:: UserSettings -GuildSettings -~~~~~~~~~~~~~~ +.. autoclass:: UserSettings() + :members: .. attributetable:: GuildSettings .. autoclass:: GuildSettings() :members: - :inherited-members: -GuildFolder -~~~~~~~~~~~~ +.. attributetable:: ChannelSettings + +.. autoclass:: ChannelSettings() + :members: .. attributetable:: GuildFolder .. autoclass:: GuildFolder() :members: - :inherited-members: - -GuildSubscriptionOptions -~~~~~~~~~~~~~~~~~~~~~~~~~ -.. attributetable:: GuildSubscriptionOptions +.. attributetable:: MuteConfig -.. autoclass:: GuildSubscriptionOptions() +.. autoclass:: MuteConfig() + :members: + +Asset +~~~~~ + +.. attributetable:: Asset + +.. autoclass:: Asset() + :members: + :inherited-members: + +Guild +~~~~~~ + +.. attributetable:: Guild + +.. autoclass:: Guild() + :members: + :inherited-members: + +.. class:: BanEntry + + A namedtuple which represents a ban returned from :meth:`~Guild.bans`. + + .. attribute:: reason + + The reason this user was banned. + + :type: Optional[:class:`str`] + .. attribute:: user + + The :class:`User` that was banned. + + :type: :class:`User` + +Role +~~~~~ + +.. attributetable:: Role + +.. autoclass:: Role() + :members: + +.. attributetable:: RoleTags + +.. autoclass:: RoleTags() :members: - :inherited-members: - ScheduledEvent ~~~~~~~~~~~~~~ @@ -3669,7 +4186,6 @@ ScheduledEvent .. autoclass:: ScheduledEvent() :members: - Integration ~~~~~~~~~~~~ @@ -3679,10 +4195,10 @@ Integration .. autoclass:: IntegrationAccount() :members: -.. autoclass:: BotIntegration() +.. autoclass:: IntegrationApplication() :members: -.. autoclass:: IntegrationApplication() +.. autoclass:: BotIntegration() :members: .. autoclass:: StreamIntegration() @@ -3701,13 +4217,11 @@ Member .. automethod:: typing :async-with: -Spotify -~~~~~~~~ - -.. attributetable:: Spotify +.. attributetable:: MemberProfile -.. autoclass:: Spotify() +.. autoclass:: MemberProfile() :members: + :inherited-members: VoiceState ~~~~~~~~~~~ @@ -3726,42 +4240,48 @@ Emoji :members: :inherited-members: -PartialEmoji -~~~~~~~~~~~~~~~~~~~~~~ - .. attributetable:: PartialEmoji .. autoclass:: PartialEmoji() :members: :inherited-members: -Role -~~~~~ +Sticker +~~~~~~~~ -.. attributetable:: Role +.. attributetable:: Sticker -.. autoclass:: Role() +.. autoclass:: Sticker() :members: -RoleTags -~~~~~~~~~~ +.. attributetable:: StickerItem -.. attributetable:: RoleTags +.. autoclass:: StickerItem() + :members: -.. autoclass:: RoleTags() +.. attributetable:: StickerPack + +.. autoclass:: StickerPack() :members: -PartialMessageable -~~~~~~~~~~~~~~~~~~~~ +.. attributetable:: StandardSticker -.. attributetable:: PartialMessageable +.. autoclass:: StandardSticker() + :members: -.. autoclass:: PartialMessageable() +.. attributetable:: GuildSticker + +.. autoclass:: GuildSticker() :members: - :inherited-members: -TextChannel -~~~~~~~~~~~~ +GuildChannel +~~~~~~~~~~~~~~ + +.. attributetable:: CategoryChannel + +.. autoclass:: CategoryChannel() + :members: + :inherited-members: .. attributetable:: TextChannel @@ -3773,21 +4293,21 @@ TextChannel .. automethod:: typing :async-with: -<<<<<<< HEAD - -ChannelSettings -~~~~~~~~~~~~~~~~ - -.. attributetable:: ChannelSettings +.. attributetable:: VoiceChannel -.. autoclass:: ChannelSettings() +.. autoclass:: VoiceChannel() :members: :inherited-members: + :exclude-members: typing + .. automethod:: typing + :async-with: -======= -ForumChannel -~~~~~~~~~~~~~ +.. attributetable:: StageChannel + +.. autoclass:: StageChannel() + :members: + :inherited-members: .. attributetable:: ForumChannel @@ -3795,13 +4315,12 @@ ForumChannel :members: :inherited-members: ->>>>>>> 95deb553328d4d1c3e8b6b50239b67c56c4576fa -Thread -~~~~~~~~ +PrivateChannel +~~~~~~~~~~~~~~~~ -.. attributetable:: Thread +.. attributetable:: DMChannel -.. autoclass:: Thread() +.. autoclass:: DMChannel() :members: :inherited-members: :exclude-members: typing @@ -3809,32 +4328,42 @@ Thread .. automethod:: typing :async-with: -ThreadMember -~~~~~~~~~~~~~ - -.. attributetable:: ThreadMember +.. attributetable:: GroupChannel -.. autoclass:: ThreadMember() +.. autoclass:: GroupChannel() :members: + :inherited-members: + :exclude-members: typing -VoiceChannel -~~~~~~~~~~~~~ + .. automethod:: typing + :async-with: -.. attributetable:: VoiceChannel +PartialMessageable +~~~~~~~~~~~~~~~~~~~~ -.. autoclass:: VoiceChannel() +.. attributetable:: PartialMessageable + +.. autoclass:: PartialMessageable() :members: :inherited-members: -StageChannel -~~~~~~~~~~~~~ +Thread +~~~~~~~ -.. attributetable:: StageChannel +.. attributetable:: Thread -.. autoclass:: StageChannel() +.. autoclass:: Thread() :members: :inherited-members: + :exclude-members: typing + + .. automethod:: typing + :async-with: + +.. attributetable:: ThreadMember +.. autoclass:: ThreadMember() + :members: StageInstance ~~~~~~~~~~~~~~ @@ -3844,210 +4373,169 @@ StageInstance .. autoclass:: StageInstance() :members: -CategoryChannel -~~~~~~~~~~~~~~~~~ +Message +~~~~~~~~ -.. attributetable:: CategoryChannel +.. attributetable:: Message -.. autoclass:: CategoryChannel() +.. autoclass:: Message() :members: :inherited-members: -DMChannel -~~~~~~~~~ - -.. attributetable:: DMChannel +.. attributetable:: PartialMessage -.. autoclass:: DMChannel() +.. autoclass:: PartialMessage :members: - :inherited-members: - :exclude-members: typing - - .. automethod:: typing - :async-with: - -GroupChannel -~~~~~~~~~~~~ -.. attributetable:: GroupChannel +.. attributetable:: Attachment -.. autoclass:: GroupChannel() +.. autoclass:: Attachment() :members: - :inherited-members: - :exclude-members: typing - .. automethod:: typing - :async-with: +.. attributetable:: MessageReference -PartialInviteGuild -~~~~~~~~~~~~~~~~~~~ +.. autoclass:: MessageReference() + :members: -.. attributetable:: PartialInviteGuild +.. attributetable:: DeletedReferencedMessage -.. autoclass:: PartialInviteGuild() +.. autoclass:: DeletedReferencedMessage() :members: -PartialInviteChannel -~~~~~~~~~~~~~~~~~~~~~ +Reaction +~~~~~~~~ -.. attributetable:: PartialInviteChannel +.. attributetable:: Reaction -.. autoclass:: PartialInviteChannel() +.. autoclass:: Reaction() :members: -Invite -~~~~~~~ +ApplicationCommand +~~~~~~~~~~~~~~~~~~ -.. attributetable:: Invite +.. attributetable:: BaseCommand -.. autoclass:: Invite() +.. autoclass:: BaseCommand() :members: + :inherited-members: -Template -~~~~~~~~~ - -.. attributetable:: Template +.. attributetable:: UserCommand -.. autoclass:: Template() +.. autoclass:: UserCommand() :members: + :inherited-members: -WidgetChannel -~~~~~~~~~~~~~~~ - -.. attributetable:: WidgetChannel +.. attributetable:: MessageCommand -.. autoclass:: WidgetChannel() +.. autoclass:: MessageCommand() :members: + :inherited-members: -WidgetMember -~~~~~~~~~~~~~ +.. attributetable:: SlashCommand -.. attributetable:: WidgetMember +.. autoclass:: SlashCommand() + :members: + :inherited-members: -.. autoclass:: WidgetMember() +.. attributetable:: SubCommand + +.. autoclass:: SubCommand() :members: :inherited-members: -Widget -~~~~~~~ +.. attributetable:: Option -.. attributetable:: Widget +.. autoclass:: Option() + :members: -.. autoclass:: Widget() +.. attributetable:: OptionChoice + +.. autoclass:: OptionChoice() :members: -StickerPack -~~~~~~~~~~~~~ +Invite +~~~~~~~ -.. attributetable:: StickerPack +.. attributetable:: Invite -.. autoclass:: StickerPack() +.. autoclass:: Invite() :members: -StickerItem -~~~~~~~~~~~~~ +.. attributetable:: PartialInviteGuild -.. attributetable:: StickerItem +.. autoclass:: PartialInviteGuild() + :members: -.. autoclass:: StickerItem() +.. attributetable:: PartialInviteChannel + +.. autoclass:: PartialInviteChannel() :members: -Sticker -~~~~~~~~~~~~~~~ +Template +~~~~~~~~~ -.. attributetable:: Sticker +.. attributetable:: Template -.. autoclass:: Sticker() +.. autoclass:: Template() :members: -StandardSticker -~~~~~~~~~~~~~~~~ +Widget +~~~~~~~ -.. attributetable:: StandardSticker +.. attributetable:: Widget -.. autoclass:: StandardSticker() +.. autoclass:: Widget() :members: -GuildSticker -~~~~~~~~~~~~~ +.. attributetable:: WidgetChannel -.. attributetable:: GuildSticker +.. autoclass:: WidgetChannel() + :members: -.. autoclass:: GuildSticker() +.. attributetable:: WidgetMember + +.. autoclass:: WidgetMember() :members: + :inherited-members: -RawMessageDeleteEvent -~~~~~~~~~~~~~~~~~~~~~~~ +Raw events +~~~~~~~~~~~ .. attributetable:: RawMessageDeleteEvent .. autoclass:: RawMessageDeleteEvent() :members: -RawBulkMessageDeleteEvent -~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. attributetable:: RawBulkMessageDeleteEvent .. autoclass:: RawBulkMessageDeleteEvent() :members: -RawMessageUpdateEvent -~~~~~~~~~~~~~~~~~~~~~~ - .. attributetable:: RawMessageUpdateEvent .. autoclass:: RawMessageUpdateEvent() :members: -RawReactionActionEvent -~~~~~~~~~~~~~~~~~~~~~~~ - .. attributetable:: RawReactionActionEvent .. autoclass:: RawReactionActionEvent() :members: -RawReactionClearEvent -~~~~~~~~~~~~~~~~~~~~~~ - .. attributetable:: RawReactionClearEvent .. autoclass:: RawReactionClearEvent() :members: -RawReactionClearEmojiEvent -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. attributetable:: RawReactionClearEmojiEvent .. autoclass:: RawReactionClearEmojiEvent() :members: -RawIntegrationDeleteEvent -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. attributetable:: RawIntegrationDeleteEvent .. autoclass:: RawIntegrationDeleteEvent() :members: -PartialWebhookGuild -~~~~~~~~~~~~~~~~~~~~ - -.. attributetable:: PartialWebhookGuild - -.. autoclass:: PartialWebhookGuild() - :members: - -PartialWebhookChannel -~~~~~~~~~~~~~~~~~~~~~~~ - -.. attributetable:: PartialWebhookChannel - -.. autoclass:: PartialWebhookChannel() - :members: - .. _discord_api_data: Data Classes @@ -4064,13 +4552,12 @@ impossible to have dynamic attributes to the data classes. The only exception to this rule is :class:`Object`, which is made with dynamic attributes in mind. - Object ~~~~~~~ .. attributetable:: Object -.. autoclass:: Object +.. autoclass:: Object() :members: Embed @@ -4078,7 +4565,7 @@ Embed .. attributetable:: Embed -.. autoclass:: Embed +.. autoclass:: Embed() :members: AllowedMentions @@ -4086,64 +4573,15 @@ AllowedMentions .. attributetable:: AllowedMentions -.. autoclass:: AllowedMentions - :members: - -MessageReference -~~~~~~~~~~~~~~~~~ - -.. attributetable:: MessageReference - -.. autoclass:: MessageReference - :members: - -PartialMessage -~~~~~~~~~~~~~~~~~ - -.. attributetable:: PartialMessage - -.. autoclass:: PartialMessage - :members: - -SelectOption -~~~~~~~~~~~~~ - -.. attributetable:: SelectOption - -.. autoclass:: SelectOption - :members: - -MemberCacheFlags -~~~~~~~~~~~~~~~~~~ - -.. attributetable:: MemberCacheFlags - -.. autoclass:: MemberCacheFlags - :members: - -ApplicationFlags -~~~~~~~~~~~~~~~~~ - -.. attributetable:: ApplicationFlags - -.. autoclass:: ApplicationFlags - :members: - -ChannelFlags -~~~~~~~~~~~~~~ - -.. attributetable:: ChannelFlags - -.. autoclass:: ChannelFlags +.. autoclass:: AllowedMentions() :members: - File ~~~~~ .. attributetable:: File -.. autoclass:: File +.. autoclass:: File() :members: Colour @@ -4151,47 +4589,40 @@ Colour .. attributetable:: Colour -.. autoclass:: Colour +.. autoclass:: Colour() :members: -BaseActivity -~~~~~~~~~~~~~~ +Activity +~~~~~~~~~ .. attributetable:: BaseActivity -.. autoclass:: BaseActivity +.. autoclass:: BaseActivity() :members: -Activity -~~~~~~~~~ - .. attributetable:: Activity -.. autoclass:: Activity +.. autoclass:: Activity() :members: -Game -~~~~~ - .. attributetable:: Game -.. autoclass:: Game +.. autoclass:: Game() :members: -Streaming -~~~~~~~~~~~ - .. attributetable:: Streaming -.. autoclass:: Streaming +.. autoclass:: Streaming() :members: -CustomActivity -~~~~~~~~~~~~~~~ +.. attributetable:: Spotify + +.. autoclass:: Spotify() + :members: .. attributetable:: CustomActivity -.. autoclass:: CustomActivity +.. autoclass:: CustomActivity() :members: Permissions @@ -4199,41 +4630,53 @@ Permissions .. attributetable:: Permissions -.. autoclass:: Permissions +.. autoclass:: Permissions() :members: -PermissionOverwrite -~~~~~~~~~~~~~~~~~~~~ - .. attributetable:: PermissionOverwrite -.. autoclass:: PermissionOverwrite +.. autoclass:: PermissionOverwrite() :members: -SystemChannelFlags -~~~~~~~~~~~~~~~~~~~~ +Flags +~~~~~~ + +.. attributetable:: ApplicationFlags + +.. autoclass:: ApplicationFlags() + :members: + +.. attributetable:: ChannelFlags + +.. autoclass:: ChannelFlags() + :members: .. attributetable:: SystemChannelFlags .. autoclass:: SystemChannelFlags() :members: -MessageFlags -~~~~~~~~~~~~ - .. attributetable:: MessageFlags .. autoclass:: MessageFlags() :members: -PublicUserFlags -~~~~~~~~~~~~~~~ - .. attributetable:: PublicUserFlags .. autoclass:: PublicUserFlags() :members: +.. attributetable:: PrivateUserFlags + +.. autoclass:: PrivateUserFlags() + :members: + :inherited-members: + +.. attributetable:: MemberCacheFlags + +.. autoclass:: MemberCacheFlags() + :members: + Exceptions ------------ @@ -4252,12 +4695,14 @@ The following exceptions are thrown by the library. .. autoexception:: NotFound +.. autoexception:: CaptchaRequired + :members: + :inherited-members: + .. autoexception:: DiscordServerError .. autoexception:: InvalidData -.. autoexception:: GatewayNotFound - .. autoexception:: ConnectionClosed .. autoexception:: discord.opus.OpusError @@ -4275,8 +4720,8 @@ Exception Hierarchy - :exc:`InvalidData` - :exc:`LoginFailure` - :exc:`ConnectionClosed` - - :exc:`GatewayNotFound` - :exc:`HTTPException` - :exc:`Forbidden` - :exc:`NotFound` - :exc:`DiscordServerError` + - :exc:`CaptchaRequired` diff --git a/docs/conf.py b/docs/conf.py index bcfd0acb4..4e5522dfe 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -145,8 +145,7 @@ pygments_style = 'friendly' # Nitpicky mode options nitpick_ignore_files = [ - "migrating_to_async", - "migrating_to_v1", + "migrating_from_dpy", "migrating", "whats_new", ] diff --git a/docs/ext/commands/commands.rst b/docs/ext/commands/commands.rst index d31809f58..c329689a3 100644 --- a/docs/ext/commands/commands.rst +++ b/docs/ext/commands/commands.rst @@ -11,13 +11,6 @@ how you can arbitrarily nest groups and commands to have a rich sub-command syst Commands are defined by attaching it to a regular Python function. The command is then invoked by the user using a similar signature to the Python function. -.. warning:: - - You must have access to the :attr:`~discord.Intents.message_content` intent for the commands extension - to function. This must be set both in the developer portal and within your code. - - Failure to do this will result in your bot not responding to any of your commands. - For example, in the given command definition: .. code-block:: python3 diff --git a/docs/faq.rst b/docs/faq.rst index 81f0ce90f..79566b954 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -6,7 +6,7 @@ Frequently Asked Questions =========================== -This is a list of Frequently Asked Questions regarding using ``discord.py`` and its extension modules. Feel free to suggest a +This is a list of Frequently Asked Questions regarding using ``discord.py-self`` and its extension modules. Feel free to suggest a new question or submit one via pull requests. .. contents:: Questions @@ -81,7 +81,7 @@ General questions regarding library usage belong here. Where can I find usage examples? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Example code can be found in the `examples folder `_ +Example code can be found in the `examples folder `_ in the repository. How do I set the "Playing" status? @@ -95,8 +95,6 @@ The constructor may be used for static activities, while :meth:`Client.change_pr It is highly discouraged to use :meth:`Client.change_presence` or API calls in :func:`on_ready` as this event may be called many times while running, not just once. - There is a high chance of disconnecting if presences are changed right after connecting. - The status type (playing, listening, streaming, watching) can be set using the :class:`ActivityType` enum. For memory optimisation purposes, some activities are offered in slimmed-down versions: diff --git a/docs/index.rst b/docs/index.rst index 89f84518c..0a9e9c953 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,18 +14,20 @@ for the Discord user APIs. - Command extension to aid with bot creation - Easy to use with an object oriented design - Optimised for both speed and memory +- Selfbot detection prevention Getting started ----------------- Is this your first time using the library? This is the place to get started! +- **Migrating from discord.py:** :doc:`migrating_from_dpy` - **First steps:** :doc:`intro` | :doc:`quickstart` | :doc:`logging` - **Working with Discord:** :doc:`token` - **Examples:** Many examples are available in the :resource:`repository `. -**Obligatory note:** -Automating user accounts is against the Discord ToS. If what you are trying to do is accomplishable with a bot account, please use one. +| **Obligatory note:** +| Automating user accounts is against the Discord ToS. If what you are trying to do is accomplishable with a bot account, please use one. Getting help -------------- @@ -57,7 +59,6 @@ These pages go into great detail about everything the API can do. :maxdepth: 1 api - interactions/api discord.ext.commands API Reference discord.ext.tasks API Reference diff --git a/docs/intro.rst b/docs/intro.rst index c2a2c97ea..79c11db1a 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -110,4 +110,3 @@ A quick example to showcase how events work: client = MyClient() client.run('token') - diff --git a/docs/migrating.rst b/docs/migrating.rst index db2817bfc..9d47f39f7 100644 --- a/docs/migrating.rst +++ b/docs/migrating.rst @@ -1,762 +1,21 @@ .. currentmodule:: discord -.. _migrating: +.. _migrating_2_0: -Migrating to this library -========================== - -| This library is designed to be compatible with discord.py. -| However, the user and bot APIs are *not* the same. - -Most things bots can do, users can (in some capacity) as well. - -However, a number of things have been removed. -For example: - -- `Intents`: While the gateway technically accepts Intents for user accounts (and even modifies payloads to be a little more like bot payloads), it leads to breakage. Additionally, it's a giant waving red flag to Discord. -- `Shards`: The concept doesn't exist and is unneeded for users. -- `Guild.fetch_members`: The `/guilds/:id/members` and `/guilds/:id/members/search` endpoints instantly phone-lock your account. For more information about guild members, please read their respective section below. - -Additionally, existing payloads and headers have been heavily changed to match the Discord client. - -<<<<<<< HEAD -Guild members --------------- -| Since the concept of Intents (mostly) doesn't exist for user accounts; you just get all events, right? -| Well, yes but actually no. - -For 80% of things, events are identical to bot events. However, other than the quite large amount of new events, not all events work the same. - -The biggest example of this are the events `on_member_add`, `on_member_update`/`on_user_update`, and `on_member_remove`. - -Bots -~~~~~ -For bots (with the member intent), it's simple. - -They request all guild members with an OPCode 8 (chunk the guild), and receive respective `GUILD_MEMBER_*` events, that are then parsed by the library and dispatched to users. - -If the bot has the presence intent, it even gets an initial member cache in the `GUILD_CREATE` event. - -Users -~~~~~~ -| Users, however, do not work like this. -| If you have one of kick members, ban members, or manage roles, you can request all guild members the same way bots do. The client uses this in various areas of guild settings. - -| But, here's the twist: users do not receive `GUILD_MEMBER_*` reliably. -| They receive them in certain circumstances, but they're usually rare and nothing to be relied on. - -If the Discord client ever needs member objects for specific users, it sends an OPCode 8 with the specific user IDs/names. -This is why this is recommended if you want to fetch specific members (implemented as :func:`Guild.query_members` in the library). -The client almost never uses the :func:`Guild.fetch_member` endpoint. - -However, the maximum amount of members you can get with this method is 100 per request. - -But, you may be thinking, how does the member list work? Why can't you just utilize that? This is where it gets complicated. -First, let's make sure we understand a few things: - -- The API doesn't differentiate between offline and invisible members (for a good reason). -- The concept of a member list is not per-guild, it's per-channel. This makes sense if you think about it, since the member list only shows users that have access to a specific channel. -- The member list is always up-to-date. -- If a server has >1k members, the member list does **not** have offline members. - -The member list uses OPCode 14, and the `GUILD_MEMBER_LIST_UPDATE` event. - -One more thing you need to understand, is that the member list is lazily loaded. -You subscribe to 100 member ranges, and can subscribe to 2 per-request (needs more testing). -So, to subscribe to all available ranges, you need to spam the gateway quite a bit (especially for large guilds). - -| Once you subscribe to a range, you'll receive `GUILD_MEMBER_LIST_UPDATE` s for it whenever someone is added to it (i.e. someone joined the guild, changed their nickname so they moved in the member list alphabetically, came online, etc.), removed from it (i.e. someone left the guild, went offline, changed their nickname so they moved in the member list alphabetically), or updated in it (i.e. someone got their roles changed, or changed their nickname but remained in the same range). -| These can be parsed and dispatched as `on_member_add`, `on_member_update`/`on_user_update`, and `on_member_remove`. - -You may have already noticed a few problems with this: - -1. You'll get spammed with `member_add/remove` s whenever someone changes ranges. -2. For guilds with >1k members you don't receive offline members. So, you won't know if an offline member is kicked, or an invisible member joins/leaves. You also won't know if someone came online or joined. Or, if someone went offline or left. - -| #1 is solveable with a bit of parsing, but #2 is a huge problem. -| If you have the permissions to request all guild members, you can combine that with member list scraping and get a *decent* local member cache. However, because of the nature of this (and the fact that you'll have to request all guild membesr again every so often), accurate events are nearly impossible. - -Additionally, there are more caveats: - -1. `GUILD_MEMBER_LIST_UPDATE` removes provide an index, not a user ID. The index starts at 0 from the top of the member list and includes hoisted roles. -2. For large servers, you get ratelimited pretty fast, so scraping can take over half an hour. -3. The scraping has to happen every time the bot starts. This not only slows things down, but *may* make Discord suspicious. -4. Remember that member lists are per-channel? Well, that means you can only subscribe all members that can *see* the channel you're subscribing too. - -#1 is again solveable with a bit of parsing. There's not much you can do about #2 and #3. But, to solve #4, you *can* subscribe to multiple channels. Although, that will probably have problems of its own. - -There are a few more pieces of the puzzle: - -<<<<<<< HEAD - async def on_member_ban(member) - -After: :: - - async def on_member_ban(guild, user) - -As part of the change, the event can either receive a :class:`User` or :class:`Member`. To help in the cases that have -:class:`User`, the :class:`Guild` is provided as the first parameter. - -The ``on_channel_`` events have received a type level split (see :ref:`migrating_1_0_channel_split`). - -Before: - -- ``on_channel_delete`` -- ``on_channel_create`` -- ``on_channel_update`` - -After: - -- :func:`on_guild_channel_delete` -- :func:`on_guild_channel_create` -- :func:`on_guild_channel_update` -- :func:`on_private_channel_delete` -- :func:`on_private_channel_create` -- :func:`on_private_channel_update` - -The ``on_guild_channel_`` events correspond to :class:`abc.GuildChannel` being updated (i.e. :class:`TextChannel` -and :class:`VoiceChannel`) and the ``on_private_channel_`` events correspond to :class:`abc.PrivateChannel` being -updated (i.e. :class:`DMChannel` and :class:`GroupChannel`). - -.. _migrating_1_0_voice: - -Voice Changes ---------------- - -Voice sending has gone through a complete redesign. - -In particular: - -- Connection is done through :meth:`VoiceChannel.connect` instead of ``Client.join_voice_channel``. -- You no longer create players and operate on them (you no longer store them). -- You instead request :class:`VoiceClient` to play an :class:`AudioSource` via :meth:`VoiceClient.play`. -- There are different built-in :class:`AudioSource`\s. - - - :class:`FFmpegPCMAudio` is the equivalent of ``create_ffmpeg_player`` - -- create_ffmpeg_player/create_stream_player/create_ytdl_player have all been removed. - - - The goal is to create :class:`AudioSource` instead. - -- Using :meth:`VoiceClient.play` will not return an ``AudioPlayer``. - - - Instead, it's "flattened" like :class:`User` -> :class:`Member` is. - -- The ``after`` parameter now takes a single parameter (the error). - -Basically: - -Before: :: - - vc = await client.join_voice_channel(channel) - player = vc.create_ffmpeg_player('testing.mp3', after=lambda: print('done')) - player.start() - - player.is_playing() - player.pause() - player.resume() - player.stop() - # ... - -After: :: - - vc = await channel.connect() - vc.play(discord.FFmpegPCMAudio('testing.mp3'), after=lambda e: print('done', e)) - vc.is_playing() - vc.pause() - vc.resume() - vc.stop() - # ... - -With the changed :class:`AudioSource` design, you can now change the source that the :class:`VoiceClient` is -playing at runtime via :attr:`VoiceClient.source`. - -For example, you can add a :class:`PCMVolumeTransformer` to allow changing the volume: :: - - vc.source = discord.PCMVolumeTransformer(vc.source) - vc.source.volume = 0.6 - -An added benefit of the redesign is that it will be much more resilient towards reconnections: - -- The voice websocket will now automatically re-connect and re-do the handshake when disconnected. -- The initial connect handshake will now retry up to 5 times so you no longer get as many ``asyncio.TimeoutError``. -- Audio will now stop and resume when a disconnect is found. - - - This includes changing voice regions etc. - - -.. _migrating_1_0_wait_for: - -Waiting For Events --------------------- - -Prior to v1.0, the machinery for waiting for an event outside of the event itself was done through two different -functions, ``Client.wait_for_message`` and ``Client.wait_for_reaction``. One problem with one such approach is that it did -not allow you to wait for events outside of the ones provided by the library. - -In v1.0 the concept of waiting for another event has been generalised to work with any event as :meth:`Client.wait_for`. - -For example, to wait for a message: :: - - # before - msg = await client.wait_for_message(author=message.author, channel=message.channel) - - # after - def pred(m): - return m.author == message.author and m.channel == message.channel - - msg = await client.wait_for('message', check=pred) - -To facilitate multiple returns, :meth:`Client.wait_for` returns either a single argument, no arguments, or a tuple of -arguments. - -For example, to wait for a reaction: :: - - reaction, user = await client.wait_for('reaction_add', check=lambda r, u: u.id == 176995180300206080) - - # use user and reaction - -Since this function now can return multiple arguments, the ``timeout`` parameter will now raise a :exc:`asyncio.TimeoutError` -when reached instead of setting the return to ``None``. For example: - -.. code-block:: python3 +Migrating to v2.0 +====================== - def pred(m): - return m.author == message.author and m.channel == message.channel +Compared to v1.0, v2.0 mostly has breaking changes related to better developer experience and API coverage. +While the changes aren't as massive to require an entire rewrite, there are still many changes that need to be accounted for. - try: +This is the first version to have version guarantees apply. - msg = await client.wait_for('message', check=pred, timeout=60.0) - except asyncio.TimeoutError: - await channel.send('You took too long...') - else: - await channel.send('You said {0.content}, {0.author}.'.format(msg)) +Below is a **non-exhaustive** list of changes. -Upgraded Dependencies +Python Version Change ----------------------- -Following v1.0 of the library, we've updated our requirements to :doc:`aiohttp ` v2.0 or higher. - -Since this is a backwards incompatible change, it is recommended that you see the -`changes `_ -and the :doc:`aio:migration_to_2xx` pages for details on the breaking changes in -:doc:`aiohttp `. - -Of the most significant for common users is the removal of helper functions such as: - -- ``aiohttp.get`` -- ``aiohttp.post`` -- ``aiohttp.delete`` -- ``aiohttp.patch`` -- ``aiohttp.head`` -- ``aiohttp.put`` -- ``aiohttp.request`` - -It is recommended that you create a session instead: :: - - async with aiohttp.ClientSession() as sess: - async with sess.get('url') as resp: - # work with resp - -Since it is better to not create a session for every request, you should store it in a variable and then call -``session.close`` on it when it needs to be disposed. - -Sharding ----------- - -The library has received significant changes on how it handles sharding and now has sharding as a first-class citizen. - -If using a Bot account and you want to shard your bot in a single process then you can use the :class:`AutoShardedClient`. - -This class allows you to use sharding without having to launch multiple processes or deal with complicated IPC. - -It should be noted that **the sharded client does not support user accounts**. This is due to the changes in connection -logic and state handling. - -Usage is as simple as doing: :: - - client = discord.AutoShardedClient() - -instead of using :class:`Client`. - -This will launch as many shards as your bot needs using the ``/gateway/bot`` endpoint, which allocates about 1000 guilds -per shard. - -If you want more control over the sharding you can specify ``shard_count`` and ``shard_ids``. :: - - # launch 10 shards regardless - client = discord.AutoShardedClient(shard_count=10) - - # launch specific shard IDs in this process - client = discord.AutoShardedClient(shard_count=10, shard_ids=(1, 2, 5, 6)) - -For users of the command extension, there is also :class:`~ext.commands.AutoShardedBot` which behaves similarly. - -Connection Improvements -------------------------- - -In v1.0, the auto reconnection logic has been powered up significantly. - -:meth:`Client.connect` has gained a new keyword argument, ``reconnect`` that defaults to ``True`` which controls -the reconnect logic. When enabled, the client will automatically reconnect in all instances of your internet going -offline or Discord going offline with exponential back-off. - -:meth:`Client.run` and :meth:`Client.start` gains this keyword argument as well, but for most cases you will not -need to specify it unless turning it off. - -.. _migrating_1_0_commands: - -Command Extension Changes --------------------------- - -Due to the :ref:`migrating_1_0_model_state` changes, some of the design of the extension module had to -undergo some design changes as well. - -Context Changes -~~~~~~~~~~~~~~~~~ - -In v1.0, the :class:`.Context` has received a lot of changes with how it's retrieved and used. - -The biggest change is that ``pass_context=True`` no longer exists, :class:`.Context` is always passed. Ergo: - -.. code-block:: python3 - - # before - @bot.command() - async def foo(): - await bot.say('Hello') - - # after - @bot.command() - async def foo(ctx): - await ctx.send('Hello') - -The reason for this is because :class:`~ext.commands.Context` now meets the requirements of :class:`abc.Messageable`. This -makes it have similar functionality to :class:`TextChannel` or :class:`DMChannel`. Using :meth:`~.Context.send` -will either DM the user in a DM context or send a message in the channel it was in, similar to the old ``bot.say`` -functionality. The old helpers have been removed in favour of the new :class:`abc.Messageable` interface. See -:ref:`migrating_1_0_removed_helpers` for more information. - -Since the :class:`~ext.commands.Context` is now passed by default, several shortcuts have been added: - -**New Shortcuts** - -- :attr:`ctx.author ` is a shortcut for ``ctx.message.author``. -- :attr:`ctx.guild ` is a shortcut for ``ctx.message.guild``. -- :attr:`ctx.channel ` is a shortcut for ``ctx.message.channel``. -- :attr:`ctx.me ` is a shortcut for ``ctx.message.guild.me`` or ``ctx.bot.user``. -- :attr:`ctx.voice_client ` is a shortcut for ``ctx.message.guild.voice_client``. - -**New Functionality** - -- :meth:`.Context.reinvoke` to invoke a command again. - - - This is useful for bypassing cooldowns. -- :attr:`.Context.valid` to check if a context can be invoked with :meth:`.Bot.invoke`. -- :meth:`.Context.send_help` to show the help command for an entity using the new :class:`~.ext.commands.HelpCommand` system. - - - This is useful if you want to show the user help if they misused a command. - -Subclassing Context -++++++++++++++++++++ - -In v1.0, there is now the ability to subclass :class:`~ext.commands.Context` and use it instead of the default -provided one. - -For example, if you want to add some functionality to the context: - -.. code-block:: python3 - - class MyContext(commands.Context): - @property - def secret(self): - return 'my secret here' - -Then you can use :meth:`~ext.commands.Bot.get_context` inside :func:`on_message` with combination with -:meth:`~ext.commands.Bot.invoke` to use your custom context: - -.. code-block:: python3 - - class MyBot(commands.Bot): - async def on_message(self, message): - ctx = await self.get_context(message, cls=MyContext) - await self.invoke(ctx) - -Now inside your commands you will have access to your custom context: - -.. code-block:: python3 - - @bot.command() - async def secret(ctx): - await ctx.send(ctx.secret) - -.. _migrating_1_0_removed_helpers: - -Removed Helpers -+++++++++++++++++ - -With the new :class:`.Context` changes, a lot of message sending helpers have been removed. - -For a full list of changes, see below: - -+-----------------+------------------------------------------------------------+ -| Before | After | -+-----------------+------------------------------------------------------------+ -| ``Bot.say`` | :meth:`.Context.send` | -+-----------------+------------------------------------------------------------+ -| ``Bot.upload`` | :meth:`.Context.send` | -+-----------------+------------------------------------------------------------+ -| ``Bot.whisper`` | ``ctx.author.send`` | -+-----------------+------------------------------------------------------------+ -| ``Bot.type`` | :meth:`.Context.typing` or :meth:`.Context.trigger_typing` | -+-----------------+------------------------------------------------------------+ -| ``Bot.reply`` | No replacement. | -+-----------------+------------------------------------------------------------+ - -Command Changes -~~~~~~~~~~~~~~~~~ - -As mentioned earlier, the first command change is that ``pass_context=True`` no longer -exists, so there is no need to pass this as a parameter. - -Another change is the removal of ``no_pm=True``. Instead, use the new :func:`~ext.commands.guild_only` built-in -check. - -The ``commands`` attribute of :class:`~ext.commands.Bot` and :class:`~ext.commands.Group` have been changed from a -dictionary to a set that does not have aliases. To retrieve the previous dictionary behaviour, use ``all_commands`` instead. - -Command instances have gained new attributes and properties: - -1. :attr:`~ext.commands.Command.signature` to get the signature of the command. -2. :attr:`~ext.commands.Command.usage`, an attribute to override the default signature. -3. :attr:`~ext.commands.Command.root_parent` to get the root parent group of a subcommand. - -For :class:`~ext.commands.Group` and :class:`~ext.commands.Bot` the following changed: - -- Changed :attr:`~.GroupMixin.commands` to be a :class:`set` without aliases. - - - Use :attr:`~.GroupMixin.all_commands` to get the old :class:`dict` with all commands. - -Check Changes -~~~~~~~~~~~~~~~ - -Prior to v1.0, :func:`~ext.commands.check`\s could only be synchronous. As of v1.0 checks can now be coroutines. - -Along with this change, a couple new checks were added. - -- :func:`~ext.commands.guild_only` replaces the old ``no_pm=True`` functionality. -- :func:`~ext.commands.is_owner` uses the :meth:`Client.application_info` endpoint by default to fetch owner ID. - - - This is actually powered by a different function, :meth:`~ext.commands.Bot.is_owner`. - - You can set the owner ID yourself by setting :attr:`.Bot.owner_id`. - -- :func:`~ext.commands.is_nsfw` checks if the channel the command is in is a NSFW channel. - - - This is powered by the new :meth:`TextChannel.is_nsfw` method. - -Event Changes -~~~~~~~~~~~~~~~ - -All command extension events have changed. - -Before: :: - - on_command(command, ctx) - on_command_completion(command, ctx) - on_command_error(error, ctx) - -After: :: - - on_command(ctx) - on_command_completion(ctx) - on_command_error(ctx, error) - -The extraneous ``command`` parameter in :func:`.on_command` and :func:`.on_command_completion` -have been removed. The :class:`~ext.commands.Command` instance was not kept up-to date so it was incorrect. In order to get -the up to date :class:`~ext.commands.Command` instance, use the :attr:`.Context.command` -attribute. - -The error handlers, either :meth:`~ext.commands.Command.error` or :func:`.on_command_error`, -have been re-ordered to use the :class:`~ext.commands.Context` as its first parameter to be consistent with other events -and commands. - -HelpFormatter and Help Command Changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``HelpFormatter`` class has been removed. It has been replaced with a :class:`~.commands.HelpCommand` class. This class now stores all the command handling and processing of the help command. - -The help command is now stored in the :attr:`.Bot.help_command` attribute. As an added extension, you can disable the help command completely by assigning the attribute to ``None`` or passing it at ``__init__`` as ``help_command=None``. - -The new interface allows the help command to be customised through special methods that can be overridden. - -- :meth:`.HelpCommand.send_bot_help` - - Called when the user requested for help with the entire bot. -- :meth:`.HelpCommand.send_cog_help` - - Called when the user requested for help with a specific cog. -- :meth:`.HelpCommand.send_group_help` - - Called when the user requested for help with a :class:`~.commands.Group` -- :meth:`.HelpCommand.send_command_help` - - Called when the user requested for help with a :class:`~.commands.Command` -- :meth:`.HelpCommand.get_destination` - - Called to know where to send the help messages. Useful for deciding whether to DM or not. -- :meth:`.HelpCommand.command_not_found` - - A function (or coroutine) that returns a presentable no command found string. -- :meth:`.HelpCommand.subcommand_not_found` - - A function (or coroutine) that returns a string when a subcommand is not found. -- :meth:`.HelpCommand.send_error_message` - - A coroutine that gets passed the result of :meth:`.HelpCommand.command_not_found` and :meth:`.HelpCommand.subcommand_not_found`. - - By default it just sends the message. But you can, for example, override it to put it in an embed. -- :meth:`.HelpCommand.on_help_command_error` - - The :ref:`error handler ` for the help command if you want to add one. -- :meth:`.HelpCommand.prepare_help_command` - - A coroutine that is called right before the help command processing is done. - -Certain subclasses can implement more customisable methods. - -The old ``HelpFormatter`` was replaced with :class:`~.commands.DefaultHelpCommand`\, which implements all of the logic of the old help command. The customisable methods can be found in the accompanying documentation. - -The library now provides a new more minimalistic :class:`~.commands.HelpCommand` implementation that doesn't take as much space, :class:`~.commands.MinimalHelpCommand`. The customisable methods can also be found in the accompanying documentation. - -A frequent request was if you could associate a help command with a cog. The new design allows for dynamically changing of cog through binding it to the :attr:`.HelpCommand.cog` attribute. After this assignment the help command will pretend to be part of the cog and everything should work as expected. When the cog is unloaded then the help command will be "unbound" from the cog. - -For example, to implement a :class:`~.commands.HelpCommand` in a cog, the following snippet can be used. - -.. code-block:: python3 - - class MyHelpCommand(commands.MinimalHelpCommand): - def get_command_signature(self, command): - return '{0.clean_prefix}{1.qualified_name} {1.signature}'.format(self, command) - - class MyCog(commands.Cog): - def __init__(self, bot): - self._original_help_command = bot.help_command - bot.help_command = MyHelpCommand() - bot.help_command.cog = self - - def cog_unload(self): - self.bot.help_command = self._original_help_command - -For more information, check out the relevant :ref:`documentation `. - -Cog Changes -~~~~~~~~~~~~~ - -Cogs have completely been revamped. They are documented in :ref:`ext_commands_cogs` as well. - -Cogs are now required to have a base class, :class:`~.commands.Cog` for future proofing purposes. This comes with special methods to customise some behaviour. - -* :meth:`.Cog.cog_unload` - - This is called when a cog needs to do some cleanup, such as cancelling a task. -* :meth:`.Cog.bot_check_once` - - This registers a :meth:`.Bot.check_once` check. -* :meth:`.Cog.bot_check` - - This registers a regular :meth:`.Bot.check` check. -* :meth:`.Cog.cog_check` - - This registers a check that applies to every command in the cog. -* :meth:`.Cog.cog_command_error` - - This is a special error handler that is called whenever an error happens inside the cog. -* :meth:`.Cog.cog_before_invoke` and :meth:`.Cog.cog_after_invoke` - - A special method that registers a cog before and after invoke hook. More information can be found in :ref:`migrating_1_0_before_after_hook`. - -Those that were using listeners, such as ``on_message`` inside a cog will now have to explicitly mark them as such using the :meth:`.commands.Cog.listener` decorator. - -Along with that, cogs have gained the ability to have custom names through specifying it in the class definition line. More options can be found in the metaclass that facilitates all this, :class:`.commands.CogMeta`. - -An example cog with every special method registered and a custom name is as follows: - -.. code-block:: python3 - - class MyCog(commands.Cog, name='Example Cog'): - def cog_unload(self): - print('cleanup goes here') - - def bot_check(self, ctx): - print('bot check') - return True - - def bot_check_once(self, ctx): - print('bot check once') - return True - - async def cog_check(self, ctx): - print('cog local check') - return await ctx.bot.is_owner(ctx.author) - - async def cog_command_error(self, ctx, error): - print('Error in {0.command.qualified_name}: {1}'.format(ctx, error)) - - async def cog_before_invoke(self, ctx): - print('cog local before: {0.command.qualified_name}'.format(ctx)) - - async def cog_after_invoke(self, ctx): - print('cog local after: {0.command.qualified_name}'.format(ctx)) - - @commands.Cog.listener() - async def on_message(self, message): - pass - - -.. _migrating_1_0_before_after_hook: - -Before and After Invocation Hooks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Commands have gained new before and after invocation hooks that allow you to do an action before and after a command is -run. - -They take a single parameter, :class:`~ext.commands.Context` and they must be a coroutine. - -They are on a global, per-cog, or per-command basis. - -Basically: :: - - - # global hooks: - - @bot.before_invoke - async def before_any_command(ctx): - # do something before a command is called - pass - - @bot.after_invoke - async def after_any_command(ctx): - # do something after a command is called - pass - -The after invocation is hook always called, **regardless of an error in the command**. This makes it ideal for some error -handling or clean up of certain resources such a database connection. - -The per-command registration is as follows: :: - - @bot.command() - async def foo(ctx): - await ctx.send('foo') - - @foo.before_invoke - async def before_foo_command(ctx): - # do something before the foo command is called - pass - - @foo.after_invoke - async def after_foo_command(ctx): - # do something after the foo command is called - pass - -The special cog method for these is :meth:`.Cog.cog_before_invoke` and :meth:`.Cog.cog_after_invoke`, e.g.: - -.. code-block:: python3 - - class MyCog(commands.Cog): - async def cog_before_invoke(self, ctx): - ctx.secret_cog_data = 'foo' - - async def cog_after_invoke(self, ctx): - print('{0.command} is done...'.format(ctx)) - - @commands.command() - async def foo(self, ctx): - await ctx.send(ctx.secret_cog_data) - -To check if a command failed in the after invocation hook, you can use -:attr:`.Context.command_failed`. - -The invocation order is as follows: - -1. Command local before invocation hook -2. Cog local before invocation hook -3. Global before invocation hook -4. The actual command -5. Command local after invocation hook -6. Cog local after invocation hook -7. Global after invocation hook - -Converter Changes -~~~~~~~~~~~~~~~~~~~ - -Prior to v1.0, a converter was a type hint that could be a callable that could be invoked -with a singular argument denoting the argument passed by the user as a string. - -This system was eventually expanded to support a :class:`~ext.commands.Converter` system to -allow plugging in the :class:`~ext.commands.Context` and do more complicated conversions such -as the built-in "discord" converters. - -In v1.0 this converter system was revamped to allow instances of :class:`~ext.commands.Converter` derived -classes to be passed. For consistency, the :meth:`~ext.commands.Converter.convert` method was changed to -always be a coroutine and will now take the two arguments as parameters. - -Essentially, before: :: - - class MyConverter(commands.Converter): - def convert(self): - return self.ctx.message.server.me - -After: :: - - class MyConverter(commands.Converter): - async def convert(self, ctx, argument): - return ctx.me - -The command framework also got a couple new converters: - -- :class:`~ext.commands.clean_content` this is akin to :attr:`Message.clean_content` which scrubs mentions. -- :class:`~ext.commands.UserConverter` will now appropriately convert :class:`User` only. -- ``ChannelConverter`` is now split into two different converters. - - - :class:`~ext.commands.TextChannelConverter` for :class:`TextChannel`. - - :class:`~ext.commands.VoiceChannelConverter` for :class:`VoiceChannel`. -======= -- There is a `/guilds/:id/roles/:id/member-ids` endpoint that provides up to 100 member IDs for any role other than the default role. You can use :func:`Guild.query_members` to fetch all these members in one go. -- With OPCode 14, you can subscribe to certain member IDs and receive presence updates for them. The limit of IDs per-request is currently unknown, but I have witnessed the client send over 200/request. This may help with the offline members issue. -- Thread member lists do *not* work the same. You just send an OPCode 14 with the thread IDs and receive a `THREAD_MEMBER_LIST_UPDATE` with all the members. The cache then stays updated with `GUILD_MEMBER_UPDATE` and `THREAD_MEMBERS_UPDATE` events. -- OPCode 14 lets you subscribe to multiple channels at once, and you *might* be able to do more than 2 ranges at once. ->>>>>>> rebase -======= -Logging on with a user token is against the Discord `Terms of Service `_ -and as such all support for user-only endpoints has been removed. - -The following have been removed: - -- ``bot`` parameter to :meth:`Client.login` and :meth:`Client.start` -- ``afk`` parameter to :meth:`Client.change_presence` -- ``password``, ``new_password``, ``email``, and ``house`` parameters to :meth:`ClientUser.edit` -- ``CallMessage`` model -- ``GroupCall`` model -- ``Profile`` model -- ``Relationship`` model -- ``RelationshipType`` enumeration -- ``HypeSquadHouse`` enumeration -- ``PremiumType`` enumeration -- ``UserContentFilter`` enumeration -- ``FriendFlags`` enumeration -- ``Theme`` enumeration -- ``on_relationship_add`` event -- ``on_relationship_remove`` event -- ``on_relationship_update`` event -- ``Client.fetch_user_profile`` method -- ``ClientUser.create_group`` method -- ``ClientUser.edit_settings`` method -- ``ClientUser.get_relationship`` method -- ``GroupChannel.add_recipients`` method -- ``GroupChannel.remove_recipients`` method -- ``GroupChannel.edit`` method -- ``Guild.ack`` method -- ``Message.ack`` method -- ``User.block`` method -- ``User.is_blocked`` method -- ``User.is_friend`` method -- ``User.profile`` method -- ``User.remove_friend`` method -- ``User.send_friend_request`` method -- ``User.unblock`` method -- ``ClientUser.blocked`` attribute -- ``ClientUser.email`` attribute -- ``ClientUser.friends`` attribute -- ``ClientUser.premium`` attribute -- ``ClientUser.premium_type`` attribute -- ``ClientUser.relationships`` attribute -- ``Message.call`` attribute -- ``User.mutual_friends`` attribute -- ``User.relationship`` attribute +In order to ease development, maintain security updates, and use newer features **v2.0 drops support for Python 3.7 and earlier**. .. _migrating_2_0_client_async_setup: @@ -765,7 +24,7 @@ asyncio Event Loop Changes Python 3.7 introduced a new helper function :func:`asyncio.run` which automatically creates and destroys the asynchronous event loop. -In order to support this, the way discord.py handles the :mod:`asyncio` event loop has changed. +In order to support this, the way discord.py-self handles the :mod:`asyncio` event loop has changed. This allows you to rather than using :meth:`Client.run` create your own asynchronous loop to setup other asynchronous code as needed. @@ -808,29 +67,6 @@ With this change, constructor of :class:`Client` no longer accepts ``connector`` In parallel with this change, changes were made to loading and unloading of commands extension extensions and cogs, see :ref:`migrating_2_0_commands_extension_cog_async` for more information. -Intents Are Now Required --------------------------- - -In earlier versions, the ``intents`` keyword argument was optional and defaulted to :meth:`Intents.default`. In order to better educate users on their intents and to also make it more explicit, this parameter is now required to pass in. - -For example: - -.. code-block:: python3 - - # before - client = discord.Client() - - # after - intents = discord.Intents.default() - client = discord.Client(intents=intents) - -This change applies to **all** subclasses of :class:`Client`. - -- :class:`AutoShardedClient` -- :class:`~discord.ext.commands.Bot` -- :class:`~discord.ext.commands.AutoShardedBot` - - Abstract Base Classes Changes ------------------------------- @@ -1230,7 +466,7 @@ The main differences between text channels and threads are: - :attr:`Thread.created_at` of threads created before 10 January 2022 is ``None``. - :attr:`Thread.members` is of type List[:class:`ThreadMember`] rather than List[:class:`Member`] - - Most of the time, this data is not provided and a call to :meth:`Thread.fetch_members` is needed. + - Most of the time, this data is not provided and a call to :meth:`Thread.fetch_members` to fetch the partial objects is needed. For convenience, :class:`Thread` has a set of properties and methods that return the information about the parent channel: @@ -1343,6 +579,7 @@ The following have been changed: - Note that this method will return ``None`` instead of :class:`VoiceChannel` if the edit was only positional. - :meth:`ClientUser.edit` +- :meth:`ClientUser.edit_settings` - :meth:`Emoji.edit` - :meth:`Guild.edit` - :meth:`Message.edit` @@ -1635,7 +872,6 @@ This removes the following: - ``StoreChannel`` - ``commands.StoreChannelConverter`` -- ``ChannelType.store`` Change in ``Guild.bans`` endpoint ----------------------------------- @@ -1658,7 +894,6 @@ Function Signature Changes Parameters in the following methods are now all positional-only: -- :meth:`AutoShardedClient.get_shard` - :meth:`Client.get_channel` - :meth:`Client.fetch_channel` - :meth:`Guild.get_channel` @@ -1739,7 +974,6 @@ The following changes have been made: - :attr:`DMChannel.recipient` may now be ``None``. - :meth:`Guild.vanity_invite` may now be ``None``. This has been done to fix an issue with the method returning a broken :class:`Invite` object. - :meth:`Widget.fetch_invite` may now be ``None``. -- :attr:`Guild.shard_id` is now ``0`` instead of ``None`` if :class:`AutoShardedClient` is not used. - :attr:`Guild.mfa_level` is now of type :class:`MFALevel`. - :attr:`Guild.member_count` is now of type Optional[:class:`int`]. - :attr:`AuditLogDiff.mfa_level` is now of type :class:`MFALevel`. @@ -1806,6 +1040,10 @@ The following have been removed: - The current API version no longer provides this functionality. Use ``intents`` parameter instead. +- ``guild_subscription_options`` parameter from :class:`Client` constructor + + - The auto-subscribing system has been removed. ``chunk_guilds_at_startup`` is now utilised properly. + - :class:`VerificationLevel` aliases: - ``VerificationLevel.table_flip`` - use :attr:`VerificationLevel.high` instead. @@ -2087,11 +1325,11 @@ The following parameters are now positional-only: - ``name`` in :meth:`ext.commands.GroupMixin.get_command` - ``name`` in :meth:`ext.commands.GroupMixin.remove_command` -The following parameters have been removed: +The following parameters have been added: -- ``self_bot`` from :class:`~ext.commands.Bot` +- ``user_bot`` in :class:`~ext.commands.Bot` - - This has been done due to the :ref:`migrating_2_0_userbot_removal` changes. + - Allows your bot to reply to everyone's message. The library now less often uses ``None`` as the default value for function/method parameters. @@ -2149,9 +1387,3 @@ Tasks Extension Changes - Calling :meth:`ext.tasks.Loop.change_interval` now changes the interval for the sleep time right away, rather than on the next loop iteration. - ``loop`` parameter in :func:`ext.tasks.loop` can no longer be ``None``. - -Migrating to v1.0 -====================== - -The contents of that migration has been moved to :ref:`migrating_1_0`. ->>>>>>> upstream/master diff --git a/docs/migrating_from_dpy.rst b/docs/migrating_from_dpy.rst new file mode 100644 index 000000000..bbfcb497b --- /dev/null +++ b/docs/migrating_from_dpy.rst @@ -0,0 +1,101 @@ +.. currentmodule:: discord + +.. _migrating_from_dpy: + +Migrating to this library +========================== + +| This library is designed to be compatible with discord.py. +| However, the user and bot APIs are *not* the same. + +Most things bots can do, users can (in some capacity) as well. + +However, a number of things have been removed. +For example: + +- ``Intents``: While the gateway technically accepts Intents for user accounts (and even modifies payloads to be a little more like bot payloads), it leads to breakage. Additionally, it's a giant waving red flag to Discord. +- ``Shards``: Again, technically accepted but useless. +- ``discord.ui``: Users cannot send items from the bot UI kit. +- ``discord.app_commands``: Users cannot register application commands. + +Additionally, existing payloads and headers have been heavily changed to match the Discord client. + +Guild members +-------------- +| Since the concept of Intents (mostly) doesn't exist for user accounts; you just get all events, right? +| Well, yes but actually no. + +For 80% of things, events are identical to bot events. However, other than the quite large amount of new events, not all events work the same. + +The biggest example of this are the events ``on_member_add``, ``on_member_update``\/``on_user_update``, ``on_member_remove``, and ``on_presence_update``. + +Bots +~~~~~ +For bots (with the member intent), it's simple. + +They request all guild members with an OPCode 8 (chunk the guild), and receive respective ``GUILD_MEMBER_*`` events, that are then parsed by the library and dispatched to users. + +If the bot has the presence intent, it even gets an initial member cache in the ``GUILD_CREATE`` event and receives ``PRESENCE_UPDATE``. + +Users +~~~~~~ +| Users, however, do not work like this. +| If you have one of kick members, ban members, or manage roles, you can request all guild members the same way bots do. The client uses this in various areas of guild settings. + +| But, here's the twist: users do not receive ``GUILD_MEMBER_*`` reliably. +| They receive them in certain circumstances (such as when subscribing to updates for specific users), but they're usually rare and nothing to be relied on. + +If the Discord client ever needs member objects for specific users, it sends an OPCode 8 with the specific user IDs/names. +This is why this is recommended if you want to fetch specific members (implemented as :func:``Guild.query_members`` in the library). + +However, the maximum amount of members you can get with this method is 100 per request. + +But, you may be thinking, how does the member sidebar work? Why can't you just utilize that? This is where it gets complicated. +First, let's make sure we understand a few things: + +- The API doesn't differentiate between offline and invisible members (for a good reason). +- The concept of a member sidebar is not per-guild, it's per-channel. This makes sense if you think about it, since the member sidebar only shows users that have access to a specific channel. +- The member sidebar is always up-to-date. +- If a server has >1,000 members, the member sidebar does **not** have offline members. + +The member sidebar uses OPCode 14, and the ``GUILD_MEMBER_LIST_UPDATE`` event. + +One more thing you need to understand, is that the member sidebar is lazily loaded. +You usually subscribe to 100 member ranges, and can subscribe to 5 per-channel per-request (up to 5 channels a request). +Additionally, if the guild's member count is under 75,000 members, you can subscribe to 400 member ranges instead. + +So, to subscribe to all available ranges, you need to spam the gateway quite a bit (especially for large guilds). +Additionally, while you can subscribe to 5 channels/request, the channels need to have the same permissions, or you'll be subscribing to two different lists (not ideal). + +| Once you subscribe to a range, you'll receive ``GUILD_MEMBER_LIST_UPDATE`` s for it whenever someone is added to it (i.e. someone joined the guild, changed their nickname so they moved in the member list alphabetically, came online, etc.), removed from it (i.e. someone left the guild, went offline, changed their nickname so they moved in the member sidebar alphabetically), or updated in it (i.e. someone got their roles changed, or changed their nickname but remained in the same position). +| These can be parsed and dispatched as ``on_member_add``, ``on_member_update``\/``on_user_update``, ``on_member_remove``, and ``on_presence_update``. + +You may have already noticed a few problems with this: + +1. You'll get spammed with ``member_add/remove``s whenever someone changes position in the member sidebar. +2. For guilds with >1,000 members you don't receive offline members. So, you won't know if an offline member is kicked, or an invisible member joins/leaves. You also won't know if someone came online or joined. Or, if someone went offline or left. + +| #1 is mostly solveable with a bit of parsing, but #2 is a huge problem. +| If you have the permissions to request all guild members, you can combine that with member sidebar scraping and get a *decent* local member cache. However, because of the nature of this (and the fact that you'll have to request all guild membesr again every so often), accurate events are nearly impossible. + +Additionally, there are more caveats: + +1. ``GUILD_MEMBER_LIST_UPDATE`` removes provide an index, not a user ID. The index starts at 0 from the top of the member sidebar and includes hoisted roles. +2. You can get ratelimited pretty fast, so scraping can take minutes for extremely large guilds. +3. The scraping has to happen every time the bot starts. This not only slows things down, but *may* make Discord suspicious. +4. Remember that member sidebars are per-channel? Well, that means you can only subscribe all members that can *see* the channel(s) you're subscribing too. + +#1 is again solveable with a bit of parsing. There's not much you can do about #2 and #3. But, to solve #4, you *can* subscribe to multiple channels (which has problems of its own and makes events virtually impossible). + +There are a few more pieces of the puzzle: + +- There is a ``/guilds/:id/roles/:id/member-ids`` endpoint that provides up to 100 member IDs for any role other than the default role. You can use :func:``Guild.query_members`` to fetch all these members in one go. +- With OPCode 14, you can subscribe to certain member IDs and receive member/presence updates for them. The limit of IDs per-request is currently unknown, but I have witnessed the client send over 200/request. +- Thread member sidebars do *not* work the same. You just send an OPCode 14 with the thread IDs and receive a ``THREAD_MEMBER_LIST_UPDATE`` with all the members. The cache then stays updated with ``GUILD_MEMBER_UPDATE`` and ``THREAD_MEMBERS_UPDATE`` events. + +Implementation +~~~~~~~~~~~~~~~ +The library offers two avenues to get the "entire" member list of a guild. + +- :func:`Guild.chunk`: If a guild has less than 1,000 members, and has at least one channel that everyone can view, you can use this method to fetch the entire member list by scraping the member sidebar. With this method, you also get events. +- :func:`Guild.fetch_members`: If you have the permissions to request all guild members, you can use this method to fetch the entire member list. Else, this method scrapes the member sidebar (which can become very slow), this only returns online members if the guild has more than 1,000 members. This method does not get events. diff --git a/docs/migrating_to_v1.rst b/docs/migrating_to_v1.rst deleted file mode 100644 index 4a1a50030..000000000 --- a/docs/migrating_to_v1.rst +++ /dev/null @@ -1,1174 +0,0 @@ -:orphan: - -.. currentmodule:: discord - -.. _migrating_1_0: - -Migrating to v1.0 -====================== - -v1.0 is one of the biggest breaking changes in the library due to a complete -redesign. - -The amount of changes are so massive and long that for all intents and purposes, it is a completely -new library. - -Part of the redesign involves making things more easy to use and natural. Things are done on the -:ref:`models ` instead of requiring a :class:`Client` instance to do any work. - -Python Version Change ------------------------ - -In order to make development easier and also to allow for our dependencies to upgrade to allow usage of 3.7 or higher, -the library had to remove support for Python versions lower than 3.5.3, which essentially means that **support for Python 3.4 -is dropped**. - -Major Model Changes ---------------------- - -Below are major model changes that have happened in v1.0 - -Snowflakes are int -~~~~~~~~~~~~~~~~~~~~ - -Before v1.0, all snowflakes (the ``id`` attribute) were strings. This has been changed to :class:`int`. - -Quick example: :: - - # before - ch = client.get_channel('84319995256905728') - if message.author.id == '80528701850124288': - ... - - # after - ch = client.get_channel(84319995256905728) - if message.author.id == 80528701850124288: - ... - -This change allows for fewer errors when using the Copy ID feature in the official client since you no longer have -to wrap it in quotes and allows for optimisation opportunities by allowing ETF to be used instead of JSON internally. - -Server is now Guild -~~~~~~~~~~~~~~~~~~~~~ - -The official API documentation calls the "Server" concept a "Guild" instead. In order to be more consistent with the -API documentation when necessary, the model has been renamed to :class:`Guild` and all instances referring to it has -been changed as well. - -A list of changes is as follows: - -+-------------------------------+----------------------------------+ -| Before | After | -+-------------------------------+----------------------------------+ -| ``Message.server`` | :attr:`Message.guild` | -+-------------------------------+----------------------------------+ -| ``Channel.server`` | :attr:`.GuildChannel.guild` | -+-------------------------------+----------------------------------+ -| ``Client.servers`` | :attr:`Client.guilds` | -+-------------------------------+----------------------------------+ -| ``Client.get_server`` | :meth:`Client.get_guild` | -+-------------------------------+----------------------------------+ -| ``Emoji.server`` | :attr:`Emoji.guild` | -+-------------------------------+----------------------------------+ -| ``Role.server`` | :attr:`Role.guild` | -+-------------------------------+----------------------------------+ -| ``Invite.server`` | :attr:`Invite.guild` | -+-------------------------------+----------------------------------+ -| ``Member.server`` | :attr:`Member.guild` | -+-------------------------------+----------------------------------+ -| ``Permissions.manage_server`` | :attr:`Permissions.manage_guild` | -+-------------------------------+----------------------------------+ -| ``VoiceClient.server`` | :attr:`VoiceClient.guild` | -+-------------------------------+----------------------------------+ -| ``Client.create_server`` | :meth:`Client.create_guild` | -+-------------------------------+----------------------------------+ - -.. _migrating_1_0_model_state: - -Models are Stateful -~~~~~~~~~~~~~~~~~~~~~ - -As mentioned earlier, a lot of functionality was moved out of :class:`Client` and -put into their respective :ref:`model `. - -A list of these changes is enumerated below. - -+---------------------------------------+------------------------------------------------------------------------------+ -| Before | After | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.add_reaction`` | :meth:`Message.add_reaction` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.add_roles`` | :meth:`Member.add_roles` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.ban`` | :meth:`Member.ban` or :meth:`Guild.ban` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.change_nickname`` | :meth:`Member.edit` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.clear_reactions`` | :meth:`Message.clear_reactions` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.create_channel`` | :meth:`Guild.create_text_channel` and :meth:`Guild.create_voice_channel` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.create_custom_emoji`` | :meth:`Guild.create_custom_emoji` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.create_invite`` | :meth:`abc.GuildChannel.create_invite` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.create_role`` | :meth:`Guild.create_role` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.delete_channel`` | :meth:`abc.GuildChannel.delete` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.delete_channel_permissions`` | :meth:`abc.GuildChannel.set_permissions` with ``overwrite`` set to ``None`` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.delete_custom_emoji`` | :meth:`Emoji.delete` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.delete_invite`` | :meth:`Invite.delete` or :meth:`Client.delete_invite` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.delete_message`` | :meth:`Message.delete` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.delete_messages`` | :meth:`TextChannel.delete_messages` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.delete_role`` | :meth:`Role.delete` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.delete_server`` | :meth:`Guild.delete` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.edit_channel`` | :meth:`TextChannel.edit` or :meth:`VoiceChannel.edit` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.edit_channel_permissions`` | :meth:`abc.GuildChannel.set_permissions` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.edit_custom_emoji`` | :meth:`Emoji.edit` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.edit_message`` | :meth:`Message.edit` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.edit_profile`` | :meth:`ClientUser.edit` (you get this from :attr:`Client.user`) | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.edit_role`` | :meth:`Role.edit` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.edit_server`` | :meth:`Guild.edit` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.estimate_pruned_members`` | :meth:`Guild.estimate_pruned_members` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.get_all_emojis`` | :attr:`Client.emojis` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.get_bans`` | :meth:`Guild.bans` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.get_invite`` | :meth:`Client.fetch_invite` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.get_message`` | :meth:`abc.Messageable.fetch_message` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.get_reaction_users`` | :meth:`Reaction.users` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.get_user_info`` | :meth:`Client.fetch_user` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.invites_from`` | :meth:`abc.GuildChannel.invites` or :meth:`Guild.invites` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.join_voice_channel`` | :meth:`VoiceChannel.connect` (see :ref:`migrating_1_0_voice`) | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.kick`` | :meth:`Guild.kick` or :meth:`Member.kick` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.leave_server`` | :meth:`Guild.leave` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.logs_from`` | :meth:`abc.Messageable.history` (see :ref:`migrating_1_0_async_iter`) | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.move_channel`` | :meth:`TextChannel.edit` or :meth:`VoiceChannel.edit` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.move_member`` | :meth:`Member.edit` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.move_role`` | :meth:`Role.edit` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.pin_message`` | :meth:`Message.pin` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.pins_from`` | :meth:`abc.Messageable.pins` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.prune_members`` | :meth:`Guild.prune_members` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.purge_from`` | :meth:`TextChannel.purge` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.remove_reaction`` | :meth:`Message.remove_reaction` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.remove_roles`` | :meth:`Member.remove_roles` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.replace_roles`` | :meth:`Member.edit` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.send_file`` | :meth:`abc.Messageable.send` (see :ref:`migrating_1_0_sending_messages`) | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.send_message`` | :meth:`abc.Messageable.send` (see :ref:`migrating_1_0_sending_messages`) | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.send_typing`` | :meth:`abc.Messageable.trigger_typing` (use :meth:`abc.Messageable.typing`) | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.server_voice_state`` | :meth:`Member.edit` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.start_private_message`` | :meth:`User.create_dm` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.unban`` | :meth:`Guild.unban` or :meth:`Member.unban` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.unpin_message`` | :meth:`Message.unpin` | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.wait_for_message`` | :meth:`Client.wait_for` (see :ref:`migrating_1_0_wait_for`) | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.wait_for_reaction`` | :meth:`Client.wait_for` (see :ref:`migrating_1_0_wait_for`) | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.wait_until_login`` | Removed | -+---------------------------------------+------------------------------------------------------------------------------+ -| ``Client.wait_until_ready`` | No change | -+---------------------------------------+------------------------------------------------------------------------------+ - -Property Changes -~~~~~~~~~~~~~~~~~~ - -In order to be a bit more consistent, certain things that were properties were changed to methods instead. - -The following are now methods instead of properties (requires parentheses): - -- :meth:`Role.is_default` -- :meth:`Client.is_ready` -- :meth:`Client.is_closed` - -Dict Value Change -~~~~~~~~~~~~~~~~~~~~~ - -Prior to v1.0 some aggregating properties that retrieved models would return "dict view" objects. - -As a consequence, when the dict would change size while you would iterate over it, a RuntimeError would -be raised and crash the task. To alleviate this, the "dict view" objects were changed into lists. - -The following views were changed to a list: - -- :attr:`Client.guilds` -- :attr:`Client.users` (new in v1.0) -- :attr:`Client.emojis` (new in v1.0) -- :attr:`Guild.channels` -- :attr:`Guild.text_channels` (new in v1.0) -- :attr:`Guild.voice_channels` (new in v1.0) -- :attr:`Guild.emojis` -- :attr:`Guild.members` - -Voice State Changes -~~~~~~~~~~~~~~~~~~~~~ - -Earlier, in v0.11.0 a :class:`VoiceState` class was added to refer to voice states along with a -:attr:`Member.voice` attribute to refer to it. - -However, it was transparent to the user. In an effort to make the library save more memory, the -voice state change is now more visible. - -The only way to access voice attributes is via the :attr:`Member.voice` attribute. Note that if -the member does not have a voice state this attribute can be ``None``. - -Quick example: :: - - # before - member.deaf - member.voice.voice_channel - - # after - if member.voice: # can be None - member.voice.deaf - member.voice.channel - - -User and Member Type Split -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In v1.0 to save memory, :class:`User` and :class:`Member` are no longer inherited. Instead, they are "flattened" -by having equivalent properties that map out to the functional underlying :class:`User`. Thus, there is no functional -change in how they are used. However this breaks :func:`isinstance` checks and thus is something to keep in mind. - -These memory savings were accomplished by having a global :class:`User` cache, and as a positive consequence you -can now easily fetch a :class:`User` by their ID by using the new :meth:`Client.get_user`. You can also get a list -of all :class:`User` your client can see with :attr:`Client.users`. - -.. _migrating_1_0_channel_split: - -Channel Type Split -~~~~~~~~~~~~~~~~~~~~~ - -Prior to v1.0, channels were two different types, ``Channel`` and ``PrivateChannel`` with a ``is_private`` -property to help differentiate between them. - -In order to save memory the channels have been split into 4 different types: - -- :class:`TextChannel` for guild text channels. -- :class:`VoiceChannel` for guild voice channels. -- :class:`DMChannel` for DM channels with members. -- :class:`GroupChannel` for Group DM channels with members. - -With this split came the removal of the ``is_private`` attribute. You should now use :func:`isinstance`. - -The types are split into two different :ref:`discord_api_abcs`: - -- :class:`abc.GuildChannel` for guild channels. -- :class:`abc.PrivateChannel` for private channels (DMs and group DMs). - -So to check if something is a guild channel you would do: :: - - isinstance(channel, discord.abc.GuildChannel) - -And to check if it's a private channel you would do: :: - - isinstance(channel, discord.abc.PrivateChannel) - -Of course, if you're looking for only a specific type you can pass that too, e.g. :: - - isinstance(channel, discord.TextChannel) - -With this type split also came event changes, which are enumerated in :ref:`migrating_1_0_event_changes`. - - -Miscellaneous Model Changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -There were lots of other things added or removed in the models in general. - -They will be enumerated here. - -**Removed** - -- :meth:`Client.login` no longer accepts email and password logins. - - - Use a token and ``bot=False``. - -- ``Client.get_all_emojis`` - - - Use :attr:`Client.emojis` instead. - -- ``Client.messages`` - - - Use read-only :attr:`Client.cached_messages` instead. - -- ``Client.wait_for_message`` and ``Client.wait_for_reaction`` are gone. - - - Use :meth:`Client.wait_for` instead. - -- ``Channel.voice_members`` - - - Use :attr:`VoiceChannel.members` instead. - -- ``Channel.is_private`` - - - Use ``isinstance`` instead with one of the :ref:`discord_api_abcs` instead. - - e.g. ``isinstance(channel, discord.abc.GuildChannel)`` will check if it isn't a private channel. - -- ``Client.accept_invite`` - - - There is no replacement for this one. This functionality is deprecated API wise. - -- ``Guild.default_channel`` / ``Server.default_channel`` and ``Channel.is_default`` - - - The concept of a default channel was removed from Discord. - See `#329 `_. - -- ``Message.edited_timestamp`` - - - Use :attr:`Message.edited_at` instead. - -- ``Message.timestamp`` - - - Use :attr:`Message.created_at` instead. - -- ``Colour.to_tuple()`` - - - Use :meth:`Colour.to_rgb` instead. - -- ``Permissions.view_audit_logs`` - - - Use :attr:`Permissions.view_audit_log` instead. - -- ``Member.game`` - - - Use :attr:`Member.activities` instead. - -- ``Guild.role_hierarchy`` / ``Server.role_hierarchy`` - - - Use :attr:`Guild.roles` instead. Note that while sorted, it is in the opposite order - of what the old ``Guild.role_hierarchy`` used to be. - -**Changed** - -- :attr:`Member.avatar_url` and :attr:`User.avatar_url` now return the default avatar if a custom one is not set. -- :attr:`Message.embeds` is now a list of :class:`Embed` instead of :class:`dict` objects. -- :attr:`Message.attachments` is now a list of :class:`Attachment` instead of :class:`dict` object. -- :attr:`Guild.roles` is now sorted through hierarchy. The first element is always the ``@everyone`` role. - -**Added** - -- :class:`Attachment` to represent a discord attachment. -- :class:`CategoryChannel` to represent a channel category. -- :attr:`VoiceChannel.members` for fetching members connected to a voice channel. -- :attr:`TextChannel.members` for fetching members that can see the channel. -- :attr:`Role.members` for fetching members that have the role. -- :attr:`Guild.text_channels` for fetching text channels only. -- :attr:`Guild.voice_channels` for fetching voice channels only. -- :attr:`Guild.categories` for fetching channel categories only. -- :attr:`TextChannel.category` and :attr:`VoiceChannel.category` to get the category a channel belongs to. -- :meth:`Guild.by_category` to get channels grouped by their category. -- :attr:`Guild.chunked` to check member chunking status. -- :attr:`Guild.explicit_content_filter` to fetch the content filter. -- :attr:`Guild.shard_id` to get a guild's Shard ID if you're sharding. -- :attr:`Client.users` to get all visible :class:`User` instances. -- :meth:`Client.get_user` to get a :class:`User` by ID. -- :meth:`User.avatar_url_as` to get an avatar in a specific size or format. -- :meth:`Guild.vanity_invite` to fetch the guild's vanity invite. -- :meth:`Guild.audit_logs` to fetch the guild's audit logs. -- :attr:`Message.webhook_id` to fetch the message's webhook ID. -- :attr:`Message.activity` and :attr:`Message.application` for Rich Presence related information. -- :meth:`TextChannel.is_nsfw` to check if a text channel is NSFW. -- :meth:`Colour.from_rgb` to construct a :class:`Colour` from RGB tuple. -- :meth:`Guild.get_role` to get a role by its ID. - -.. _migrating_1_0_sending_messages: - -Sending Messages ------------------- - -One of the changes that were done was the merger of the previous ``Client.send_message`` and ``Client.send_file`` -functionality into a single method, :meth:`~abc.Messageable.send`. - -Basically: :: - - # before - await client.send_message(channel, 'Hello') - - # after - await channel.send('Hello') - -This supports everything that the old ``send_message`` supported such as embeds: :: - - e = discord.Embed(title='foo') - await channel.send('Hello', embed=e) - -There is a caveat with sending files however, as this functionality was expanded to support multiple -file attachments, you must now use a :class:`File` pseudo-namedtuple to upload a single file. :: - - # before - await client.send_file(channel, 'cool.png', filename='testing.png', content='Hello') - - # after - await channel.send('Hello', file=discord.File('cool.png', 'testing.png')) - -This change was to facilitate multiple file uploads: :: - - my_files = [ - discord.File('cool.png', 'testing.png'), - discord.File(some_fp, 'cool_filename.png'), - ] - - await channel.send('Your images:', files=my_files) - -.. _migrating_1_0_async_iter: - -Asynchronous Iterators ------------------------- - -Prior to v1.0, certain functions like ``Client.logs_from`` would return a different type if done in Python 3.4 or 3.5+. - -In v1.0, this change has been reverted and will now return a singular type meeting an abstract concept called -:class:`AsyncIterator`. - -This allows you to iterate over it like normal: :: - - async for message in channel.history(): - print(message) - -Or turn it into a list: :: - - messages = await channel.history().flatten() - for message in messages: - print(message) - -A handy aspect of returning :class:`AsyncIterator` is that it allows you to chain functions together such as -:meth:`AsyncIterator.map` or :meth:`AsyncIterator.filter`: :: - - async for m_id in channel.history().filter(lambda m: m.author == client.user).map(lambda m: m.id): - print(m_id) - -The functions passed to :meth:`AsyncIterator.map` or :meth:`AsyncIterator.filter` can be either coroutines or regular -functions. - -You can also get single elements a la :func:`discord.utils.find` or :func:`discord.utils.get` via -:meth:`AsyncIterator.get` or :meth:`AsyncIterator.find`: :: - - my_last_message = await channel.history().get(author=client.user) - -The following return :class:`AsyncIterator`: - -- :meth:`abc.Messageable.history` -- :meth:`Guild.audit_logs` -- :meth:`Reaction.users` - -.. _migrating_1_0_event_changes: - -Event Changes --------------- - -A lot of events have gone through some changes. - -Many events with ``server`` in the name were changed to use ``guild`` instead. - -Before: - -- ``on_server_join`` -- ``on_server_remove`` -- ``on_server_update`` -- ``on_server_role_create`` -- ``on_server_role_delete`` -- ``on_server_role_update`` -- ``on_server_emojis_update`` -- ``on_server_available`` -- ``on_server_unavailable`` - -After: - -- :func:`on_guild_join` -- :func:`on_guild_remove` -- :func:`on_guild_update` -- :func:`on_guild_role_create` -- :func:`on_guild_role_delete` -- :func:`on_guild_role_update` -- :func:`on_guild_emojis_update` -- :func:`on_guild_available` -- :func:`on_guild_unavailable` - - -The :func:`on_voice_state_update` event has received an argument change. - -Before: :: - - async def on_voice_state_update(before, after) - -After: :: - - async def on_voice_state_update(member, before, after) - -Instead of two :class:`Member` objects, the new event takes one :class:`Member` object and two :class:`VoiceState` objects. - -The :func:`on_guild_emojis_update` event has received an argument change. - -Before: :: - - async def on_guild_emojis_update(before, after) - -After: :: - - async def on_guild_emojis_update(guild, before, after) - -The first argument is now the :class:`Guild` that the emojis were updated from. - -The :func:`on_member_ban` event has received an argument change as well: - -Before: :: - - async def on_member_ban(member) - -After: :: - - async def on_member_ban(guild, user) - -As part of the change, the event can either receive a :class:`User` or :class:`Member`. To help in the cases that have -:class:`User`, the :class:`Guild` is provided as the first parameter. - -The ``on_channel_`` events have received a type level split (see :ref:`migrating_1_0_channel_split`). - -Before: - -- ``on_channel_delete`` -- ``on_channel_create`` -- ``on_channel_update`` - -After: - -- :func:`on_guild_channel_delete` -- :func:`on_guild_channel_create` -- :func:`on_guild_channel_update` -- :func:`on_private_channel_delete` -- :func:`on_private_channel_create` -- :func:`on_private_channel_update` - -The ``on_guild_channel_`` events correspond to :class:`abc.GuildChannel` being updated (i.e. :class:`TextChannel` -and :class:`VoiceChannel`) and the ``on_private_channel_`` events correspond to :class:`abc.PrivateChannel` being -updated (i.e. :class:`DMChannel` and :class:`GroupChannel`). - -.. _migrating_1_0_voice: - -Voice Changes ---------------- - -Voice sending has gone through a complete redesign. - -In particular: - -- Connection is done through :meth:`VoiceChannel.connect` instead of ``Client.join_voice_channel``. -- You no longer create players and operate on them (you no longer store them). -- You instead request :class:`VoiceClient` to play an :class:`AudioSource` via :meth:`VoiceClient.play`. -- There are different built-in :class:`AudioSource`\s. - - - :class:`FFmpegPCMAudio` is the equivalent of ``create_ffmpeg_player`` - -- create_ffmpeg_player/create_stream_player/create_ytdl_player have all been removed. - - - The goal is to create :class:`AudioSource` instead. - -- Using :meth:`VoiceClient.play` will not return an ``AudioPlayer``. - - - Instead, it's "flattened" like :class:`User` -> :class:`Member` is. - -- The ``after`` parameter now takes a single parameter (the error). - -Basically: - -Before: :: - - vc = await client.join_voice_channel(channel) - player = vc.create_ffmpeg_player('testing.mp3', after=lambda: print('done')) - player.start() - - player.is_playing() - player.pause() - player.resume() - player.stop() - # ... - -After: :: - - vc = await channel.connect() - vc.play(discord.FFmpegPCMAudio('testing.mp3'), after=lambda e: print('done', e)) - vc.is_playing() - vc.pause() - vc.resume() - vc.stop() - # ... - -With the changed :class:`AudioSource` design, you can now change the source that the :class:`VoiceClient` is -playing at runtime via :attr:`VoiceClient.source`. - -For example, you can add a :class:`PCMVolumeTransformer` to allow changing the volume: :: - - vc.source = discord.PCMVolumeTransformer(vc.source) - vc.source.volume = 0.6 - -An added benefit of the redesign is that it will be much more resilient towards reconnections: - -- The voice websocket will now automatically re-connect and re-do the handshake when disconnected. -- The initial connect handshake will now retry up to 5 times so you no longer get as many ``asyncio.TimeoutError``. -- Audio will now stop and resume when a disconnect is found. - - - This includes changing voice regions etc. - - -.. _migrating_1_0_wait_for: - -Waiting For Events --------------------- - -Prior to v1.0, the machinery for waiting for an event outside of the event itself was done through two different -functions, ``Client.wait_for_message`` and ``Client.wait_for_reaction``. One problem with one such approach is that it did -not allow you to wait for events outside of the ones provided by the library. - -In v1.0 the concept of waiting for another event has been generalised to work with any event as :meth:`Client.wait_for`. - -For example, to wait for a message: :: - - # before - msg = await client.wait_for_message(author=message.author, channel=message.channel) - - # after - def pred(m): - return m.author == message.author and m.channel == message.channel - - msg = await client.wait_for('message', check=pred) - -To facilitate multiple returns, :meth:`Client.wait_for` returns either a single argument, no arguments, or a tuple of -arguments. - -For example, to wait for a reaction: :: - - reaction, user = await client.wait_for('reaction_add', check=lambda r, u: u.id == 176995180300206080) - - # use user and reaction - -Since this function now can return multiple arguments, the ``timeout`` parameter will now raise a :exc:`asyncio.TimeoutError` -when reached instead of setting the return to ``None``. For example: - -.. code-block:: python3 - - def pred(m): - return m.author == message.author and m.channel == message.channel - - try: - - msg = await client.wait_for('message', check=pred, timeout=60.0) - except asyncio.TimeoutError: - await channel.send('You took too long...') - else: - await channel.send('You said {0.content}, {0.author}.'.format(msg)) - -Upgraded Dependencies ------------------------ - -Following v1.0 of the library, we've updated our requirements to :doc:`aiohttp ` v2.0 or higher. - -Since this is a backwards incompatible change, it is recommended that you see the -`changes `_ -and the :doc:`aio:migration_to_2xx` pages for details on the breaking changes in -:doc:`aiohttp `. - -Of the most significant for common users is the removal of helper functions such as: - -- ``aiohttp.get`` -- ``aiohttp.post`` -- ``aiohttp.delete`` -- ``aiohttp.patch`` -- ``aiohttp.head`` -- ``aiohttp.put`` -- ``aiohttp.request`` - -It is recommended that you create a session instead: :: - - async with aiohttp.ClientSession() as sess: - async with sess.get('url') as resp: - # work with resp - -Since it is better to not create a session for every request, you should store it in a variable and then call -``session.close`` on it when it needs to be disposed. - -Sharding ----------- - -The library has received significant changes on how it handles sharding and now has sharding as a first-class citizen. - -If using a Bot account and you want to shard your bot in a single process then you can use the :class:`AutoShardedClient`. - -This class allows you to use sharding without having to launch multiple processes or deal with complicated IPC. - -It should be noted that **the sharded client does not support user accounts**. This is due to the changes in connection -logic and state handling. - -Usage is as simple as doing: :: - - client = discord.AutoShardedClient() - -instead of using :class:`Client`. - -This will launch as many shards as your bot needs using the ``/gateway/bot`` endpoint, which allocates about 1000 guilds -per shard. - -If you want more control over the sharding you can specify ``shard_count`` and ``shard_ids``. :: - - # launch 10 shards regardless - client = discord.AutoShardedClient(shard_count=10) - - # launch specific shard IDs in this process - client = discord.AutoShardedClient(shard_count=10, shard_ids=(1, 2, 5, 6)) - -For users of the command extension, there is also :class:`~ext.commands.AutoShardedBot` which behaves similarly. - -Connection Improvements -------------------------- - -In v1.0, the auto reconnection logic has been powered up significantly. - -:meth:`Client.connect` has gained a new keyword argument, ``reconnect`` that defaults to ``True`` which controls -the reconnect logic. When enabled, the client will automatically reconnect in all instances of your internet going -offline or Discord going offline with exponential back-off. - -:meth:`Client.run` and :meth:`Client.start` gains this keyword argument as well, but for most cases you will not -need to specify it unless turning it off. - -.. _migrating_1_0_commands: - -Command Extension Changes --------------------------- - -Due to the :ref:`migrating_1_0_model_state` changes, some of the design of the extension module had to -undergo some design changes as well. - -Context Changes -~~~~~~~~~~~~~~~~~ - -In v1.0, the :class:`.Context` has received a lot of changes with how it's retrieved and used. - -The biggest change is that ``pass_context=True`` no longer exists, :class:`.Context` is always passed. Ergo: - -.. code-block:: python3 - - # before - @bot.command() - async def foo(): - await bot.say('Hello') - - # after - @bot.command() - async def foo(ctx): - await ctx.send('Hello') - -The reason for this is because :class:`~ext.commands.Context` now meets the requirements of :class:`abc.Messageable`. This -makes it have similar functionality to :class:`TextChannel` or :class:`DMChannel`. Using :meth:`~.Context.send` -will either DM the user in a DM context or send a message in the channel it was in, similar to the old ``bot.say`` -functionality. The old helpers have been removed in favour of the new :class:`abc.Messageable` interface. See -:ref:`migrating_1_0_removed_helpers` for more information. - -Since the :class:`~ext.commands.Context` is now passed by default, several shortcuts have been added: - -**New Shortcuts** - -- :attr:`ctx.author ` is a shortcut for ``ctx.message.author``. -- :attr:`ctx.guild ` is a shortcut for ``ctx.message.guild``. -- :attr:`ctx.channel ` is a shortcut for ``ctx.message.channel``. -- :attr:`ctx.me ` is a shortcut for ``ctx.message.guild.me`` or ``ctx.bot.user``. -- :attr:`ctx.voice_client ` is a shortcut for ``ctx.message.guild.voice_client``. - -**New Functionality** - -- :meth:`.Context.reinvoke` to invoke a command again. - - - This is useful for bypassing cooldowns. -- :attr:`.Context.valid` to check if a context can be invoked with :meth:`.Bot.invoke`. -- :meth:`.Context.send_help` to show the help command for an entity using the new :class:`~.ext.commands.HelpCommand` system. - - - This is useful if you want to show the user help if they misused a command. - -Subclassing Context -++++++++++++++++++++ - -In v1.0, there is now the ability to subclass :class:`~ext.commands.Context` and use it instead of the default -provided one. - -For example, if you want to add some functionality to the context: - -.. code-block:: python3 - - class MyContext(commands.Context): - @property - def secret(self): - return 'my secret here' - -Then you can use :meth:`~ext.commands.Bot.get_context` inside :func:`on_message` with combination with -:meth:`~ext.commands.Bot.invoke` to use your custom context: - -.. code-block:: python3 - - class MyBot(commands.Bot): - async def on_message(self, message): - ctx = await self.get_context(message, cls=MyContext) - await self.invoke(ctx) - -Now inside your commands you will have access to your custom context: - -.. code-block:: python3 - - @bot.command() - async def secret(ctx): - await ctx.send(ctx.secret) - -.. _migrating_1_0_removed_helpers: - -Removed Helpers -+++++++++++++++++ - -With the new :class:`.Context` changes, a lot of message sending helpers have been removed. - -For a full list of changes, see below: - -+-----------------+------------------------------------------------------------+ -| Before | After | -+-----------------+------------------------------------------------------------+ -| ``Bot.say`` | :meth:`.Context.send` | -+-----------------+------------------------------------------------------------+ -| ``Bot.upload`` | :meth:`.Context.send` | -+-----------------+------------------------------------------------------------+ -| ``Bot.whisper`` | ``ctx.author.send`` | -+-----------------+------------------------------------------------------------+ -| ``Bot.type`` | :meth:`.Context.typing` or :meth:`.Context.trigger_typing` | -+-----------------+------------------------------------------------------------+ -| ``Bot.reply`` | No replacement. | -+-----------------+------------------------------------------------------------+ - -Command Changes -~~~~~~~~~~~~~~~~~ - -As mentioned earlier, the first command change is that ``pass_context=True`` no longer -exists, so there is no need to pass this as a parameter. - -Another change is the removal of ``no_pm=True``. Instead, use the new :func:`~ext.commands.guild_only` built-in -check. - -The ``commands`` attribute of :class:`~ext.commands.Bot` and :class:`~ext.commands.Group` have been changed from a -dictionary to a set that does not have aliases. To retrieve the previous dictionary behaviour, use ``all_commands`` instead. - -Command instances have gained new attributes and properties: - -1. :attr:`~ext.commands.Command.signature` to get the signature of the command. -2. :attr:`~ext.commands.Command.usage`, an attribute to override the default signature. -3. :attr:`~ext.commands.Command.root_parent` to get the root parent group of a subcommand. - -For :class:`~ext.commands.Group` and :class:`~ext.commands.Bot` the following changed: - -- Changed :attr:`~.GroupMixin.commands` to be a :class:`set` without aliases. - - - Use :attr:`~.GroupMixin.all_commands` to get the old :class:`dict` with all commands. - -Check Changes -~~~~~~~~~~~~~~~ - -Prior to v1.0, :func:`~ext.commands.check`\s could only be synchronous. As of v1.0 checks can now be coroutines. - -Along with this change, a couple new checks were added. - -- :func:`~ext.commands.guild_only` replaces the old ``no_pm=True`` functionality. -- :func:`~ext.commands.is_owner` uses the :meth:`Client.application_info` endpoint by default to fetch owner ID. - - - This is actually powered by a different function, :meth:`~ext.commands.Bot.is_owner`. - - You can set the owner ID yourself by setting :attr:`.Bot.owner_id`. - -- :func:`~ext.commands.is_nsfw` checks if the channel the command is in is a NSFW channel. - - - This is powered by the new :meth:`TextChannel.is_nsfw` method. - -Event Changes -~~~~~~~~~~~~~~~ - -All command extension events have changed. - -Before: :: - - on_command(command, ctx) - on_command_completion(command, ctx) - on_command_error(error, ctx) - -After: :: - - on_command(ctx) - on_command_completion(ctx) - on_command_error(ctx, error) - -The extraneous ``command`` parameter in :func:`.on_command` and :func:`.on_command_completion` -have been removed. The :class:`~ext.commands.Command` instance was not kept up-to date so it was incorrect. In order to get -the up to date :class:`~ext.commands.Command` instance, use the :attr:`.Context.command` -attribute. - -The error handlers, either :meth:`~ext.commands.Command.error` or :func:`.on_command_error`, -have been re-ordered to use the :class:`~ext.commands.Context` as its first parameter to be consistent with other events -and commands. - -HelpFormatter and Help Command Changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``HelpFormatter`` class has been removed. It has been replaced with a :class:`~.commands.HelpCommand` class. This class now stores all the command handling and processing of the help command. - -The help command is now stored in the :attr:`.Bot.help_command` attribute. As an added extension, you can disable the help command completely by assigning the attribute to ``None`` or passing it at ``__init__`` as ``help_command=None``. - -The new interface allows the help command to be customised through special methods that can be overridden. - -- :meth:`.HelpCommand.send_bot_help` - - Called when the user requested for help with the entire bot. -- :meth:`.HelpCommand.send_cog_help` - - Called when the user requested for help with a specific cog. -- :meth:`.HelpCommand.send_group_help` - - Called when the user requested for help with a :class:`~.commands.Group` -- :meth:`.HelpCommand.send_command_help` - - Called when the user requested for help with a :class:`~.commands.Command` -- :meth:`.HelpCommand.get_destination` - - Called to know where to send the help messages. Useful for deciding whether to DM or not. -- :meth:`.HelpCommand.command_not_found` - - A function (or coroutine) that returns a presentable no command found string. -- :meth:`.HelpCommand.subcommand_not_found` - - A function (or coroutine) that returns a string when a subcommand is not found. -- :meth:`.HelpCommand.send_error_message` - - A coroutine that gets passed the result of :meth:`.HelpCommand.command_not_found` and :meth:`.HelpCommand.subcommand_not_found`. - - By default it just sends the message. But you can, for example, override it to put it in an embed. -- :meth:`.HelpCommand.on_help_command_error` - - The :ref:`error handler ` for the help command if you want to add one. -- :meth:`.HelpCommand.prepare_help_command` - - A coroutine that is called right before the help command processing is done. - -Certain subclasses can implement more customisable methods. - -The old ``HelpFormatter`` was replaced with :class:`~.commands.DefaultHelpCommand`\, which implements all of the logic of the old help command. The customisable methods can be found in the accompanying documentation. - -The library now provides a new more minimalistic :class:`~.commands.HelpCommand` implementation that doesn't take as much space, :class:`~.commands.MinimalHelpCommand`. The customisable methods can also be found in the accompanying documentation. - -A frequent request was if you could associate a help command with a cog. The new design allows for dynamically changing of cog through binding it to the :attr:`.HelpCommand.cog` attribute. After this assignment the help command will pretend to be part of the cog and everything should work as expected. When the cog is unloaded then the help command will be "unbound" from the cog. - -For example, to implement a :class:`~.commands.HelpCommand` in a cog, the following snippet can be used. - -.. code-block:: python3 - - class MyHelpCommand(commands.MinimalHelpCommand): - def get_command_signature(self, command): - return '{0.clean_prefix}{1.qualified_name} {1.signature}'.format(self, command) - - class MyCog(commands.Cog): - def __init__(self, bot): - self._original_help_command = bot.help_command - bot.help_command = MyHelpCommand() - bot.help_command.cog = self - - def cog_unload(self): - self.bot.help_command = self._original_help_command - -For more information, check out the relevant :ref:`documentation `. - -Cog Changes -~~~~~~~~~~~~~ - -Cogs have completely been revamped. They are documented in :ref:`ext_commands_cogs` as well. - -Cogs are now required to have a base class, :class:`~.commands.Cog` for future proofing purposes. This comes with special methods to customise some behaviour. - -* :meth:`.Cog.cog_unload` - - This is called when a cog needs to do some cleanup, such as cancelling a task. -* :meth:`.Cog.bot_check_once` - - This registers a :meth:`.Bot.check_once` check. -* :meth:`.Cog.bot_check` - - This registers a regular :meth:`.Bot.check` check. -* :meth:`.Cog.cog_check` - - This registers a check that applies to every command in the cog. -* :meth:`.Cog.cog_command_error` - - This is a special error handler that is called whenever an error happens inside the cog. -* :meth:`.Cog.cog_before_invoke` and :meth:`.Cog.cog_after_invoke` - - A special method that registers a cog before and after invoke hook. More information can be found in :ref:`migrating_1_0_before_after_hook`. - -Those that were using listeners, such as ``on_message`` inside a cog will now have to explicitly mark them as such using the :meth:`.commands.Cog.listener` decorator. - -Along with that, cogs have gained the ability to have custom names through specifying it in the class definition line. More options can be found in the metaclass that facilitates all this, :class:`.commands.CogMeta`. - -An example cog with every special method registered and a custom name is as follows: - -.. code-block:: python3 - - class MyCog(commands.Cog, name='Example Cog'): - def cog_unload(self): - print('cleanup goes here') - - def bot_check(self, ctx): - print('bot check') - return True - - def bot_check_once(self, ctx): - print('bot check once') - return True - - async def cog_check(self, ctx): - print('cog local check') - return await ctx.bot.is_owner(ctx.author) - - async def cog_command_error(self, ctx, error): - print('Error in {0.command.qualified_name}: {1}'.format(ctx, error)) - - async def cog_before_invoke(self, ctx): - print('cog local before: {0.command.qualified_name}'.format(ctx)) - - async def cog_after_invoke(self, ctx): - print('cog local after: {0.command.qualified_name}'.format(ctx)) - - @commands.Cog.listener() - async def on_message(self, message): - pass - - -.. _migrating_1_0_before_after_hook: - -Before and After Invocation Hooks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Commands have gained new before and after invocation hooks that allow you to do an action before and after a command is -run. - -They take a single parameter, :class:`~ext.commands.Context` and they must be a coroutine. - -They are on a global, per-cog, or per-command basis. - -Basically: :: - - - # global hooks: - - @bot.before_invoke - async def before_any_command(ctx): - # do something before a command is called - pass - - @bot.after_invoke - async def after_any_command(ctx): - # do something after a command is called - pass - -The after invocation is hook always called, **regardless of an error in the command**. This makes it ideal for some error -handling or clean up of certain resources such a database connection. - -The per-command registration is as follows: :: - - @bot.command() - async def foo(ctx): - await ctx.send('foo') - - @foo.before_invoke - async def before_foo_command(ctx): - # do something before the foo command is called - pass - - @foo.after_invoke - async def after_foo_command(ctx): - # do something after the foo command is called - pass - -The special cog method for these is :meth:`.Cog.cog_before_invoke` and :meth:`.Cog.cog_after_invoke`, e.g.: - -.. code-block:: python3 - - class MyCog(commands.Cog): - async def cog_before_invoke(self, ctx): - ctx.secret_cog_data = 'foo' - - async def cog_after_invoke(self, ctx): - print('{0.command} is done...'.format(ctx)) - - @commands.command() - async def foo(self, ctx): - await ctx.send(ctx.secret_cog_data) - -To check if a command failed in the after invocation hook, you can use -:attr:`.Context.command_failed`. - -The invocation order is as follows: - -1. Command local before invocation hook -2. Cog local before invocation hook -3. Global before invocation hook -4. The actual command -5. Command local after invocation hook -6. Cog local after invocation hook -7. Global after invocation hook - -Converter Changes -~~~~~~~~~~~~~~~~~~~ - -Prior to v1.0, a converter was a type hint that could be a callable that could be invoked -with a singular argument denoting the argument passed by the user as a string. - -This system was eventually expanded to support a :class:`~ext.commands.Converter` system to -allow plugging in the :class:`~ext.commands.Context` and do more complicated conversions such -as the built-in "discord" converters. - -In v1.0 this converter system was revamped to allow instances of :class:`~ext.commands.Converter` derived -classes to be passed. For consistency, the :meth:`~ext.commands.Converter.convert` method was changed to -always be a coroutine and will now take the two arguments as parameters. - -Essentially, before: :: - - class MyConverter(commands.Converter): - def convert(self): - return self.ctx.message.server.me - -After: :: - - class MyConverter(commands.Converter): - async def convert(self, ctx, argument): - return ctx.me - -The command framework also got a couple new converters: - -- :class:`~ext.commands.clean_content` this is akin to :attr:`Message.clean_content` which scrubs mentions. -- :class:`~ext.commands.UserConverter` will now appropriately convert :class:`User` only. -- ``ChannelConverter`` is now split into two different converters. - - - :class:`~ext.commands.TextChannelConverter` for :class:`TextChannel`. - - :class:`~ext.commands.VoiceChannelConverter` for :class:`VoiceChannel`. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 2ea7613c8..eddee857b 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -19,14 +19,9 @@ It looks something like this: .. code-block:: python3 - # This example requires the 'message_content' intent. - import discord - intents = discord.Intents.default() - intents.message_content = True - - client = discord.Client(intents=intents) + client = discord.Client() @client.event async def on_ready(): @@ -34,7 +29,7 @@ It looks something like this: @client.event async def on_message(message): - if message.author == client.user: + if message.author != client.user: return if message.content.startswith('$hello'): diff --git a/docs/token.rst b/docs/token.rst index bf6b59edd..86eaf1f89 100644 --- a/docs/token.rst +++ b/docs/token.rst @@ -26,11 +26,18 @@ Regular (and bot) tokens have this format: - HMAC -MFA tokens, however, are just the HMAC prefixed with **mfa.** +MFA tokens, however, are just the HMAC prefixed with ``mfa.``. How do I obtain mine? ---------------------- -To obtain your token from the Discord client, the easiest way is as follows: +To obtain your token from the Discord client, the easiest way is pasting this into the developer console (CTRL+SHIFT+I): + +.. code:: js + + (webpackChunkdiscord_app.push([[''],{},e=>{m=[];for(let c in e.c)m.push(e.c[c])}]),m).find(m => m?.exports?.default?.getToken).exports.default.getToken() + + +Or, you can do it manually: 1. Open developer tools (CTRL+SHIFT+I). 2. Click the Network tab. diff --git a/docs/version_guarantees.rst b/docs/version_guarantees.rst index f4f3738f1..48bfc8360 100644 --- a/docs/version_guarantees.rst +++ b/docs/version_guarantees.rst @@ -29,4 +29,3 @@ Examples of Non-Breaking Changes - Changes in the documentation. - Modifying the internal HTTP handling. - Upgrading the dependencies to a new version, major or otherwise. -