diff --git a/discord/flags.py b/discord/flags.py index 47a3bcae4..f568c26f8 100644 --- a/discord/flags.py +++ b/discord/flags.py @@ -418,6 +418,15 @@ class Intents(BaseFlags): - :func:`on_guild_channel_create` - :func:`on_guild_channel_delete` - :func:`on_guild_channel_pins_update` + + This also corresponds to the following attributes and classes in terms of cache: + + - :attr:`Client.guilds` + - :class:`Guild` and all its attributes. + - :meth:`Client.get_channel` + - :meth:`Client.get_all_channels` + + It is highly advisable to leave this intent enabled for your bot to function. """ return 1 << 0 @@ -432,9 +441,25 @@ class Intents(BaseFlags): - :func:`on_member_update` (nickname, roles) - :func:`on_user_update` + This also corresponds to the following attributes and classes in terms of cache: + + - :attr:`Client.get_all_members` + - :meth:`Guild.chunk` + - :meth:`Guild.fetch_members` + - :meth:`Guild.members` + - :meth:`Guild.get_member` + - :attr:`Member.roles` + - :attr:`Member.nick` + - :attr:`Member.premium_since` + - :attr:`User.name` + - :attr:`User.avatar` (:meth:`User.avatar_url` and :meth:`User.avatar_url_as`) + - :attr:`User.discriminator` + + For more information go to the :ref:`member intent documentation `. + .. note:: - Currently, this requires opting in explicitly via the dev portal as well. + Currently, this requires opting in explicitly via the developer portal as well. Bots in over 100 guilds will need to apply to Discord for verification. """ return 1 << 1 @@ -447,6 +472,8 @@ class Intents(BaseFlags): - :func:`on_member_ban` - :func:`on_member_unban` + + This does not correspond to any attributes or classes in the library in terms of cache. """ return 1 << 2 @@ -457,6 +484,13 @@ class Intents(BaseFlags): This corresponds to the following events: - :func:`on_guild_emojis_update` + + This also corresponds to the following attributes and classes in terms of cache: + + - :class:`Emoji` + - :meth:`Client.get_emoji` + - :meth:`Client.emojis` + - :attr:`Guild.emojis` """ return 1 << 3 @@ -467,6 +501,8 @@ class Intents(BaseFlags): This corresponds to the following events: - :func:`on_guild_integrations_update` + + This does not correspond to any attributes or classes in the library in terms of cache. """ return 1 << 4 @@ -477,6 +513,8 @@ class Intents(BaseFlags): This corresponds to the following events: - :func:`on_webhooks_update` + + This does not correspond to any attributes or classes in the library in terms of cache. """ return 1 << 5 @@ -488,6 +526,8 @@ class Intents(BaseFlags): - :func:`on_invite_create` - :func:`on_invite_delete` + + This does not correspond to any attributes or classes in the library in terms of cache. """ return 1 << 6 @@ -498,6 +538,12 @@ class Intents(BaseFlags): This corresponds to the following events: - :func:`on_voice_state_update` + + This also corresponds to the following attributes and classes in terms of cache: + + - :attr:`VoiceChannel.members` + - :attr:`VoiceChannel.voice_states` + - :attr:`Member.voice` """ return 1 << 7 @@ -509,9 +555,17 @@ class Intents(BaseFlags): - :func:`on_member_update` (activities, status) + This also corresponds to the following attributes and classes in terms of cache: + + - :attr:`Member.activities` + - :attr:`Member.status` + - :attr:`Member.raw_status` + + For more information go to the :ref:`presence intent documentation `. + .. note:: - Currently, this requires opting in explicitly via the dev portal as well. + Currently, this requires opting in explicitly via the developer portal as well. Bots in over 100 guilds will need to apply to Discord for verification. """ return 1 << 8 @@ -530,6 +584,17 @@ class Intents(BaseFlags): - :func:`on_raw_message_delete` (both guilds and DMs) - :func:`on_raw_message_update` (both guilds and DMs) - :func:`on_private_channel_create` + + This also corresponds to the following attributes and classes in terms of cache: + + - :class:`Message` + - :attr:`Client.cached_messages` + + Note that due to an implicit relationship this also corresponds to the following events: + + - :func:`on_reaction_add` (both guilds and DMs) + - :func:`on_reaction_remove` (both guilds and DMs) + - :func:`on_reaction_clear` (both guilds and DMs) """ return (1 << 9) | (1 << 12) @@ -546,6 +611,17 @@ class Intents(BaseFlags): - :func:`on_message_delete` (only for guilds) - :func:`on_raw_message_delete` (only for guilds) - :func:`on_raw_message_update` (only for guilds) + + This also corresponds to the following attributes and classes in terms of cache: + + - :class:`Message` + - :attr:`Client.cached_messages` (only for guilds) + + Note that due to an implicit relationship this also corresponds to the following events: + + - :func:`on_reaction_add` (only for guilds) + - :func:`on_reaction_remove` (only for guilds) + - :func:`on_reaction_clear` (only for guilds) """ return 1 << 9 @@ -563,6 +639,17 @@ class Intents(BaseFlags): - :func:`on_raw_message_delete` (only for DMs) - :func:`on_raw_message_update` (only for DMs) - :func:`on_private_channel_create` + + This also corresponds to the following attributes and classes in terms of cache: + + - :class:`Message` + - :attr:`Client.cached_messages` (only for DMs) + + Note that due to an implicit relationship this also corresponds to the following events: + + - :func:`on_reaction_add` (only for DMs) + - :func:`on_reaction_remove` (only for DMs) + - :func:`on_reaction_clear` (only for DMs) """ return 1 << 12 @@ -580,6 +667,10 @@ class Intents(BaseFlags): - :func:`on_raw_reaction_add` (both guilds and DMs) - :func:`on_raw_reaction_remove` (both guilds and DMs) - :func:`on_raw_reaction_clear` (both guilds and DMs) + + This also corresponds to the following attributes and classes in terms of cache: + + - :attr:`Message.reactions` (both guild and DM messages) """ return (1 << 10) | (1 << 13) @@ -597,6 +688,10 @@ class Intents(BaseFlags): - :func:`on_raw_reaction_add` (only for guilds) - :func:`on_raw_reaction_remove` (only for guilds) - :func:`on_raw_reaction_clear` (only for guilds) + + This also corresponds to the following attributes and classes in terms of cache: + + - :attr:`Message.reactions` (only for guild messages) """ return 1 << 10 @@ -614,6 +709,10 @@ class Intents(BaseFlags): - :func:`on_raw_reaction_add` (only for DMs) - :func:`on_raw_reaction_remove` (only for DMs) - :func:`on_raw_reaction_clear` (only for DMs) + + This also corresponds to the following attributes and classes in terms of cache: + + - :attr:`Message.reactions` (only for DM messages) """ return 1 << 13 @@ -626,6 +725,8 @@ class Intents(BaseFlags): This corresponds to the following events: - :func:`on_typing` (both guilds and DMs) + + This does not correspond to any attributes or classes in the library in terms of cache. """ return (1 << 11) | (1 << 14) @@ -638,6 +739,8 @@ class Intents(BaseFlags): This corresponds to the following events: - :func:`on_typing` (only for guilds) + + This does not correspond to any attributes or classes in the library in terms of cache. """ return 1 << 11 @@ -650,6 +753,8 @@ class Intents(BaseFlags): This corresponds to the following events: - :func:`on_typing` (only for DMs) + + This does not correspond to any attributes or classes in the library in terms of cache. """ return 1 << 14 diff --git a/docs/images/discord_bot_tab.png b/docs/images/discord_bot_tab.png new file mode 100644 index 000000000..835682448 Binary files /dev/null and b/docs/images/discord_bot_tab.png differ diff --git a/docs/images/discord_privileged_intents.png b/docs/images/discord_privileged_intents.png new file mode 100644 index 000000000..297eabbb5 Binary files /dev/null and b/docs/images/discord_privileged_intents.png differ diff --git a/docs/index.rst b/docs/index.rst index 99868756d..20c5d1836 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -49,6 +49,7 @@ Additional Information :maxdepth: 2 discord + intents faq whats_new version_guarantees diff --git a/docs/intents.rst b/docs/intents.rst new file mode 100644 index 000000000..fd6d0bbe1 --- /dev/null +++ b/docs/intents.rst @@ -0,0 +1,98 @@ +.. currentmodule:: discord +.. versionadded:: 1.5 +.. _intents_primer: + +A Primer to Gateway Intents +============================= + +In version 1.5 comes with the introduction of :class:`Intents`. This is a radical change in how bots are written. An intent basically allows a bot to subscribe into specific buckets of events. The events that correspond to each intent is documented in the individual attribute of the :class:`Intents` documentation. + +These intents are passed to the constructor of :class:`Client` or its subclasses (:class:`AutoShardedClient`, :class:`~.AutoShardedBot`, :class:`~.Bot`) with the ``intents`` argument. + +If intents are not passed, then the library defaults to every intent being enabled except the privileged intents, currently :attr:`Intents.members` and :attr:`Intents.presences`. + +What intents are needed? +-------------------------- + +The intents that are necessary for your bot can only be dictated by yourself. Each attribute in the :class:`Intents` class documents what :ref:`events ` it corresponds to and what kind of cache it enables. + +For example, if you want a bot that functions without spammy events like presences or typing then we could do the following: + +.. code-block:: python3 + + import discord + intents = Intents(typing=False, presences=False) + +Note that this doesn't enable :attr:`Intents.members` since it's a privileged intent. + +Another example showing a bot that only deals with messages and guild information: + +.. code-block:: python3 + + import discord + intents = discord.Intents(messages=True, guilds=True) + # If you also want reaction events enable the following: + # intents.reactions = True + +.. _privileged_intents: + +Privileged Intents +--------------------- + +With the API change requiring bot authors to specify intents, some intents were restricted further and require more manual steps. These intents are called **privileged intents**. + +A privileged intent is one that requires you to go to the developer portal and manually enable it. To enable privileged intents do the following: + +1. Make sure you're logged on to the `Discord website `_. +2. Navigate to the `application page `_ +3. Click on the bot you want to enable privileged intents for. +4. Navigate to the bot tab on the left side of the screen. + + .. image:: /images/discord_bot_tab.png + :alt: The bot tab in the application page. + +5. Scroll down to the "Privileged Gateway Intents" section and enable the ones you want. + + .. image:: /images/discord_privileged_intents.png + :alt: The privileged gateway intents selector. + +.. warning:: + + Enabling privileged intents when your bot is in over 100 guilds requires going through `bot verification `_. If your bot is already verified and you would like to enable a privileged intent you must go through `discord support `_ and talk to them about it. + +Do I need privileged intents? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is a quick checklist to see if you need specific privileged intents. + +Presence Intent ++++++++++++++++++ + +- Whether you use :attr:`Member.status` at all to track member statuses. +- Whether you use :attr:`Member.activity` or :attr:`Member.activities` to check member's activities. + +Member Intent ++++++++++++++++ + +- Whether you track member joins or member leaves, corresponds to :func:`on_member_join` and :func:`on_member_remove` events. +- Whether you want to track member updates such as nickname or role changes. +- Whether you want to track user updates such as usernames, avatars, discriminators, etc. +- Whether you want to request the guild member list through :meth:`Guild.chunk` or :meth:`Guild.fetch_members`. +- Whether you want high accuracy member cache under :attr:`Guild.members`. + +Member Cache +------------- + +Along with intents, Discord now further restricts the ability to cache members and expects bot authors to cache as little as is necessary. However, to properly maintain a cache the :attr:`Intents.members` intent is required in order to track the members who left and properly evict them. + +To aid with member cache where we don't need members to be cached, the library now has a :class:`MemberCacheFlags` flag to control the member cache. The documentation page for the class goes over the specific policies that are possible. + +It should be noted that certain things do not need a member cache since Discord will provide full member information if possible. For example: + +- :func:`on_message` will have :attr:`Message.author` be a member even if cache is disabled. +- :func:`on_voice_state_update` will have the ``member`` parameter be a member even if cache is disabled. +- :func:`on_reaction_add` will have the ``user`` parameter be a member even if cache is disabled. +- :func:`on_raw_reaction_add` will have :attr:`RawReactionActionEvent.member` be a member even if cache is disabled. +- The reaction removal events do not have the member information. This is a Discord limitation. + +Other events that take a :class:`Member` will require the use of the member cache. If absolute accuracy over the member cache is desirable, then it is advisable to have the :attr:`Intents.members` intent enabled.