Abstract Base Classes¶
An abstract base class (also known as an abc
) is a class that models can inherit
to get their behaviour. Abstract base classes should not be instantiated.
They are mainly there for usage with isinstance()
and issubclass()
.
This library has a module related to abstract base classes, in which all the ABCs are subclasses of
typing.Protocol
.
- class discord.abc.Snowflake[source]¶
An ABC that details the common operations on a Discord model.
Almost all Discord models meet this abstract base class.
If you want to create a snowflake on your own, consider using
Object
.
- class discord.abc.User[source]¶
An ABC that details the common operations on a Discord user.
The following implement this ABC:
This ABC must also implement
Snowflake
.- discriminator¶
The user’s discriminator.
Note
If the user has migrated to the new username system, this will always be “0”.
- Type:
- property display_name¶
Returns the user’s display name.
- property mention¶
Returns a string that allows you to mention the given user.
- class discord.abc.PrivateChannel[source]¶
An ABC that details the common operations on a private Discord channel.
The following implement this ABC:
This ABC must also implement
Snowflake
.- me¶
The user presenting yourself.
- Type:
- asyncclone
- asynccreate_invite
- asyncdelete
- asyncinvites
- asyncmove
- defoverwrites_for
- defpermissions_for
- asyncset_permissions
- class discord.abc.GuildChannel[source]¶
An ABC that details the common operations on a Discord guild channel.
The following implement this ABC:
This ABC must also implement
Snowflake
.- position¶
The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.
- Type:
- property changed_roles¶
Returns a list of roles that have been overridden from their default values in the
roles
attribute.
- property mention¶
The string that allows you to mention the channel.
- property jump_url¶
Returns a URL that allows the client to jump to the channel.
Added in version 2.0.
- property created_at¶
Returns the channel’s creation time in UTC.
- overwrites_for(obj)[source]¶
Returns the channel-specific overwrites for a member or a role.
- property overwrites¶
Returns all of the channel’s overwrites.
This is returned as a dictionary where the key contains the target which can be either a
Role
or aMember
and the value is the overwrite as aPermissionOverwrite
.- Returns:
The channel’s permission overwrites.
- Return type:
Dict[Union[
Role
,Member
],PermissionOverwrite
]
- property category¶
The category this channel belongs to.
If there is no category then this is
None
.
- property permissions_synced¶
Whether the permissions for this channel are synced with the category it belongs to.
If there is no category then this is
False
.Added in version 1.3.
- permissions_for(obj, /)[source]¶
Handles permission resolution for the
Member
orRole
.This function takes into consideration the following cases:
Guild owner
Guild roles
Channel overrides
Member overrides
If a
Role
is passed, then it checks the permissions someone with that role would have, which is essentially:The default role permissions
The permissions of the role used as a parameter
The default role permission overwrites
The permission overwrites of the role used as a parameter
Changed in version 2.0: The object passed in can now be a role object.
- await delete(*, reason=None)[source]¶
This function is a coroutine.
Deletes the channel.
You must have
manage_channels
permission to use this.- Parameters:
reason (Optional[
str
]) – The reason for deleting this channel. Shows up on the audit log.- Raises:
Forbidden – You do not have proper permissions to delete the channel.
NotFound – The channel was not found or was already deleted.
HTTPException – Deleting the channel failed.
- Return type:
- await set_permissions(target, *, overwrite=..., reason=None, **permissions)[source]¶
This function is a coroutine.
Sets the channel specific permission overwrites for a target in the channel.
The
target
parameter should either be aMember
or aRole
that belongs to guild.The
overwrite
parameter, if given, must either beNone
orPermissionOverwrite
. For convenience, you can pass in keyword arguments denotingPermissions
attributes. If this is done, then you cannot mix the keyword arguments with theoverwrite
parameter.If the
overwrite
parameter isNone
, then the permission overwrites are deleted.You must have the
manage_roles
permission to use this.Note
This method replaces the old overwrites with the ones given.
Examples
Setting allow and deny:
await message.channel.set_permissions(message.author, read_messages=True, send_messages=False)
Deleting overwrites
await channel.set_permissions(member, overwrite=None)
Using
PermissionOverwrite
overwrite = discord.PermissionOverwrite() overwrite.send_messages = False overwrite.read_messages = True await channel.set_permissions(member, overwrite=overwrite)
- Parameters:
target (Union[
Member
,Role
]) – The member or role to overwrite permissions for.overwrite (Optional[
PermissionOverwrite
]) – The permissions to allow and deny to the target, orNone
to delete the overwrite.**permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with
overwrite
.reason (Optional[
str
]) – The reason for doing this action. Shows up on the audit log.
- Raises:
Forbidden – You do not have permissions to edit channel specific permissions.
HTTPException – Editing channel specific permissions failed.
NotFound – The role or member being edited is not part of the guild.
InvalidArgument – The overwrite parameter invalid or the target type was not
Role
orMember
.
- await clone(*, name=None, reason=None)[source]¶
This function is a coroutine.
Clones this channel. This creates a channel with the same properties as this channel.
You must have the
manage_channels
permission to do this.Added in version 1.1.
- Parameters:
- Returns:
The channel that was created.
- Return type:
- Raises:
Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.
- await move(**kwargs)[source]¶
This function is a coroutine.
A rich interface to help move a channel relative to other channels.
If exact position movement is required,
edit
should be used instead.You must have the
manage_channels
permission to do this.Note
Voice channels will always be sorted below text channels. This is a Discord limitation.
Added in version 1.7.
- Parameters:
beginning (
bool
) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive withend
,before
, andafter
.end (
bool
) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive withbeginning
,before
, andafter
.before (
Snowflake
) – The channel that should be before our current channel. This is mutually exclusive withbeginning
,end
, andafter
.after (
Snowflake
) – The channel that should be after our current channel. This is mutually exclusive withbeginning
,end
, andbefore
.offset (
int
) – The number of channels to offset the move by. For example, an offset of2
withbeginning=True
would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after thebeginning
,end
,before
, andafter
parameters.category (Optional[
Snowflake
]) – The category to move this channel under. IfNone
is given then it moves it out of the category. This parameter is ignored if moving a category channel.sync_permissions (
bool
) – Whether to sync the permissions with the category (if given).reason (
str
) – The reason for the move.
- Raises:
InvalidArgument – An invalid position was given or a bad mix of arguments was passed.
Forbidden – You do not have permissions to move the channel.
HTTPException – Moving the channel failed.
- Return type:
- await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, target_event=None, target_type=None, target_user=None, target_application_id=None)[source]¶
This function is a coroutine.
Creates an instant invite from a text or voice channel.
You must have the
create_instant_invite
permission to do this.- Parameters:
max_age (
int
) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to0
.max_uses (
int
) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to0
.temporary (
bool
) – Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults toFalse
.unique (
bool
) – Indicates if a unique invite URL should be created. Defaults to True. If this is set toFalse
then it will return a previously created invite.reason (Optional[
str
]) – The reason for creating this invite. Shows up on the audit log.target_type (Optional[
InviteTarget
]) –The type of target for the voice channel invite, if any.
Added in version 2.0.
target_user (Optional[
User
]) –The user whose stream to display for this invite, required if target_type is TargetType.stream. The user must be streaming in the channel.
Added in version 2.0.
target_application_id (Optional[
int
]) –The id of the embedded application for the invite, required if target_type is TargetType.embedded_application.
Added in version 2.0.
target_event (Optional[
ScheduledEvent
]) –The scheduled event object to link to the event. Shortcut to
Invite.set_scheduled_event()
See
Invite.set_scheduled_event()
for more info on event invite linking.Added in version 2.0.
- Returns:
The invite that was created.
- Return type:
- Raises:
HTTPException – Invite creation failed.
NotFound – The channel that was passed is a category or an invalid channel.
- await invites()[source]¶
This function is a coroutine.
Returns a list of all active instant invites from this channel.
You must have
manage_channels
to get this information.- Returns:
The list of invites that are currently active.
- Return type:
List[
Invite
]- Raises:
Forbidden – You do not have proper permissions to get the information.
HTTPException – An error occurred while fetching the information.
- defcan_send
- asyncfetch_message
- defhistory
- asyncpins
- asyncsend
- asynctrigger_typing
- deftyping
- class discord.abc.Messageable[source]¶
An ABC that details the common operations on a model that can send messages.
The following implement this ABC:
- async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)[source]¶
Returns an
AsyncIterator
that enables receiving the destination’s message history.You must have
read_message_history
permissions to use this.- Parameters:
limit (Optional[
int
]) – The number of messages to retrieve. IfNone
, retrieves every message in the channel. Note, however, that this would make it a slow operation.before (Optional[Union[
Snowflake
,datetime.datetime
]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.after (Optional[Union[
Snowflake
,datetime.datetime
]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.around (Optional[Union[
Snowflake
,datetime.datetime
]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number, then this will return at most limit + 1 messages.oldest_first (Optional[
bool
]) – If set toTrue
, return messages in oldest->newest order. Defaults toTrue
ifafter
is specified, otherwiseFalse
.
- Yields:
Message
– The message with the message data parsed.- Raises:
Forbidden – You do not have permissions to get channel message history.
HTTPException – The request to get message history failed.
- Return type:
HistoryIterator
Examples
Usage
counter = 0 async for message in channel.history(limit=200): if message.author == client.user: counter += 1
Flattening into a list:
messages = await channel.history(limit=123).flatten() # messages is now a list of Message...
All parameters are optional.
- async with typing()[source]¶
Returns a context manager that allows you to type for an indefinite period of time.
This is useful for denoting long computations in your bot. :rtype:
Typing
Note
This is both a regular context manager and an async context manager. This means that both
with
andasync with
work with this.Example Usage:
async with channel.typing(): # simulate something heavy await asyncio.sleep(10) await channel.send('done!')
- await send(content=None, *, tts=None, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, enforce_nonce=None, allowed_mentions=None, reference=None, mention_author=None, view=None, poll=None, suppress=None, silent=None)[source]¶
This function is a coroutine.
Sends a message to the destination with the content given.
The content must be a type that can convert to a string through
str(content)
. If the content is set toNone
(the default), then theembed
parameter must be provided.To upload a single file, the
file
parameter should be used with a singleFile
object. To upload multiple files, thefiles
parameter should be used with alist
ofFile
objects. Specifying both parameters will lead to an exception.To upload a single embed, the
embed
parameter should be used with a singleEmbed
object. To upload multiple embeds, theembeds
parameter should be used with alist
ofEmbed
objects. Specifying both parameters will lead to an exception.- Parameters:
content (Optional[
str
]) – The content of the message to send.tts (
bool
) – Indicates if the message should be sent using text-to-speech.embed (
Embed
) – The rich embed for the content.file (
File
) – The file to upload.files (List[
File
]) – A list of files to upload. Must be a maximum of 10.nonce (Union[
str
,int
]) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.enforce_nonce (Optional[
bool
]) –Whether
nonce
is enforced to be validated.Added in version 2.5.
delete_after (
float
) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.allowed_mentions (
AllowedMentions
) –Controls the mentions being processed in this message. If this is passed, then the object is merged with
allowed_mentions
. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set inallowed_mentions
. If no object is passed at all then the defaults given byallowed_mentions
are used instead.Added in version 1.4.
reference (Union[
Message
,MessageReference
,PartialMessage
]) –A reference to the
Message
to which you are replying, this can be created usingto_reference()
or passed directly as aMessage
. You can control whether this mentions the author of the referenced message using thereplied_user
attribute ofallowed_mentions
or by settingmention_author
.Added in version 1.6.
mention_author (Optional[
bool
]) –If set, overrides the
replied_user
attribute ofallowed_mentions
.Added in version 1.6.
view (
discord.ui.View
) – A Discord UI View to add to the message.embeds (List[
Embed
]) –A list of embeds to upload. Must be a maximum of 10.
Added in version 2.0.
stickers (Sequence[Union[
GuildSticker
,StickerItem
]]) –A list of stickers to upload. Must be a maximum of 3.
Added in version 2.0.
suppress (
bool
) – Whether to suppress embeds for the message.silent (
bool
) –Whether to suppress push and desktop notifications for the message.
Added in version 2.4.
poll (
Poll
) –The poll to send.
Added in version 2.6.
- Returns:
The message that was sent.
- Return type:
- Raises:
HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
InvalidArgument – The
files
list is not of the appropriate size, you specified bothfile
andfiles
, or you specified bothembed
andembeds
, or thereference
object is not aMessage
,MessageReference
orPartialMessage
.
- await trigger_typing()[source]¶
This function is a coroutine.
Triggers a typing indicator to the destination.
Typing indicator will go away after 10 seconds, or after a message is sent.
- Return type:
- await fetch_message(id, /)[source]¶
This function is a coroutine.
Retrieves a single
Message
from the destination.- Parameters:
id (
int
) – The message ID to look for.- Returns:
The message asked for.
- Return type:
- Raises:
NotFound – The specified message was not found.
Forbidden – You do not have the permissions required to get a message.
HTTPException – Retrieving the message failed.
- await pins()[source]¶
This function is a coroutine.
Retrieves all messages that are currently pinned in the channel.
Note
Due to a limitation with the Discord API, the
Message
objects returned by this method do not contain completeMessage.reactions
data.- Returns:
The messages that are currently pinned.
- Return type:
List[
Message
]- Raises:
HTTPException – Retrieving the pinned messages failed.
- class discord.abc.Connectable[source]¶
An ABC that details the common operations on a channel that can connect to a voice server.
The following implement this ABC:
Note
This ABC is not decorated with
typing.runtime_checkable()
, so will failisinstance()
/issubclass()
checks.