Miscellaneous¶

This section documents everything that doesn’t fit into any other section, but isn’t big enough to have its own section.

Classes¶

AsyncIterator¶

class disnake.AsyncIterator¶

Represents the “AsyncIterator” concept. Note that no such class exists, it is purely abstract.

async for x in y: Iterates over the contents of the async iterator.

await next()¶

This function is a coroutine.

Advances the iterator by one, if possible. If no more items are found then this raises NoMoreItems.

await get(**attrs)¶

This function is a coroutine.

Similar to utils.get() except run over the async iterator.

Getting the last message by a user named ‘Dave’ or None:

msg = await channel.history().get(author__name='Dave')

await find(predicate)¶

This function is a coroutine.

Similar to utils.find() except run over the async iterator.

Unlike utils.find(), the predicate provided can be a coroutine.

Getting the last audit log with a reason or None:

def predicate(event):
    return event.reason is not None

event = await guild.audit_logs().find(predicate)

Parameters:: predicate – The predicate to use. Could be a coroutine.
Returns:: The first element that returns True for the predicate or None.

await flatten()¶

This function is a coroutine.

Flattens the async iterator into a list with all the elements.

Returns:: A list of every element in the async iterator.
Return type:: list

chunk(max_size)¶

Collects items into chunks of up to a given maximum size. Another AsyncIterator is returned which collects items into lists of a given size. The maximum chunk size must be a positive integer.

New in version 1.6.

Collecting groups of users:

async for leader, *users in reaction.users().chunk(3):
    ...

Warning

The last chunk collected may not be as large as max_size.

Parameters:: max_size – The size of individual chunks.
Return type:: AsyncIterator

map(func)¶

This is similar to the built-in map function. Another AsyncIterator is returned that executes the function on every element it is iterating over. This function can either be a regular function or a coroutine.

Creating a content iterator:

def transform(message):
    return message.content

async for content in channel.history().map(transform):
    message_length = len(content)

Parameters:: func – The function to call on every element. Could be a coroutine.
Return type:: AsyncIterator

filter(predicate)¶

This is similar to the built-in filter function. Another AsyncIterator is returned that filters over the original async iterator. This predicate can be a regular function or a coroutine.

Getting messages by non-bot accounts:

def predicate(message):
    return not message.author.bot

async for elem in channel.history().filter(predicate):
    ...

Parameters:: predicate – The predicate to call on every element. Could be a coroutine.
Return type:: AsyncIterator

Discord Models¶

Asset¶

Attributes

Methods

defis_animated
asyncread
defreplace
asyncsave
asyncto_file
defwith_format
defwith_size
defwith_static_format

class disnake.Asset[source]¶

Represents a CDN asset on Discord.

str(x): Returns the URL of the CDN asset.

len(x): Returns the length of the CDN asset’s URL.

x == y: Checks if the asset is equal to another asset.

x != y: Checks if the asset is not equal to another asset.

hash(x): Returns the hash of the asset.

property url[source]¶

Returns the underlying URL of the asset.

Type:: str

property key[source]¶

Returns the identifying key of the asset.

Type:: str

is_animated()[source]¶

Whether the asset is animated.

Return type:: bool

replace(*, size=..., format=..., static_format=...)[source]¶

Returns a new asset with the passed components replaced.

Changed in version 2.6: Raises ValueError instead of InvalidArgument.

Parameters:

size (int) – The new size of the asset.
format (str) – The new format to change it to. Must be either ‘webp’, ‘jpeg’, ‘jpg’, ‘png’, or ‘gif’ if it’s animated.
static_format (str) – The new format to change it to if the asset isn’t animated. Must be either ‘webp’, ‘jpeg’, ‘jpg’, or ‘png’.

Raises:

ValueError – An invalid size or format was passed.

Returns:

The newly updated asset.

Return type:

Asset

with_size(size, /)[source]¶

Returns a new asset with the specified size.

Changed in version 2.6: Raises ValueError instead of InvalidArgument.

Parameters:: size (int) – The new size of the asset.
Raises:: ValueError – The asset had an invalid size.
Returns:: The newly updated asset.
Return type:: Asset

with_format(format, /)[source]¶

Returns a new asset with the specified format.

Changed in version 2.6: Raises ValueError instead of InvalidArgument.

Parameters:: format (str) – The new format of the asset.
Raises:: ValueError – The asset had an invalid format.
Returns:: The newly updated asset.
Return type:: Asset

with_static_format(format, /)[source]¶

Returns a new asset with the specified static format.

This only changes the format if the underlying asset is not animated. Otherwise, the asset is not changed.

