Converters

This section documents converters - special classes that aid in converting various types to Discord Models.

Classes

class disnake.ext.commands.Converter(*args, **kwargs)[source]

The base class of custom converters that require the Context or ApplicationCommandInteraction to be passed to be useful.

This allows you to implement converters that function similar to the special cased disnake classes.

Classes that derive from this should override the convert() method to do its conversion logic. This method must be a coroutine function.

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.ObjectConverter(*args, **kwargs)[source]

Converts to a Object.

The argument must follow the valid ID or mention formats (e.g. <@80088516616269824>).

New in version 2.0.

The lookup strategy is as follows (in order):

  1. Lookup by ID.

  2. Lookup by member, role, or channel mention.

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.MemberConverter(*args, **kwargs)[source]

Converts to a Member.

All lookups are via the local guild. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

  1. Lookup by ID

  2. Lookup by mention

  3. Lookup by username#discrim

  4. Lookup by username#0

  5. Lookup by nickname

  6. Lookup by global name

  7. Lookup by username

The name resolution order matches the one used by Guild.get_member_named().

Changed in version 1.5: Raise MemberNotFound instead of generic BadArgument

Changed in version 1.5.1: This converter now lazily fetches members from the gateway and HTTP APIs, optionally caching the result if MemberCacheFlags.joined is enabled.

Changed in version 2.9: Name resolution order changed from username > nick to nick > global_name > username to account for the username migration.

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.UserConverter(*args, **kwargs)[source]

Converts to a User.

All lookups are via the global user cache.

The lookup strategy is as follows (in order):

  1. Lookup by ID

  2. Lookup by mention

  3. Lookup by username#discrim

  4. Lookup by username#0

  5. Lookup by global name

  6. Lookup by username

Changed in version 1.5: Raise UserNotFound instead of generic BadArgument

Changed in version 1.6: This converter now lazily fetches users from the HTTP APIs if an ID is passed and it’s not available in cache.

Changed in version 2.9: Now takes global_name into account. No longer automatically removes "@" prefix from arguments.

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.MessageConverter(*args, **kwargs)[source]

Converts to a Message.

New in version 1.1.

The lookup strategy is as follows (in order):

  1. Lookup by “{channel ID}-{message ID}” (retrieved by shift-clicking on “Copy ID”)

  2. Lookup by message ID (the message must be in the context channel)

  3. Lookup by message URL

Changed in version 1.5: Raise ChannelNotFound, MessageNotFound or ChannelNotReadable instead of generic BadArgument

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.PartialMessageConverter(*args, **kwargs)[source]

Converts to a PartialMessage.

New in version 1.7.

The creation strategy is as follows (in order):

  1. By “{channel ID}-{message ID}” (retrieved by shift-clicking on “Copy ID”)

  2. By message ID (The message is assumed to be in the context channel.)

  3. By message URL

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.GuildChannelConverter(*args, **kwargs)[source]

Converts to a abc.GuildChannel.

All lookups are via the local guild. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

  1. Lookup by ID.

  2. Lookup by mention.

  3. Lookup by name.

New in version 2.0.

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.TextChannelConverter(*args, **kwargs)[source]

Converts to a TextChannel.

All lookups are via the local guild. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

  1. Lookup by ID.

  2. Lookup by mention.

  3. Lookup by name

Changed in version 1.5: Raise ChannelNotFound instead of generic BadArgument

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.VoiceChannelConverter(*args, **kwargs)[source]

Converts to a VoiceChannel.

All lookups are via the local guild. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

  1. Lookup by ID.

  2. Lookup by mention.

  3. Lookup by name

Changed in version 1.5: Raise ChannelNotFound instead of generic BadArgument

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.StageChannelConverter(*args, **kwargs)[source]

Converts to a StageChannel.

New in version 1.7.

All lookups are via the local guild. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

  1. Lookup by ID.

  2. Lookup by mention.

  3. Lookup by name

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.CategoryChannelConverter(*args, **kwargs)[source]

Converts to a CategoryChannel.

All lookups are via the local guild. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

  1. Lookup by ID.

  2. Lookup by mention.

  3. Lookup by name

Changed in version 1.5: Raise ChannelNotFound instead of generic BadArgument

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.ForumChannelConverter(*args, **kwargs)[source]

Converts to a ForumChannel.

New in version 2.5.

