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

Added 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: str

Returns the user’s display name.

property mention: str

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

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

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

    Added in version 1.4.

  • reference (Union[Message, MessageReference, PartialMessage]) –

    A reference to the Message being replied to or forwarded. This can be created using to_reference(). When replying, 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.

    Added in version 1.6.

  • mention_author (Optional[bool]) –

    If set, overrides the replied_user attribute of allowed_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:

Message

Raises:
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.

pins(*, limit=50, before=None)[source]

Returns a MessagePinIterator that enables receiving the destination’s pinned messages.

You must have read_message_history permissions to use this.

Warning

Starting from version 3.0, await channel.pins() will no longer return a list of Message. See examples below for new usage instead.

Parameters:

  • limit (Optional[int]) – The number of pinned messages to retrieve. If None, retrieves every pinned message in the channel.

  • before (Optional[Union[Snowflake, datetime.datetime]]) – Retrieve messages pinned before this datetime. 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.

Yields:

MessagePin – The pinned message.

Raises:

  • Forbidden – You do not have permissions to get pinned messages.

  • HTTPException – The request to get pinned messages failed.

Return type:

MessagePinIterator

Examples

Usage

counter = 0
async for pin in channel.pins(limit=250):
    if pin.message.author == client.user:
        counter += 1

Flattening into a list:

pins = await channel.pins(limit=None).flatten()
# pins is now a list of MessagePin...

All parameters are optional.

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.