Abstract Base Classes¶

This section documents everything under disnake.abc.*.

Abstract Base Classes (commonly referred to as ABC) are classes that other classes can inherit to get or override specific behaviour. Read more about them here.

Classes¶

Snowflake¶

Attributes

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

User¶

Attributes

avatar
bot
discriminator
display_name
global_name
mention
name

class disnake.abc.User[source]¶

An ABC that details the common operations on a Discord user.

The following classes implement this ABC:

This ABC must also implement Snowflake.

name¶

The user’s username.

Type:: str

discriminator¶

The user’s discriminator.

Note

This is being phased out by Discord; the username system is moving away from username#discriminator to users having a globally unique username. The value of a single zero ("0") indicates that the user has been migrated to the new system. See the help article for details.

Type:: str

global_name¶

The user’s global display name, if set. This takes precedence over name when shown.

New in version 2.9.

Type:: str | None

bot¶

Whether the user is a bot account.

Type:: bool

property display_name[source]¶

Returns the user’s display name.

Type:: str

property mention[source]¶

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

Type:: str

property avatar[source]¶

Returns an Asset for the avatar the user has.

Type:: Asset | None

PrivateChannel¶

Attributes

class disnake.abc.PrivateChannel[source]¶

An ABC that details the common operations on a private Discord channel.

The following classes implement this ABC:

This ABC must also implement Snowflake.

me¶

The user representing yourself.

Type:: ClientUser

GuildChannel¶

Attributes

category
changed_roles
created_at
flags
guild
jump_url
mention
name
overwrites
permissions_synced
position

Methods

asyncclone
asynccreate_invite
asyncdelete
asyncinvites
asyncmove
defoverwrites_for
defpermissions_for
asyncset_permissions

class disnake.abc.GuildChannel[source]¶

An ABC that details the common operations on a Discord guild channel.

The following classes implement this ABC:

This ABC must also implement abc.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[source]¶

Returns a list of roles that have been overridden from their default values in the Guild.roles attribute.

Type:: list[Role]

property mention[source]¶

The string that allows you to mention the channel.

Type:: str

property created_at[source]¶

Returns the channel’s creation time in UTC.

Type:: datetime.datetime

overwrites_for(obj)[source]¶

Returns the channel-specific overwrites for a member or a role.

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

property overwrites[source]¶

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[Role | Member, PermissionOverwrite]

property category[source]¶

The category this channel belongs to.

If there is no category then this is None.

Type:: CategoryChannel | None

property permissions_synced[source]¶

Whether or not 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.

Type:: bool

property flags[source]¶

The channel flags for this channel.

New in version 2.6.

Type:: ChannelFlags

property jump_url[source]¶: A URL that can be used to jump to this channel.

New in version 2.4.

Note

This exists for all guild channels but may not be usable by the client for all guild channel types.

permissions_for(obj, /, *, ignore_timeout=...)[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
Timeouts

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

Note

If the channel originated from an Interaction and the guild attribute is unavailable, such as with user-installed applications in guilds, this method will not work due to an API limitation. Consider using Interaction.permissions or app_permissions instead.

Changed in version 2.0: The object passed in can now be a role object.

Parameters:

obj (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.
ignore_timeout (bool) –
Whether or not to ignore the user’s timeout. Defaults to False.

New in version 2.4.

Note

This only applies to Member objects.

Changed in version 2.6: The default was changed to False.

Raises:

TypeError – ignore_timeout is only supported for Member objects.

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 Permissions.manage_channels permission to do this.

Parameters:

reason (str | None) – 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.

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 Permissions.manage_roles permission to do this.

Note

This method replaces the old overwrites with the ones given.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Examples

Setting allow and deny:

await message.channel.set_permissions(message.author, view_channel=True,
                                                      send_messages=False)

Deleting overwrites

await channel.set_permissions(member, overwrite=None)

Using PermissionOverwrite

overwrite = disnake.PermissionOverwrite()
overwrite.send_messages = False
overwrite.view_channel = True
await channel.set_permissions(member, overwrite=overwrite)

Parameters:

target (Member | Role) – The member or role to overwrite permissions for.
overwrite (PermissionOverwrite | None) – 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 (str | None) – 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.
TypeError – overwrite is invalid, the target type was not Role or Member, both keyword arguments and overwrite were provided, or invalid permissions were provided as keyword arguments.

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 Permissions.manage_channels permission to do this.

New in version 1.1.

Parameters:

name (str | None) – The name of the new channel. If not provided, defaults to this channel name.
reason (str | None) – The reason for cloning this channel. Shows up on the audit log.

Raises:

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.

Returns:

The channel that was created.

Return type:

abc.GuildChannel

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

Changed in version 2.6: Raises TypeError or ValueError instead of InvalidArgument.

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 (abc.Snowflake) – The channel that should be before our current channel. This is mutually exclusive with beginning, end, and after.
after (abc.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 (abc.Snowflake | None) – 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 | None) – The reason for moving this channel. Shows up on the audit log.

Raises:

Forbidden – You do not have permissions to move the channel.
HTTPException – Moving the channel failed.
TypeError – A bad mix of arguments were passed.
ValueError – An invalid position was given.

await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, target_type=None, target_user=None, target_application=None, guild_scheduled_event=None)[source]¶

This function is a coroutine.

Creates an instant invite from a text or voice channel.

You must have Permissions.create_instant_invite permission to do this.

Parameters:

max_age (int) – How long the invite should last in seconds. If set to 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) – Whether the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to False.
unique (bool) – Whether a unique invite URL should be created. Defaults to True. If this is set to False then it will return a previously created invite.
target_type (InviteTarget | None) –
The type of target for the voice channel invite, if any.

New in version 2.0.
target_user (User | None) –
The user whose stream to display for this invite, required if target_type is InviteTarget.stream. The user must be streaming in the channel.

