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
orApplicationCommandInteraction
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.- 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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
Lookup by ID.
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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
Lookup by ID
Lookup by mention
Lookup by username#discrim
Lookup by username#0
Lookup by nickname
Lookup by global name
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 genericBadArgument
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
tonick > 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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
Lookup by ID
Lookup by mention
Lookup by username#discrim
Lookup by username#0
Lookup by global name
Lookup by username
Changed in version 1.5: Raise
UserNotFound
instead of genericBadArgument
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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
Lookup by “{channel ID}-{message ID}” (retrieved by shift-clicking on “Copy ID”)
Lookup by message ID (the message must be in the context channel)
Lookup by message URL
Changed in version 1.5: Raise
ChannelNotFound
,MessageNotFound
orChannelNotReadable
instead of genericBadArgument
- 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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
By “{channel ID}-{message ID}” (retrieved by shift-clicking on “Copy ID”)
By message ID (The message is assumed to be in the context channel.)
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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
Lookup by ID.
Lookup by mention.
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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
Lookup by ID.
Lookup by mention.
Lookup by name
Changed in version 1.5: Raise
ChannelNotFound
instead of genericBadArgument
- 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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
Lookup by ID.
Lookup by mention.
Lookup by name
Changed in version 1.5: Raise
ChannelNotFound
instead of genericBadArgument
- 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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
Lookup by ID.
Lookup by mention.
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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
Lookup by ID.
Lookup by mention.
Lookup by name
Changed in version 1.5: Raise
ChannelNotFound
instead of genericBadArgument
- 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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
Lookup by ID.
Lookup by mention.
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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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]¶
Coverts to a
Thread
.All lookups are via the local guild.
The lookup strategy is as follows (in order):
Lookup by ID.
Lookup by mention.
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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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
inColour
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 genericBadArgument
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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
Lookup by ID.
Lookup by mention.
Lookup by name
Changed in version 1.5: Raise
RoleNotFound
instead of genericBadArgument
- 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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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 genericBadArgument
- 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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
Lookup by ID.
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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
Lookup by ID.
Lookup by extracting ID from the emoji.
Lookup by name
Changed in version 1.5: Raise
EmojiNotFound
instead of genericBadArgument
- 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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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 genericBadArgument
- 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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
Lookup by ID
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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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):
Lookup by ID (in current guild)
Lookup as event URL
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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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
.- use_nicknames¶
Whether to use
nicknames
andglobal names
when transforming mentions.- Type:
- remove_markdown¶
Whether to also remove special markdown characters. This option is not supported with
escape_markdown
New in version 1.7.
- Type:
- 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:
ctx (Union[
Context
,ApplicationCommandInteraction
]) – The invocation context that the argument is being used in.argument (
str
) – The argument that is being converted.
- 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 passnumbers
with[1, 2, 3, 4, 5, 6]
andreason
withhello
.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. IfTrue
then flags are parsed in a case insensitive manner. Defaults toFalse
.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:
FlagError – A flag related parsing error.
CommandError – A command related error.
- Returns:
The flag converter instance with all flags parsed.
- Return type:
- 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.- 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:
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.