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.

Attributes

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.

id#

The model’s unique ID.

Type:: int

Attributes

avatar
bot
discriminator
display_name
global_name
mention
name

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.

name#

The user’s username.

Type:: str

discriminator#

The user’s discriminator.

Note

If the user has migrated to the new username system, this will always be “0”.

Type:: str

global_name#

The user’s global name.

New in version 2.5.

Type:: str

avatar#

The avatar asset the user has.

Type:: Asset

bot#

If the user is a bot account.

Type:: bool

property display_name#: Returns the user’s display name.

property mention#: Returns a string that allows you to mention the given user.

Attributes

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:: ClientUser

Attributes

category
changed_roles
created_at
guild
jump_url
mention
name
overwrites
permissions_synced
position

Methods

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.

name#

The channel name.

Type:: str

guild#

The guild the channel belongs to.

Type:: Guild

position#

The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

Type:: int

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.

New 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.

Parameters:: obj (Union[Role, User]) – The role or user denoting whose overwrite to get.
Returns:: The permission overwrites for this object.
Return type:: PermissionOverwrite

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 a Member and the value is the overwrite as a PermissionOverwrite.

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.

New in version 1.3.

permissions_for(obj, /)[source]#

Handles permission resolution for the Member or Role.

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.

Parameters:: obj (Union[Member, Role]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.
Returns:: The resolved permissions for the member or role.
Return type:: Permissions

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:

None

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 a Member or a Role that belongs to guild.

The overwrite parameter, if given, must either be None or PermissionOverwrite. For convenience, you can pass in keyword arguments denoting Permissions attributes. If this is done, then you cannot mix the keyword arguments with the overwrite parameter.

If the overwrite parameter is None, 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, or None 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 or Member.

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.

New in version 1.1.

Parameters:

name (Optional[str]) – The name of the new channel. If not provided, defaults to this channel name.
reason (Optional[str]) – The reason for cloning this channel. Shows up on the audit log.
self (GCH) –

Returns:

The channel that was created.

Return type:

abc.GuildChannel

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.

New 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 with end, before, and after.
end (bool) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with beginning, before, and after.
before (Snowflake) – The channel that should be before our current channel. This is mutually exclusive with beginning, end, and after.
after (Snowflake) – The channel that should be after our current channel. This is mutually exclusive with beginning, end, and before.
offset (int) – The number of channels to offset the move by. For example, an offset of 2 with beginning=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 the beginning, end, before, and after parameters.
category (Optional[Snowflake]) – The category to move this channel under. If None 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:

None

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 to 0.
max_uses (int) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to 0.
temporary (bool) – Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to False.
unique (bool) – Indicates if a unique invite URL should be created. Defaults to True. If this is set to False 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.

New 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.

New 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.

New 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.

New in version 2.0.

Returns:

The invite that was created.

Return type:

Invite

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.

Methods

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. If None, 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 to True, return messages in oldest->newest order. Defaults to True if after is specified, otherwise False.

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 and async 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 to None (the default), then the embed parameter must be provided.

To upload a single file, the file parameter should be used with a single File object. To upload multiple files, the files parameter should be used with a list of File objects. Specifying both parameters will lead to an exception.

To upload a single embed, the embed parameter should be used with a single Embed object. To upload multiple embeds, the embeds parameter should be used with a list of Embed 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.

New 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 in allowed_mentions. If no object is passed at all then the defaults given by allowed_mentions are used instead.

New in version 1.4.
reference (Union[Message, MessageReference, PartialMessage]) –
A reference to the Message to which you are replying, this can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

New in version 1.6.
mention_author (Optional[bool]) –
If set, overrides the replied_user attribute of allowed_mentions.

New 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.

New in version 2.0.
stickers (Sequence[Union[GuildSticker, StickerItem]]) –
A list of stickers to upload. Must be a maximum of 3.

New 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.

New in version 2.4.
poll (Poll) –
The poll to send.

New in version 2.6.

Returns:

The message that was sent.

Return type:

Message

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 both file and files, or you specified both embed and embeds, or the reference object is not a Message, MessageReference or PartialMessage.

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:: None

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:

Message

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 complete Message.reactions data.

Returns:: The messages that are currently pinned.
Return type:: List[Message]
Raises:: HTTPException – Retrieving the pinned messages failed.

can_send(*objects)[source]#

Returns a bool indicating whether you have the permissions to send the object(s).

Returns:: Indicates whether you have the permissions to send the object(s).
Return type:: bool
Raises:: TypeError – An invalid type has been passed.

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 fail isinstance()/issubclass() checks.