New in version 2.0.
target_application (Snowflake | None) –
The ID of the embedded application for the invite, required if target_type is InviteTarget.embedded_application.

New in version 2.0.

Changed in version 2.9: PartyType is deprecated, and Snowflake should be used instead.
guild_scheduled_event (GuildScheduledEvent | None) –
The guild scheduled event to include with the invite.

New in version 2.3.
reason (str | None) – The reason for creating this invite. Shows up on the audit log.

Raises:

HTTPException – Invite creation failed.
NotFound – The channel that was passed is a category or an invalid channel.

Returns:

The newly created invite.

Return type:

Invite

await invites()[source]¶

This function is a coroutine.

Returns a list of all active instant invites from this channel.

You must have Permissions.manage_channels permission to use this.

Raises:

Forbidden – You do not have proper permissions to get the information.
HTTPException – An error occurred while fetching the information.

Returns:

The list of invites that are currently active.

Return type:

list[Invite]

Messageable¶

Methods

asyncfetch_message
defhistory
defpins
asyncsend
asynctrigger_typing
deftyping

class disnake.abc.Messageable[source]¶

An ABC that details the common operations on a model that can send messages.

The following classes 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 Permissions.read_message_history permission to use this.

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.

Parameters:

limit (int | None) – 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 (abc.Snowflake | datetime.datetime | None) – 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 (abc.Snowflake | datetime.datetime | None) – 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 (abc.Snowflake | datetime.datetime | None) – 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 (bool | None) – If set to True, return messages in oldest->newest order. Defaults to True if after is specified, otherwise False.

Raises:

Forbidden – You do not have permissions to get channel message history.
HTTPException – The request to get message history failed.

Yields:

Message – The message with the message data parsed.

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.

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=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, suppress_embeds=None, flags=None, allowed_mentions=None, reference=None, mention_author=None, view=None, components=None, poll=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).

At least one of content, embed/embeds, file/files, stickers, components, poll or view 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.

Changed in version 2.6: Raises TypeError or ValueError instead of InvalidArgument.

Parameters:

content (str | None) – The content of the message to send.
tts (bool) – Whether the message should be sent using text-to-speech.
embed (Embed) – The rich embed for the content to send. This cannot be mixed with the embeds parameter.
embeds (list[Embed]) –
A list of embeds to send with the content. Must be a maximum of 10. This cannot be mixed with the embed parameter.

New in version 2.0.
file (File) – The file to upload. This cannot be mixed with the files parameter.
files (list[File]) – A list of files to upload. Must be a maximum of 10. This cannot be mixed with the file parameter.
stickers (Sequence[GuildSticker | StandardSticker | StickerItem]) –
A list of stickers to upload. Must be a maximum of 3.

New in version 2.0.
nonce (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.
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 Client.allowed_mentions. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in Client.allowed_mentions. If no object is passed at all then the defaults given by Client.allowed_mentions are used instead.

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

New in version 1.6.

Note

Passing a Message or PartialMessage will only allow replies. To forward a message you must explicitly transform the message to a MessageReference using Message.to_reference() and specify the MessageReferenceType, or use Message.forward().
mention_author (bool | None) –
If set, overrides the AllowedMentions.replied_user attribute of allowed_mentions.

New in version 1.6.
view (ui.View) –
A Discord UI View to add to the message. This cannot be mixed with components.

New in version 2.0.
components (UIComponent | list[UIComponent | list[WrappedComponent]]) –
A list of components to include in the message. This cannot be mixed with view.

New in version 2.4.

Note

Passing v2 components here automatically sets the is_components_v2 flag. Setting this flag cannot be reverted. Note that this also disables the content, embeds, stickers, and poll fields.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This hides all the embeds from the UI if set to True.

New in version 2.5.
flags (MessageFlags) –
The flags to set for this message. Only suppress_embeds, suppress_notifications, and is_components_v2 are supported.

If parameter suppress_embeds is provided, that will override the setting of MessageFlags.suppress_embeds.

New in version 2.9.
poll (Poll) –
The poll to send with the message.

New in version 2.10.

Raises:

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
TypeError – Specified both file and files, or you specified both embed and embeds, or you specified both view and components, or the reference object is not a Message, MessageReference or PartialMessage.
ValueError – The files or embeds list is too large, or you tried to send v2 components together with content, embeds, stickers, or poll.

Returns:

The message that was sent.

Return type:

Message

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.

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.

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.

Returns:

The message asked for.

Return type:

Message

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

Returns an AsyncIterator that enables receiving the destination’s pinned messages.

You must have the Permissions.read_message_history and Permissions.view_channel permissions to use this.

Note

Due to a limitation with the Discord API, the Message objects returned by this method do not contain complete Message.reactions data.

Changed in version 2.11: Now returns an AsyncIterator to support changes in Discord’s API. awaiting the result of this method remains supported, but only returns the last 50 pins and is deprecated in favor of async for msg in channel.pins().

Examples

Usage

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

Flattening to a list

pinned_messages = await channel.pins(limit=100).flatten()
# pinned_messages is now a list of Message...

All parameters are optional.

Parameters:

limit (int | None) – The number of pinned messages to retrieve. If None, retrieves every pinned message in the channel. Note, however, that this would make it a slow operation.
before (abc.Snowflake | datetime.datetime | None) – Retrieve messages pinned 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.

Raises:

HTTPException – Retrieving the pinned messages failed.

Yields:

Message – The pinned message from the parsed message data.

Connectable¶

class disnake.abc.Connectable[source]¶

An ABC that details the common operations on a channel that can connect to a voice server.

The following classes implement this ABC:

Note

This ABC is not decorated with typing.runtime_checkable(), so will fail isinstance()/issubclass() checks.