hikari.intents
Shard intents for controlling which events the application receives.
View Source
# -*- coding: utf-8 -*- # cython: language_level=3 # Copyright (c) 2020 Nekokatt # Copyright (c) 2021-present davfsa # # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to deal # in the Software without restriction, including without limitation the rights # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell # copies of the Software, and to permit persons to whom the Software is # furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice shall be included in all # copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. """Shard intents for controlling which events the application receives.""" from __future__ import annotations __all__: typing.Sequence[str] = ("Intents",) import typing from hikari.internal import enums @typing.final class Intents(enums.Flag): """Represents an intent on the gateway. This is a bitfield representation of all the categories of event that you wish to receive. Any events not in an intent category will be fired regardless of what intents you provide. .. note:: Discord now places limits on certain events you can receive without whitelisting your bot first. On the `Bot` tab in the developer's portal for your bot, you should now have the option to enable functionality for receiving these events. If you attempt to request an intent type that you have not whitelisted your bot for, you will be disconnected on startup with a `4014` closure code. .. warning:: If you are using the V7 Gateway, you will be REQUIRED to provide some form of intent value when you connect. Failure to do so may result in immediate termination of the session server-side. This enum is an `enum.IntFlag`, which means that you can use bitwise operators to join and splice multiple intents into one value. For example, if we wish to only refer to the `GUILDS` intent, then it is simply a case of accessing it normally. ```py my_intents = Intents.GUILDS ``` If we wanted to have several intents grouped together, we would use the bitwise-or operator to combine them (`|`). This can be done in-place with the `|=` operator if needed. ```py # One or two values that fit on one line. my_intents = Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES # Several intents together. You may find it useful to format these like # so to keep your code readable. my_intents = ( Intents.GUILDS | Intents.GUILD_BANS | Intents.GUILD_EMOJIS | Intents.GUILD_INTEGRATIONS | Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES ) ``` To check if an intent **is present** in a given intents bitfield, you can use the bitwise-and operator (`&`) to check. This returns the "intersection" or "crossover" between the left and right-hand side of the `&`. You can then use the `==` operator to check that specific values are present. You can check in-place with the `&=` operator if needed. ```py # Check if an intent is set: if (my_intents & Intents.GUILD_MESSAGES) == Intents.GUILD_MESSAGES: print("Guild messages are enabled") # Checking if ALL in a combination are set: expected_intents = (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES) if (my_intents & expected_intents) == expected_intents: print("Messages are enabled in guilds and private messages.") # Checking if AT LEAST ONE in a combination is set: expected_intents = (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES) if my_intents & expected_intents: print("Messages are enabled in guilds or private messages.") ``` Removing one or more intents from a combination can be done with the bitwise-xor (`^`) operator. The `^=` operator can do this in-place. ```py # Remove GUILD_MESSAGES my_intents = my_intents ^ Intents.GUILD_MESSAGES # or, simplifying: my_intents ^= Intents.GUILD_MESSAGES # Remove all messages events. my_intents = my_intents ^ (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES) # or, simplifying my_intents ^= (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES) ``` What is and is not covered by intents? -------------------------------------- The following unprivileged events require intents to be dispatched: - `GUILD_CREATE` - `GUILD_UPDATE` - `GUILD_DELETE` - `GUILD_ROLE_CREATE` - `GUILD_ROLE_UPDATE` - `GUILD_ROLE_DELETE` - `GUILD_BAN_ADD` - `GUILD_BAN_REMOVE` - `GUILD_EMOJIS_UPDATE` - `INTEGRATION_CREATE` - `INTEGRATION_DELETE` - `INTEGRATION_UPDATE` - `INVITE_CREATE` - `INVITE_DELETE` - `CHANNEL_CREATE` - `CHANNEL_UPDATE` - `CHANNEL_DELETE` - `CHANNEL_PINS_UPDATE (guilds only)` - `MESSAGE_CREATE` - `MESSAGE_UPDATE` - `MESSAGE_DELETE` - `MESSAGE_BULK_DELETE` - `MESSAGE_REACTION_ADD` - `MESSAGE_REACTION_REMOVE` - `MESSAGE_REACTION_REMOVE_ALL` - `MESSAGE_REACTION_REMOVE_EMOJI` - `TYPING_START` - `VOICE_STATE_UPDATE` - `WEBHOOKS_UPDATE` The following privileged events require intents to be dispatched: - `GUILD_MEMBER_ADD` - `GUILD_MEMBER_UPDATE` - `GUILD_MEMBER_REMOVE` - `PRESENCE_UPDATE` All events not listed above will be dispatched regardless of whether intents are used or not. """ NONE = 0 """Represents no intents.""" GUILDS = 1 << 0 """Subscribes to the following events: * `GUILD_CREATE` * `GUILD_UPDATE` * `GUILD_DELETE` * `GUILD_ROLE_CREATE` * `GUILD_ROLE_UPDATE` * `GUILD_ROLE_DELETE` * `CHANNEL_CREATE` * `CHANNEL_UPDATE` * `CHANNEL_DELETE` * `CHANNEL_PINS_UPDATE` """ GUILD_MEMBERS = 1 << 1 """Subscribes to the following events: * `GUILD_MEMBER_ADD` * `GUILD_MEMBER_UPDATE` * `GUILD_MEMBER_REMOVE` .. warning:: This intent is privileged, and requires enabling/whitelisting to use. """ GUILD_BANS = 1 << 2 """Subscribes to the following events: * `GUILD_BAN_ADD` * `GUILD_BAN_REMOVE` """ GUILD_EMOJIS = 1 << 3 """Subscribes to the following events: * `GUILD_EMOJIS_UPDATE` """ GUILD_INTEGRATIONS = 1 << 4 """Subscribes to the following events: * `INTEGRATION_CREATE` * `INTEGRATION_DELETE` * `INTEGRATION_UPDATE` """ GUILD_WEBHOOKS = 1 << 5 """Subscribes to the following events: * `WEBHOOKS_UPDATE` """ GUILD_INVITES = 1 << 6 """Subscribes to the following events: * `INVITE_CREATE` * `INVITE_DELETE` """ GUILD_VOICE_STATES = 1 << 7 """Subscribes to the following events: * `VOICE_STATE_UPDATE` """ GUILD_PRESENCES = 1 << 8 """Subscribes to the following events: * `PRESENCE_UPDATE` .. warning:: This intent is privileged, and requires enabling/whitelisting to use.""" GUILD_MESSAGES = 1 << 9 """Subscribes to the following events: * `MESSAGE_CREATE` (in guilds only) * `MESSAGE_UPDATE` (in guilds only) * `MESSAGE_DELETE` (in guilds only) * `MESSAGE_BULK_DELETE` (in guilds only) """ GUILD_MESSAGE_REACTIONS = 1 << 10 """Subscribes to the following events: * `MESSAGE_REACTION_ADD` (in guilds only) * `MESSAGE_REACTION_REMOVE` (in guilds only) * `MESSAGE_REACTION_REMOVE_ALL` (in guilds only) * `MESSAGE_REACTION_REMOVE_EMOJI` (in guilds only) """ GUILD_MESSAGE_TYPING = 1 << 11 """Subscribes to the following events: * `TYPING_START` (in guilds only) """ DM_MESSAGES = 1 << 12 """Subscribes to the following events: * `MESSAGE_CREATE` (in private message channels (non-guild bound) only) * `MESSAGE_UPDATE` (in private message channels (non-guild bound) only) * `MESSAGE_DELETE` (in private message channels (non-guild bound) only) """ DM_MESSAGE_REACTIONS = 1 << 13 """Subscribes to the following events: * `MESSAGE_REACTION_ADD` (in private message channels (non-guild bound) only) * `MESSAGE_REACTION_REMOVE` (in private message channels (non-guild bound) only) * `MESSAGE_REACTION_REMOVE_ALL` (in private message channels (non-guild bound) only) * `MESSAGE_REACTION_REMOVE_EMOJI` (in private message channels (non-guild bound) only) """ DM_MESSAGE_TYPING = 1 << 14 """Subscribes to the following events: * `TYPING_START` (in private message channels (non-guild bound) only) """ MESSAGE_CONTENT = 1 << 15 """Receive message content for all messages. DM's to the bot and messages that mention it are exempt from this. .. warning:: This intent is privileged, and requires enabling/whitelisting to use. """ GUILD_SCHEDULED_EVENTS = 1 << 16 """Subscribes to the following events: * `GUILD_SCHEDULED_EVENT_CREATE` * `GUILD_SCHEDULED_EVENT_UPDATE` * `GUILD_SCHEDULED_EVENT_DELETE` * `GUILD_SCHEDULED_EVENT_USER_ADD` * `GUILD_SCHEDULED_EVENT_USER_REMOVE` """ # Annoyingly, enums hide classmethods and staticmethods from __dir__ in # EnumMeta which means if I make methods to generate these, then stuff # will not be documented by pdoc. Alas, my dream of being smart with # operator.or_ and functools.reduce has been destroyed. ALL_GUILDS_UNPRIVILEGED = ( GUILDS | GUILD_BANS | GUILD_EMOJIS | GUILD_INTEGRATIONS | GUILD_WEBHOOKS | GUILD_INVITES | GUILD_VOICE_STATES | GUILD_MESSAGES | GUILD_MESSAGE_REACTIONS | GUILD_MESSAGE_TYPING | GUILD_SCHEDULED_EVENTS ) """All unprivileged guild-related intents.""" ALL_GUILDS_PRIVILEGED = GUILD_MEMBERS | GUILD_PRESENCES """All privileged guild intents. .. warning:: This set of intent is privileged, and requires enabling/whitelisting to use. """ ALL_GUILDS = ALL_GUILDS_UNPRIVILEGED | ALL_GUILDS_PRIVILEGED """All unprivileged guild intents and all privileged guild intents. This combines `Intents.ALL_GUILDS_UNPRIVILEGED` and `Intents.ALL_GUILDS_PRIVILEGED`. .. warning:: This set of intent is privileged, and requires enabling/whitelisting to use. """ ALL_DMS = DM_MESSAGES | DM_MESSAGE_TYPING | DM_MESSAGE_REACTIONS """All private message channel (non-guild bound) intents.""" ALL_MESSAGES = DM_MESSAGES | GUILD_MESSAGES """All message intents.""" ALL_MESSAGE_REACTIONS = DM_MESSAGE_REACTIONS | GUILD_MESSAGE_REACTIONS """All message reaction intents.""" ALL_MESSAGE_TYPING = DM_MESSAGE_TYPING | GUILD_MESSAGE_TYPING """All typing indicator intents.""" ALL_UNPRIVILEGED = ALL_GUILDS_UNPRIVILEGED | ALL_DMS """All unprivileged intents.""" ALL_PRIVILEGED = ALL_GUILDS_PRIVILEGED | MESSAGE_CONTENT """All privileged intents. .. warning:: This set of intent is privileged, and requires enabling/whitelisting to use. """ ALL = ALL_UNPRIVILEGED | ALL_PRIVILEGED """All unprivileged and privileged intents. .. warning:: This set of intent is privileged, and requires enabling/whitelisting to use. """ @property def is_privileged(self) -> bool: """Determine whether the intent requires elevated privileges. If this is `True`, you will be required to opt-in to using this intent on the Discord Developer Portal before you can utilise it in your application. """ return bool(self & self.ALL_PRIVILEGED)
View Source
@typing.final class Intents(enums.Flag): """Represents an intent on the gateway. This is a bitfield representation of all the categories of event that you wish to receive. Any events not in an intent category will be fired regardless of what intents you provide. .. note:: Discord now places limits on certain events you can receive without whitelisting your bot first. On the `Bot` tab in the developer's portal for your bot, you should now have the option to enable functionality for receiving these events. If you attempt to request an intent type that you have not whitelisted your bot for, you will be disconnected on startup with a `4014` closure code. .. warning:: If you are using the V7 Gateway, you will be REQUIRED to provide some form of intent value when you connect. Failure to do so may result in immediate termination of the session server-side. This enum is an `enum.IntFlag`, which means that you can use bitwise operators to join and splice multiple intents into one value. For example, if we wish to only refer to the `GUILDS` intent, then it is simply a case of accessing it normally. ```py my_intents = Intents.GUILDS ``` If we wanted to have several intents grouped together, we would use the bitwise-or operator to combine them (`|`). This can be done in-place with the `|=` operator if needed. ```py # One or two values that fit on one line. my_intents = Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES # Several intents together. You may find it useful to format these like # so to keep your code readable. my_intents = ( Intents.GUILDS | Intents.GUILD_BANS | Intents.GUILD_EMOJIS | Intents.GUILD_INTEGRATIONS | Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES ) ``` To check if an intent **is present** in a given intents bitfield, you can use the bitwise-and operator (`&`) to check. This returns the "intersection" or "crossover" between the left and right-hand side of the `&`. You can then use the `==` operator to check that specific values are present. You can check in-place with the `&=` operator if needed. ```py # Check if an intent is set: if (my_intents & Intents.GUILD_MESSAGES) == Intents.GUILD_MESSAGES: print("Guild messages are enabled") # Checking if ALL in a combination are set: expected_intents = (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES) if (my_intents & expected_intents) == expected_intents: print("Messages are enabled in guilds and private messages.") # Checking if AT LEAST ONE in a combination is set: expected_intents = (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES) if my_intents & expected_intents: print("Messages are enabled in guilds or private messages.") ``` Removing one or more intents from a combination can be done with the bitwise-xor (`^`) operator. The `^=` operator can do this in-place. ```py # Remove GUILD_MESSAGES my_intents = my_intents ^ Intents.GUILD_MESSAGES # or, simplifying: my_intents ^= Intents.GUILD_MESSAGES # Remove all messages events. my_intents = my_intents ^ (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES) # or, simplifying my_intents ^= (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES) ``` What is and is not covered by intents? -------------------------------------- The following unprivileged events require intents to be dispatched: - `GUILD_CREATE` - `GUILD_UPDATE` - `GUILD_DELETE` - `GUILD_ROLE_CREATE` - `GUILD_ROLE_UPDATE` - `GUILD_ROLE_DELETE` - `GUILD_BAN_ADD` - `GUILD_BAN_REMOVE` - `GUILD_EMOJIS_UPDATE` - `INTEGRATION_CREATE` - `INTEGRATION_DELETE` - `INTEGRATION_UPDATE` - `INVITE_CREATE` - `INVITE_DELETE` - `CHANNEL_CREATE` - `CHANNEL_UPDATE` - `CHANNEL_DELETE` - `CHANNEL_PINS_UPDATE (guilds only)` - `MESSAGE_CREATE` - `MESSAGE_UPDATE` - `MESSAGE_DELETE` - `MESSAGE_BULK_DELETE` - `MESSAGE_REACTION_ADD` - `MESSAGE_REACTION_REMOVE` - `MESSAGE_REACTION_REMOVE_ALL` - `MESSAGE_REACTION_REMOVE_EMOJI` - `TYPING_START` - `VOICE_STATE_UPDATE` - `WEBHOOKS_UPDATE` The following privileged events require intents to be dispatched: - `GUILD_MEMBER_ADD` - `GUILD_MEMBER_UPDATE` - `GUILD_MEMBER_REMOVE` - `PRESENCE_UPDATE` All events not listed above will be dispatched regardless of whether intents are used or not. """ NONE = 0 """Represents no intents.""" GUILDS = 1 << 0 """Subscribes to the following events: * `GUILD_CREATE` * `GUILD_UPDATE` * `GUILD_DELETE` * `GUILD_ROLE_CREATE` * `GUILD_ROLE_UPDATE` * `GUILD_ROLE_DELETE` * `CHANNEL_CREATE` * `CHANNEL_UPDATE` * `CHANNEL_DELETE` * `CHANNEL_PINS_UPDATE` """ GUILD_MEMBERS = 1 << 1 """Subscribes to the following events: * `GUILD_MEMBER_ADD` * `GUILD_MEMBER_UPDATE` * `GUILD_MEMBER_REMOVE` .. warning:: This intent is privileged, and requires enabling/whitelisting to use. """ GUILD_BANS = 1 << 2 """Subscribes to the following events: * `GUILD_BAN_ADD` * `GUILD_BAN_REMOVE` """ GUILD_EMOJIS = 1 << 3 """Subscribes to the following events: * `GUILD_EMOJIS_UPDATE` """ GUILD_INTEGRATIONS = 1 << 4 """Subscribes to the following events: * `INTEGRATION_CREATE` * `INTEGRATION_DELETE` * `INTEGRATION_UPDATE` """ GUILD_WEBHOOKS = 1 << 5 """Subscribes to the following events: * `WEBHOOKS_UPDATE` """ GUILD_INVITES = 1 << 6 """Subscribes to the following events: * `INVITE_CREATE` * `INVITE_DELETE` """ GUILD_VOICE_STATES = 1 << 7 """Subscribes to the following events: * `VOICE_STATE_UPDATE` """ GUILD_PRESENCES = 1 << 8 """Subscribes to the following events: * `PRESENCE_UPDATE` .. warning:: This intent is privileged, and requires enabling/whitelisting to use.""" GUILD_MESSAGES = 1 << 9 """Subscribes to the following events: * `MESSAGE_CREATE` (in guilds only) * `MESSAGE_UPDATE` (in guilds only) * `MESSAGE_DELETE` (in guilds only) * `MESSAGE_BULK_DELETE` (in guilds only) """ GUILD_MESSAGE_REACTIONS = 1 << 10 """Subscribes to the following events: * `MESSAGE_REACTION_ADD` (in guilds only) * `MESSAGE_REACTION_REMOVE` (in guilds only) * `MESSAGE_REACTION_REMOVE_ALL` (in guilds only) * `MESSAGE_REACTION_REMOVE_EMOJI` (in guilds only) """ GUILD_MESSAGE_TYPING = 1 << 11 """Subscribes to the following events: * `TYPING_START` (in guilds only) """ DM_MESSAGES = 1 << 12 """Subscribes to the following events: * `MESSAGE_CREATE` (in private message channels (non-guild bound) only) * `MESSAGE_UPDATE` (in private message channels (non-guild bound) only) * `MESSAGE_DELETE` (in private message channels (non-guild bound) only) """ DM_MESSAGE_REACTIONS = 1 << 13 """Subscribes to the following events: * `MESSAGE_REACTION_ADD` (in private message channels (non-guild bound) only) * `MESSAGE_REACTION_REMOVE` (in private message channels (non-guild bound) only) * `MESSAGE_REACTION_REMOVE_ALL` (in private message channels (non-guild bound) only) * `MESSAGE_REACTION_REMOVE_EMOJI` (in private message channels (non-guild bound) only) """ DM_MESSAGE_TYPING = 1 << 14 """Subscribes to the following events: * `TYPING_START` (in private message channels (non-guild bound) only) """ MESSAGE_CONTENT = 1 << 15 """Receive message content for all messages. DM's to the bot and messages that mention it are exempt from this. .. warning:: This intent is privileged, and requires enabling/whitelisting to use. """ GUILD_SCHEDULED_EVENTS = 1 << 16 """Subscribes to the following events: * `GUILD_SCHEDULED_EVENT_CREATE` * `GUILD_SCHEDULED_EVENT_UPDATE` * `GUILD_SCHEDULED_EVENT_DELETE` * `GUILD_SCHEDULED_EVENT_USER_ADD` * `GUILD_SCHEDULED_EVENT_USER_REMOVE` """ # Annoyingly, enums hide classmethods and staticmethods from __dir__ in # EnumMeta which means if I make methods to generate these, then stuff # will not be documented by pdoc. Alas, my dream of being smart with # operator.or_ and functools.reduce has been destroyed. ALL_GUILDS_UNPRIVILEGED = ( GUILDS | GUILD_BANS | GUILD_EMOJIS | GUILD_INTEGRATIONS | GUILD_WEBHOOKS | GUILD_INVITES | GUILD_VOICE_STATES | GUILD_MESSAGES | GUILD_MESSAGE_REACTIONS | GUILD_MESSAGE_TYPING | GUILD_SCHEDULED_EVENTS ) """All unprivileged guild-related intents.""" ALL_GUILDS_PRIVILEGED = GUILD_MEMBERS | GUILD_PRESENCES """All privileged guild intents. .. warning:: This set of intent is privileged, and requires enabling/whitelisting to use. """ ALL_GUILDS = ALL_GUILDS_UNPRIVILEGED | ALL_GUILDS_PRIVILEGED """All unprivileged guild intents and all privileged guild intents. This combines `Intents.ALL_GUILDS_UNPRIVILEGED` and `Intents.ALL_GUILDS_PRIVILEGED`. .. warning:: This set of intent is privileged, and requires enabling/whitelisting to use. """ ALL_DMS = DM_MESSAGES | DM_MESSAGE_TYPING | DM_MESSAGE_REACTIONS """All private message channel (non-guild bound) intents.""" ALL_MESSAGES = DM_MESSAGES | GUILD_MESSAGES """All message intents.""" ALL_MESSAGE_REACTIONS = DM_MESSAGE_REACTIONS | GUILD_MESSAGE_REACTIONS """All message reaction intents.""" ALL_MESSAGE_TYPING = DM_MESSAGE_TYPING | GUILD_MESSAGE_TYPING """All typing indicator intents.""" ALL_UNPRIVILEGED = ALL_GUILDS_UNPRIVILEGED | ALL_DMS """All unprivileged intents.""" ALL_PRIVILEGED = ALL_GUILDS_PRIVILEGED | MESSAGE_CONTENT """All privileged intents. .. warning:: This set of intent is privileged, and requires enabling/whitelisting to use. """ ALL = ALL_UNPRIVILEGED | ALL_PRIVILEGED """All unprivileged and privileged intents. .. warning:: This set of intent is privileged, and requires enabling/whitelisting to use. """ @property def is_privileged(self) -> bool: """Determine whether the intent requires elevated privileges. If this is `True`, you will be required to opt-in to using this intent on the Discord Developer Portal before you can utilise it in your application. """ return bool(self & self.ALL_PRIVILEGED)
Represents an intent on the gateway.
This is a bitfield representation of all the categories of event that you wish to receive.
Any events not in an intent category will be fired regardless of what intents you provide.
Note: Discord now places limits on certain events you can receive without whitelisting your bot first. On the Bot tab in the developer's portal for your bot, you should now have the option to enable functionality for receiving these events.
If you attempt to request an intent type that you have not whitelisted your bot for, you will be disconnected on startup with a 4014 closure code.
Warning: If you are using the V7 Gateway, you will be REQUIRED to provide some form of intent value when you connect. Failure to do so may result in immediate termination of the session server-side.
This enum is an enum.IntFlag, which means that you can use bitwise operators to join and splice multiple intents into one value.
For example, if we wish to only refer to the GUILDS intent, then it is simply a case of accessing it normally.
my_intents = Intents.GUILDS
If we wanted to have several intents grouped together, we would use the bitwise-or operator to combine them (|). This can be done in-place with the |= operator if needed.
# One or two values that fit on one line.
my_intents = Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES
# Several intents together. You may find it useful to format these like
# so to keep your code readable.
my_intents = (
Intents.GUILDS |
Intents.GUILD_BANS |
Intents.GUILD_EMOJIS |
Intents.GUILD_INTEGRATIONS |
Intents.GUILD_MESSAGES |
Intents.PRIVATE_MESSAGES
)
To check if an intent is present in a given intents bitfield, you can use the bitwise-and operator (&) to check. This returns the "intersection" or "crossover" between the left and right-hand side of the &. You can then use the == operator to check that specific values are present. You can check in-place with the &= operator if needed.
# Check if an intent is set:
if (my_intents & Intents.GUILD_MESSAGES) == Intents.GUILD_MESSAGES:
print("Guild messages are enabled")
# Checking if ALL in a combination are set:
expected_intents = (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES)
if (my_intents & expected_intents) == expected_intents:
print("Messages are enabled in guilds and private messages.")
# Checking if AT LEAST ONE in a combination is set:
expected_intents = (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES)
if my_intents & expected_intents:
print("Messages are enabled in guilds or private messages.")
Removing one or more intents from a combination can be done with the bitwise-xor (^) operator. The ^= operator can do this in-place.
# Remove GUILD_MESSAGES
my_intents = my_intents ^ Intents.GUILD_MESSAGES
# or, simplifying:
my_intents ^= Intents.GUILD_MESSAGES
# Remove all messages events.
my_intents = my_intents ^ (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES)
# or, simplifying
my_intents ^= (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES)
What is and is not covered by intents?
The following unprivileged events require intents to be dispatched:
GUILD_CREATEGUILD_UPDATEGUILD_DELETEGUILD_ROLE_CREATEGUILD_ROLE_UPDATEGUILD_ROLE_DELETEGUILD_BAN_ADDGUILD_BAN_REMOVEGUILD_EMOJIS_UPDATEINTEGRATION_CREATEINTEGRATION_DELETEINTEGRATION_UPDATEINVITE_CREATEINVITE_DELETECHANNEL_CREATECHANNEL_UPDATECHANNEL_DELETECHANNEL_PINS_UPDATE (guilds only)MESSAGE_CREATEMESSAGE_UPDATEMESSAGE_DELETEMESSAGE_BULK_DELETEMESSAGE_REACTION_ADDMESSAGE_REACTION_REMOVEMESSAGE_REACTION_REMOVE_ALLMESSAGE_REACTION_REMOVE_EMOJITYPING_STARTVOICE_STATE_UPDATEWEBHOOKS_UPDATE
The following privileged events require intents to be dispatched:
GUILD_MEMBER_ADDGUILD_MEMBER_UPDATEGUILD_MEMBER_REMOVEPRESENCE_UPDATE
All events not listed above will be dispatched regardless of whether intents are used or not.
Variables and properties
All unprivileged and privileged intents.
Warning: This set of intent is privileged, and requires enabling/whitelisting to use.
All private message channel (non-guild bound) intents.
All unprivileged guild intents and all privileged guild intents.
This combines Intents.ALL_GUILDS_UNPRIVILEGED and Intents.ALL_GUILDS_PRIVILEGED.
Warning: This set of intent is privileged, and requires enabling/whitelisting to use.
All privileged guild intents.
Warning: This set of intent is privileged, and requires enabling/whitelisting to use.
All unprivileged guild-related intents.
All message intents.
All message reaction intents.
All typing indicator intents.
All privileged intents.
Warning: This set of intent is privileged, and requires enabling/whitelisting to use.
All unprivileged intents.
Subscribes to the following events:
MESSAGE_CREATE(in private message channels (non-guild bound) only)MESSAGE_UPDATE(in private message channels (non-guild bound) only)MESSAGE_DELETE(in private message channels (non-guild bound) only)
Subscribes to the following events:
MESSAGE_REACTION_ADD(in private message channels (non-guild bound) only)MESSAGE_REACTION_REMOVE(in private message channels (non-guild bound) only)MESSAGE_REACTION_REMOVE_ALL(in private message channels (non-guild bound) only)MESSAGE_REACTION_REMOVE_EMOJI(in private message channels (non-guild bound) only)
Subscribes to the following events:
TYPING_START(in private message channels (non-guild bound) only)
Subscribes to the following events:
GUILD_CREATEGUILD_UPDATEGUILD_DELETEGUILD_ROLE_CREATEGUILD_ROLE_UPDATEGUILD_ROLE_DELETECHANNEL_CREATECHANNEL_UPDATECHANNEL_DELETECHANNEL_PINS_UPDATE
Subscribes to the following events:
GUILD_BAN_ADDGUILD_BAN_REMOVE
Subscribes to the following events:
GUILD_EMOJIS_UPDATE
Subscribes to the following events:
INTEGRATION_CREATEINTEGRATION_DELETEINTEGRATION_UPDATE
Subscribes to the following events:
INVITE_CREATEINVITE_DELETE
Subscribes to the following events:
GUILD_MEMBER_ADDGUILD_MEMBER_UPDATEGUILD_MEMBER_REMOVE
Warning: This intent is privileged, and requires enabling/whitelisting to use.
Subscribes to the following events:
MESSAGE_CREATE(in guilds only)MESSAGE_UPDATE(in guilds only)MESSAGE_DELETE(in guilds only)MESSAGE_BULK_DELETE(in guilds only)
Subscribes to the following events:
MESSAGE_REACTION_ADD(in guilds only)MESSAGE_REACTION_REMOVE(in guilds only)MESSAGE_REACTION_REMOVE_ALL(in guilds only)MESSAGE_REACTION_REMOVE_EMOJI(in guilds only)
Subscribes to the following events:
TYPING_START(in guilds only)
Subscribes to the following events:
PRESENCE_UPDATE
Warning: This intent is privileged, and requires enabling/whitelisting to use.
Subscribes to the following events:
GUILD_SCHEDULED_EVENT_CREATEGUILD_SCHEDULED_EVENT_UPDATEGUILD_SCHEDULED_EVENT_DELETEGUILD_SCHEDULED_EVENT_USER_ADDGUILD_SCHEDULED_EVENT_USER_REMOVE
Subscribes to the following events:
VOICE_STATE_UPDATE
Subscribes to the following events:
WEBHOOKS_UPDATE
Receive message content for all messages.
DM's to the bot and messages that mention it are exempt from this.
Warning: This intent is privileged, and requires enabling/whitelisting to use.
Represents no intents.
the denominator of a rational number in lowest terms
the imaginary part of a complex number
Determine whether the intent requires elevated privileges.
If this is True, you will be required to opt-in to using this intent on the Discord Developer Portal before you can utilise it in your application.
Return the name of the flag combination as a str.
the numerator of a rational number in lowest terms
the real part of a complex number
Return the int value of the flag.
Methods
View Source
def __call__(cls, value: int = 0) -> typing.Any: """Cast a value to the flag enum, returning the raw value that was passed if values not found.""" # We want to handle value invariantly to avoid issues brought in by different behaviours from sub-classed ints # and floats. This also ensures that .__int__ only returns an invariant int. value = int(value) try: return cls._value_to_member_map_[value] except KeyError: # We only need this ability here usually, so overloading operators # is an overkill and would add more overhead. if value < 0: # Convert to a positive value instead. return cls.__everything__ - ~value temp_members = cls._temp_members_ # For huge enums, don't ever cache anything. We could consume masses of memory otherwise # (e.g. Permissions) try: # Try to get a cached value. return temp_members[value] except KeyError: # If we can't find the value, just return what got casted in by generating a pseudomember # and caching it. We can't use weakref because int is not weak referenceable, annoyingly. pseudomember = cls.__new__(cls, value) pseudomember._name_ = None pseudomember._value_ = value temp_members[value] = pseudomember if len(temp_members) > _MAX_CACHED_MEMBERS: temp_members.popitem() return pseudomember
Cast a value to the flag enum, returning the raw value that was passed if values not found.
View Source
def all(self: _T, *flags: _T) -> bool: """Check if all of the given flags are part of this value. Returns ------- bool `True` if any of the given flags are part of this value. Otherwise, return `False`. """ return all((flag & self) == flag for flag in flags)
Check if all of the given flags are part of this value.
Returns
- bool:
Trueif any of the given flags are part of this value. Otherwise, returnFalse.
View Source
def any(self: _T, *flags: _T) -> bool: """Check if any of the given flags are part of this value. Returns ------- bool `True` if any of the given flags are part of this value. Otherwise, return `False`. """ return any((flag & self) == flag for flag in flags)
Check if any of the given flags are part of this value.
Returns
- bool:
Trueif any of the given flags are part of this value. Otherwise, returnFalse.
Return integer ratio.
Return a pair of integers, whose ratio is exactly equal to the original int and with a positive denominator.
>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)
Number of bits necessary to represent self in binary.
>>> bin(37)
'0b100101'
>>> (37).bit_length()
6
Returns self, the complex conjugate of any int.
View Source
def difference(self: _T, other: typing.Union[_T, int]) -> _T: """Perform a set difference with the other set. This will return all flags in this set that are not in the other value. Equivalent to using the subtraction `-` operator. """ return self.__class__(self & ~int(other))
Perform a set difference with the other set.
This will return all flags in this set that are not in the other value.
Equivalent to using the subtraction - operator.
Return the integer represented by the given array of bytes.
bytes Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol. byteorder The byte order used to represent the integer. If byteorder is 'big', the most significant byte is at the beginning of the byte array. If byteorder is 'little', the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder' as the byte order value. signed Indicates whether two's complement is used to represent the integer.
View Source
def intersection(self: _T, other: typing.Union[_T, int]) -> _T: """Return a combination of flags that are set for both given values. Equivalent to using the "AND" `&` operator. """ return self.__class__(self._value_ & int(other))
Return a combination of flags that are set for both given values.
Equivalent to using the "AND" & operator.
View Source
def invert(self: _T) -> _T: """Return a set of all flags not in the current set.""" return self.__class__(self.__class__.__everything__._value_ & ~self._value_)
Return a set of all flags not in the current set.
View Source
def is_disjoint(self: _T, other: typing.Union[_T, int]) -> bool: """Return whether two sets have a intersection or not. If the two sets have an intersection, then this returns `False`. If no common flag values exist between them, then this returns `True`. """ return not (self & other)
Return whether two sets have a intersection or not.
If the two sets have an intersection, then this returns False. If no common flag values exist between them, then this returns True.
View Source
def is_subset(self: _T, other: typing.Union[_T, int]) -> bool: """Return whether another set contains this set or not. Equivalent to using the "in" operator. """ return (self & other) == other
Return whether another set contains this set or not.
Equivalent to using the "in" operator.
View Source
def is_superset(self: _T, other: typing.Union[_T, int]) -> bool: """Return whether this set contains another set or not.""" return (self & other) == self
Return whether this set contains another set or not.
View Source
def is_disjoint(self: _T, other: typing.Union[_T, int]) -> bool: """Return whether two sets have a intersection or not. If the two sets have an intersection, then this returns `False`. If no common flag values exist between them, then this returns `True`. """ return not (self & other)
Return whether two sets have a intersection or not.
If the two sets have an intersection, then this returns False. If no common flag values exist between them, then this returns True.
View Source
def is_subset(self: _T, other: typing.Union[_T, int]) -> bool: """Return whether another set contains this set or not. Equivalent to using the "in" operator. """ return (self & other) == other
Return whether another set contains this set or not.
Equivalent to using the "in" operator.
View Source
def is_superset(self: _T, other: typing.Union[_T, int]) -> bool: """Return whether this set contains another set or not.""" return (self & other) == self
Return whether this set contains another set or not.
View Source
def none(self: _T, *flags: _T) -> bool: """Check if none of the given flags are part of this value. .. note:: This is essentially the opposite of `Flag.any`. Returns ------- bool `True` if none of the given flags are part of this value. Otherwise, return `False`. """ return not self.any(*flags)
Check if none of the given flags are part of this value.
Note: This is essentially the opposite of Flag.any.
Returns
- bool:
Trueif none of the given flags are part of this value. Otherwise, returnFalse.
View Source
def split(self: _T) -> typing.Sequence[_T]: """Return a list of all defined atomic values for this flag. Any unrecognised bits will be omitted for brevity. The result will be a name-sorted `typing.Sequence` of each member """ return sorted( (member for member in self.__class__._powers_of_2_to_member_map_.values() if member.value & self), # Assumption: powers of 2 already have a cached value. key=lambda m: m._name_, )
Return a list of all defined atomic values for this flag.
Any unrecognised bits will be omitted for brevity.
The result will be a name-sorted typing.Sequence of each member
View Source
def symmetric_difference(self: _T, other: typing.Union[_T, int]) -> _T: """Return a set with the symmetric differences of two flag sets. Equivalent to using the "XOR" `^` operator. For `a ^ b`, this can be considered the same as `(a - b) | (b - a)`. """ return self.__class__(self._value_ ^ int(other))
Return a set with the symmetric differences of two flag sets.
Equivalent to using the "XOR" ^ operator.
For a ^ b, this can be considered the same as (a - b) | (b - a).
View Source
def symmetric_difference(self: _T, other: typing.Union[_T, int]) -> _T: """Return a set with the symmetric differences of two flag sets. Equivalent to using the "XOR" `^` operator. For `a ^ b`, this can be considered the same as `(a - b) | (b - a)`. """ return self.__class__(self._value_ ^ int(other))
Return a set with the symmetric differences of two flag sets.
Equivalent to using the "XOR" ^ operator.
For a ^ b, this can be considered the same as (a - b) | (b - a).
Return an array of bytes representing an integer.
length Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes. byteorder The byte order used to represent the integer. If byteorder is 'big', the most significant byte is at the beginning of the byte array. If byteorder is 'little', the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder' as the byte order value. signed Determines whether two's complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.
View Source
def union(self: _T, other: typing.Union[_T, int]) -> _T: """Return a combination of all flags in this set and the other set. Equivalent to using the "OR" `~` operator. """ return self.__class__(self._value_ | int(other))
Return a combination of all flags in this set and the other set.
Equivalent to using the "OR" ~ operator.