Changed in version 2.6: Raises ValueError instead of InvalidArgument.

Parameters:: format (str) – The new static format of the asset.
Raises:: ValueError – The asset had an invalid format.
Returns:: The newly updated asset.
Return type:: Asset

await read()[source]¶

This function is a coroutine.

Retrieves the content of this asset as a bytes object.

Raises:

DiscordException – There was no internal connection state.
HTTPException – Downloading the asset failed.
NotFound – The asset was deleted.

Returns:

The content of the asset.

Return type:

bytes

await save(fp, *, seek_begin=True)[source]¶

This function is a coroutine.

Saves this asset into a file-like object.

Parameters:

fp (Union[io.BufferedIOBase, os.PathLike]) – The file-like object to save this asset to or the filename to use. If a filename is passed then a file is created with that filename and used instead.
seek_begin (bool) – Whether to seek to the beginning of the file after saving is successfully done.

Raises:

DiscordException – There was no internal connection state.
HTTPException – Downloading the asset failed.
NotFound – The asset was deleted.

Returns:

The number of bytes written.

Return type:

int

await to_file(*, spoiler=False, filename=None, description=None)[source]¶

This function is a coroutine.

Converts the asset into a File suitable for sending via abc.Messageable.send().

New in version 2.5.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Parameters:

spoiler (bool) – Whether the file is a spoiler.
filename (Optional[str]) – The filename to display when uploading to Discord. If this is not given, it defaults to the name of the asset’s URL.
description (Optional[str]) – The file’s description.

Raises:

DiscordException – The asset does not have an associated state.
HTTPException – Downloading the asset failed.
NotFound – The asset was deleted.
TypeError – The asset is a unicode emoji or a sticker with lottie type.

Returns:

The asset as a file suitable for sending.

Return type:

File

Data Classes¶

Object¶

Attributes

created_at
id

class disnake.Object(id)[source]¶

Represents a generic Discord object.

The purpose of this class is to allow you to create ‘miniature’ versions of data classes if you want to pass in just an ID. Most functions that take in a specific data class with an ID can also take in this class as a substitute instead. Note that even though this is the case, not all objects (if any) actually inherit from this class.

There are also some cases where some websocket events are received in strange order and when such events happened you would receive this class rather than the actual data class. These cases are extremely rare.

x == y: Checks if two objects are equal.

x != y: Checks if two objects are not equal.

hash(x): Returns the object’s hash.

id¶

The ID of the object.

Type:: int

property created_at[source]¶

Returns the snowflake’s creation time in UTC.

Type:: datetime.datetime

Colour¶

Attributes

b
g
r
value

Methods

clsColour.blue
clsColour.blurple
clsColour.brand_green
clsColour.brand_red
clsColour.dark_blue
clsColour.dark_embed
clsColour.dark_gold
clsColour.dark_gray
clsColour.dark_green
clsColour.dark_grey
clsColour.dark_magenta
clsColour.dark_orange
clsColour.dark_purple
clsColour.dark_red
clsColour.dark_teal
clsColour.dark_theme
clsColour.darker_gray
clsColour.darker_grey
clsColour.default
clsColour.from_hsv
clsColour.from_rgb
clsColour.fuchsia
clsColour.gold
clsColour.green
clsColour.greyple
clsColour.light_embed
clsColour.light_gray
clsColour.light_grey
clsColour.lighter_gray
clsColour.lighter_grey
clsColour.magenta
clsColour.og_blurple
clsColour.old_blurple
clsColour.orange
clsColour.purple
clsColour.random
clsColour.red
clsColour.teal
clsColour.yellow
defto_rgb

class disnake.Colour(value)[source]¶

Represents a Discord role colour. This class is similar to a (red, green, blue) tuple.

There is an alias for this called Color.

x == y: Checks if two colours are equal.

x != y: Checks if two colours are not equal.

hash(x): Return the colour’s hash.

str(x): Returns the hex format for the colour.

int(x): Returns the raw colour value.

value¶

The raw integer colour value.

Type:: int

property r[source]¶

Returns the red component of the colour.

Type:: int

property g[source]¶

Returns the green component of the colour.

Type:: int

property b[source]¶

Returns the blue component of the colour.

Type:: int

to_rgb()[source]¶: Tuple[int, int, int]: Returns an (r, g, b) tuple representing the colour.

classmethod from_rgb(r, g, b)[source]¶: Constructs a Colour from an RGB tuple.

classmethod from_hsv(h, s, v)[source]¶: Constructs a Colour from an HSV tuple.

classmethod default()[source]¶: A factory method that returns a Colour with a value of 0.