All lookups are via the local guild. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

  1. Lookup by ID.

  2. Lookup by mention.

  3. Lookup by name

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.MediaChannelConverter(*args, **kwargs)[source]

Converts to a MediaChannel.

New in version 2.10.

All lookups are via the local guild. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

  1. Lookup by ID.

  2. Lookup by mention.

  3. Lookup by name

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.ThreadConverter(*args, **kwargs)[source]

Converts to a Thread.

All lookups are via the local guild.

The lookup strategy is as follows (in order):

  1. Lookup by ID.

  2. Lookup by mention.

  3. Lookup by name.

New in version 2.0.

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.ColourConverter(*args, **kwargs)[source]

Converts to a Colour.

Changed in version 1.5: Add an alias named ColorConverter

The following formats are accepted:

  • 0x<hex>

  • #<hex>

  • 0x#<hex>

  • rgb(<number>, <number>, <number>)

  • Any of the classmethod in Colour

    • The _ in the name can be optionally replaced with spaces.

Like CSS, <number> can be either 0-255 or 0-100% and <hex> can be either a 6 digit hex number or a 3 digit hex shortcut (e.g. #fff).

Changed in version 1.5: Raise BadColourArgument instead of generic BadArgument

Changed in version 1.7: Added support for rgb function and 3-digit hex shortcuts

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.RoleConverter(*args, **kwargs)[source]

Converts to a Role.

All lookups are via the local guild. If in a DM context, the converter raises NoPrivateMessage exception.

The lookup strategy is as follows (in order):

  1. Lookup by ID.

  2. Lookup by mention.

  3. Lookup by name

Changed in version 1.5: Raise RoleNotFound instead of generic BadArgument

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.GameConverter(*args, **kwargs)[source]

Converts to Game.

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.InviteConverter(*args, **kwargs)[source]

Converts to a Invite.

This is done via an HTTP request using Bot.fetch_invite().

Changed in version 1.5: Raise BadInviteArgument instead of generic BadArgument

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.GuildConverter(*args, **kwargs)[source]

Converts to a Guild.

The lookup strategy is as follows (in order):

  1. Lookup by ID.

  2. Lookup by name. (There is no disambiguation for Guilds with multiple matching names).

New in version 1.7.

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.EmojiConverter(*args, **kwargs)[source]

Converts to a Emoji.

All lookups are done for the local guild first, if available. If that lookup fails, then it checks the client’s global cache.

The lookup strategy is as follows (in order):

  1. Lookup by ID.

  2. Lookup by extracting ID from the emoji.

  3. Lookup by name

Changed in version 1.5: Raise EmojiNotFound instead of generic BadArgument

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.PartialEmojiConverter(*args, **kwargs)[source]

Converts to a PartialEmoji.

This is done by extracting the animated flag, name and ID from the emoji.

Changed in version 1.5: Raise PartialEmojiConversionFailure instead of generic BadArgument

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.GuildStickerConverter(*args, **kwargs)[source]

Converts to a GuildSticker.

All lookups are done for the local guild first, if available. If that lookup fails, then it checks the client’s global cache.

The lookup strategy is as follows (in order):

  1. Lookup by ID

  2. Lookup by name

New in version 2.0.

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.GuildSoundboardSoundConverter(*args, **kwargs)[source]

Converts to a GuildSoundboardSound.

All lookups are done for the local guild first, if available. If that lookup fails, then it checks the client’s global cache.

The lookup strategy is as follows (in order):

  1. Lookup by ID

  2. Lookup by name

New in version 2.10.

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.PermissionsConverter(*args, **kwargs)[source]

Converts to a Permissions.

Accepts an integer or a string of space-separated permission names (or just a single one) as input.

New in version 2.3.

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.GuildScheduledEventConverter(*args, **kwargs)[source]

Converts to a GuildScheduledEvent.

The lookup strategy is as follows (in order):

  1. Lookup by ID (in current guild)

  2. Lookup as event URL

  3. Lookup by name (in current guild; there is no disambiguation for scheduled events with multiple matching names)

New in version 2.5.

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.clean_content(*, fix_channel_mentions=False, use_nicknames=True, escape_markdown=False, remove_markdown=False)[source]

Converts the argument to mention scrubbed version of said content.

This behaves similarly to clean_content.

fix_channel_mentions

Whether to clean channel mentions.

Type:

bool

use_nicknames

Whether to use nicknames and global names when transforming mentions.

Type:

bool

escape_markdown

Whether to also escape special markdown characters.

Type:

bool

remove_markdown

Whether to also remove special markdown characters. This option is not supported with escape_markdown

New in version 1.7.

Type:

bool

await convert(ctx, argument)[source]

This function is a coroutine.

The method to override to do conversion logic.

If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters:
Raises:

  • CommandError – A generic exception occurred when converting the argument.

  • BadArgument – The converter failed to convert the argument.

class disnake.ext.commands.Greedy[source]

A special converter that greedily consumes arguments until it can’t. As a consequence of this behaviour, most input errors are silently discarded, since it is used as an indicator of when to stop parsing.

When a parser error is met the greedy converter stops converting, undoes the internal string parsing routine, and continues parsing regularly.

For example, in the following code:

@commands.command()
async def test(ctx, numbers: Greedy[int], reason: str):
    await ctx.send("numbers: {0}, reason: {1}".format(numbers, reason))

An invocation of [p]test 1 2 3 4 5 6 hello would pass numbers with [1, 2, 3, 4, 5, 6] and reason with hello.

For more information, check Special Converters.

class disnake.ext.commands.FlagConverter[source]

A converter that allows for a user-friendly flag syntax.

The flags are defined using PEP 526 type annotations similar to the dataclasses Python module. For more information on how this converter works, check the appropriate documentation.

iter(x)

Returns an iterator of (flag_name, flag_value) pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.

New in version 2.0.

Parameters:

  • case_insensitive (bool) – A class parameter to toggle case insensitivity of the flag parsing. If True then flags are parsed in a case insensitive manner. Defaults to False.

  • prefix (str) – The prefix that all flags must be prefixed with. By default there is no prefix.

  • delimiter (str) – The delimiter that separates a flag’s argument from the flag’s name. By default this is :.

classmethod get_flags()[source]

dict[str, Flag]: A mapping of flag name to flag object this converter has.

classmethod await convert(ctx, argument)[source]

This function is a coroutine.

The method that actually converters an argument to the flag mapping.

Parameters:

  • cls (type[FlagConverter]) – The flag converter class.

  • ctx (Context) – The invocation context.

  • argument (str) – The argument to convert from.

Raises:
Returns:

The flag converter instance with all flags parsed.

Return type:

FlagConverter

class disnake.ext.commands.Flag[source]

Represents a flag parameter for FlagConverter.

The flag() function helps create these flag objects, but it is not necessary to do so. These cannot be constructed manually.

name

The name of the flag.

Type:

str

aliases

The aliases of the flag name.

Type:

list[str]

attribute

The attribute in the class that corresponds to this flag.

Type:

str

default

The default value of the flag, if available.

Type:

Any

annotation

The underlying evaluated annotation of the flag.

Type:

Any

max_args

The maximum number of arguments the flag can accept. A negative value indicates an unlimited amount of arguments.

Type:

int

override

Whether multiple given values overrides the previous value.

Type:

bool

property required[source]

Whether the flag is required.

A required flag has no default value.

Type:

bool

Functions

await disnake.ext.commands.run_converters(ctx, converter, argument, param)[source]

This function is a coroutine.

Runs converters for a given converter, argument, and parameter.

This function does the same work that the library does under the hood.

New in version 2.0.

Parameters:

  • ctx (Context) – The invocation context to run the converters under.

  • converter (Any) – The converter to run, this corresponds to the annotation in the function.

  • argument (str) – The argument to convert to.

  • param (inspect.Parameter) – The parameter being converted. This is mainly for error reporting.

Raises:

CommandError – The converter failed to convert.

Returns:

The resulting conversion.

Return type:

Any

@disnake.ext.commands.converter_method(function)[source]

A decorator to register a method as the converter method.

New in version 2.3.

disnake.ext.commands.flag(*, name=..., aliases=..., default=..., max_args=..., override=...)[source]

Override default functionality and parameters of the underlying FlagConverter class attributes.

Parameters:

  • name (str) – The flag name. If not given, defaults to the attribute name.

  • aliases (list[str]) – Aliases to the flag name. If not given no aliases are set.

  • default (Any) – The default parameter. This could be either a value or a callable that takes Context as its sole parameter. If not given then it defaults to the default value given to the attribute.

  • max_args (int) – The maximum number of arguments the flag can accept. A negative value indicates an unlimited amount of arguments. The default value depends on the annotation given.

  • override (bool) – Whether multiple given values overrides the previous value. The default value depends on the annotation given.