classmethod random(*, seed=None)[source]¶

A factory method that returns a Colour with a random hue.

Note

The random algorithm works by choosing a colour with a random hue but with maxed out saturation and value.

New in version 1.6.

Parameters:

seed (Optional[Union[int, str, float, bytes, bytearray]]) –

The seed to initialize the RNG with. If None is passed the default RNG is used.

New in version 1.7.

classmethod teal()[source]¶: A factory method that returns a Colour with a value of 0x1abc9c.

classmethod dark_teal()[source]¶: A factory method that returns a Colour with a value of 0x11806a.

classmethod brand_green()[source]¶: A factory method that returns a Colour with a value of 0x57F287.

New in version 2.0.

classmethod green()[source]¶: A factory method that returns a Colour with a value of 0x2ecc71.

classmethod dark_green()[source]¶: A factory method that returns a Colour with a value of 0x1f8b4c.

classmethod blue()[source]¶: A factory method that returns a Colour with a value of 0x3498db.

classmethod dark_blue()[source]¶: A factory method that returns a Colour with a value of 0x206694.

classmethod purple()[source]¶: A factory method that returns a Colour with a value of 0x9b59b6.

classmethod dark_purple()[source]¶: A factory method that returns a Colour with a value of 0x71368a.

classmethod magenta()[source]¶: A factory method that returns a Colour with a value of 0xe91e63.

classmethod dark_magenta()[source]¶: A factory method that returns a Colour with a value of 0xad1457.

classmethod gold()[source]¶: A factory method that returns a Colour with a value of 0xf1c40f.

classmethod dark_gold()[source]¶: A factory method that returns a Colour with a value of 0xc27c0e.

classmethod orange()[source]¶: A factory method that returns a Colour with a value of 0xe67e22.

classmethod dark_orange()[source]¶: A factory method that returns a Colour with a value of 0xa84300.

classmethod brand_red()[source]¶: A factory method that returns a Colour with a value of 0xED4245.

New in version 2.0.

classmethod red()[source]¶: A factory method that returns a Colour with a value of 0xe74c3c.

classmethod dark_red()[source]¶: A factory method that returns a Colour with a value of 0x992d22.

classmethod lighter_grey()[source]¶: A factory method that returns a Colour with a value of 0x95a5a6.

classmethod lighter_gray()[source]¶: A factory method that returns a Colour with a value of 0x95a5a6.

classmethod dark_grey()[source]¶: A factory method that returns a Colour with a value of 0x607d8b.

classmethod dark_gray()[source]¶: A factory method that returns a Colour with a value of 0x607d8b.

classmethod light_grey()[source]¶: A factory method that returns a Colour with a value of 0x979c9f.

classmethod light_gray()[source]¶: A factory method that returns a Colour with a value of 0x979c9f.

classmethod darker_grey()[source]¶: A factory method that returns a Colour with a value of 0x546e7a.

classmethod darker_gray()[source]¶: A factory method that returns a Colour with a value of 0x546e7a.

classmethod og_blurple()[source]¶: A factory method that returns a Colour with a value of 0x7289da.

classmethod old_blurple()[source]¶: A factory method that returns a Colour with a value of 0x7289da.

classmethod blurple()[source]¶: A factory method that returns a Colour with a value of 0x5865F2.

classmethod greyple()[source]¶: A factory method that returns a Colour with a value of 0x99aab5.

classmethod dark_theme()[source]¶: A factory method that returns a Colour with a value of 0x313338. This will appear transparent on Discord’s dark theme.

New in version 1.5.

classmethod fuchsia()[source]¶: A factory method that returns a Colour with a value of 0xEB459E.

New in version 2.0.

classmethod yellow()[source]¶: A factory method that returns a Colour with a value of 0xFEE75C.

New in version 2.0.

classmethod light_embed()[source]¶: A factory method that returns a Colour with a value of 0xF2F3F5. This matches the embed background colour on Discord’s light theme.

New in version 2.10.

classmethod dark_embed()[source]¶: A factory method that returns a Colour with a value of 0x2B2D31. This matches the embed background colour on Discord’s dark theme.

New in version 2.10.

Module Attributes¶

Version Info¶

There are two main ways to query version information about the library. For guarantees, check Version Guarantees.

disnake.version_info¶

A named tuple that is similar to sys.version_info.

Just like sys.version_info the valid values for releaselevel are ‘alpha’, ‘beta’, ‘candidate’ and ‘final’.

disnake.__version__¶: A string representation of the version. e.g. '1.0.0rc1'. This is based off of PEP 440.