Prefix Commands

This section documents everything related to prefix commands.

Classes

Command

Attributes
Methods
class disnake.ext.commands.Command(*args, **kwargs)[source]

A class that implements the protocol for a bot text command.

These are not created manually, instead they are created via the decorator or functional interface.

name

The name of the command.

Type:

str

callback[source]

The coroutine that is executed when the command is called.

Type:

coroutine

help

The long help text for the command.

Type:

Optional[str]

brief

The short help text for the command.

Type:

Optional[str]

usage

A replacement for arguments in the default help text.

Type:

Optional[str]

aliases

The list of aliases the command can be invoked under.

Type:

Union[List[str], Tuple[str]]

enabled

Whether the command is currently enabled. If the command is invoked while it is disabled, then DisabledCommand is raised to the on_command_error() event. Defaults to True.

Type:

bool

parent

The parent group that this command belongs to. None if there isn’t one.

Type:

Optional[Group]

cog

The cog that this command belongs to. None if there isn’t one.

Type:

Optional[Cog]

checks

A list of predicates that verifies if the command could be executed with the given Context as the sole parameter. If an exception is necessary to be thrown to signal failure, then one inherited from CommandError should be used. Note that if the checks fail then CheckFailure exception is raised to the on_command_error() event.

Type:

List[Callable[[Context], bool]]

description

The message prefixed into the default help command.

Type:

str

hidden

If True, the default help command does not show this in the help output.

Type:

bool

rest_is_raw

If False and a keyword-only argument is provided then the keyword only argument is stripped and handled as if it was a regular argument that handles MissingRequiredArgument and default values in a regular matter rather than passing the rest completely raw. If True then the keyword-only argument will pass in the rest of the arguments in a completely raw matter. Defaults to False.

Type:

bool

invoked_subcommand

The subcommand that was invoked, if any.

Type:

Optional[Command]

require_var_positional

If True and a variadic positional argument is specified, requires the user to specify at least one argument. Defaults to False.

New in version 1.5.

Type:

bool

ignore_extra

If True, ignores extraneous strings passed to a command if all its requirements are met (e.g. ?foo a b c when only expecting a and b). Otherwise on_command_error() and local error handlers are called with TooManyArguments. Defaults to True.

Type:

bool

cooldown_after_parsing

If True, cooldown processing is done after argument parsing, which calls converters. If False then cooldown processing is done first and then the converters are called second. Defaults to False.

Type:

bool

extras

A dict of user provided extras to attach to the Command.

Note

This object may be copied by the library.

New in version 2.0.

Type:

dict

@after_invoke[source]

A decorator that registers a coroutine as a post-invoke hook.

A post-invoke hook is called directly after the command is called. This makes it a useful function to clean-up database connections or any type of clean up required.

This post-invoke hook takes a sole parameter, a Context.

See Bot.after_invoke() for more info.

Parameters:

coro (coroutine) – The coroutine to register as the post-invoke hook.

Raises:

TypeError – The coroutine passed is not actually a coroutine.

@before_invoke[source]

A decorator that registers a coroutine as a pre-invoke hook.

A pre-invoke hook is called directly before the command is called. This makes it a useful function to set up database connections or any type of set up required.

This pre-invoke hook takes a sole parameter, a Context.

See Bot.before_invoke() for more info.

Parameters:

coro (coroutine) – The coroutine to register as the pre-invoke hook.

Raises:

TypeError – The coroutine passed is not actually a coroutine.

@error[source]

A decorator that registers a coroutine as a local error handler.

A local error handler is an on_command_error() event limited to a single command. However, the on_command_error() is still invoked afterwards as the catch-all.

Parameters:

coro (coroutine) – The coroutine to register as the local error handler.

Raises:

TypeError – The coroutine passed is not actually a coroutine.

add_check(func)[source]

Adds a check to the command.

This is the non-decorator interface to check().

New in version 1.3.

Parameters:

func – The function that will be used as a check.

remove_check(func)[source]

Removes a check from the command.

This function is idempotent and will not raise an exception if the function is not in the command’s checks.

New in version 1.3.

Parameters:

func – The function to remove from the checks.

update(**kwargs)[source]

Updates Command instance with updated attribute.

This works similarly to the command() decorator in terms of parameters in that they are passed to the Command or subclass constructors, sans the name and callback.

await __call__(context, *args, **kwargs)[source]

This function is a coroutine.

Calls the internal callback that the command holds.

Note

This bypasses all mechanisms – including checks, converters, invoke hooks, cooldowns, etc. You must take care to pass the proper arguments and types to this function.

New in version 1.3.

copy()[source]

Creates a copy of this command.

Returns:

A new instance of this command.

Return type:

Command

property clean_params[source]

Dict[str, inspect.Parameter]: Retrieves the parameter dictionary without the context or self parameters.

Useful for inspecting signature.

property full_parent_name[source]

Retrieves the fully qualified parent command name.

This the base command name required to execute it. For example, in ?one two three the parent name would be one two.

Type:

str

property parents[source]

Retrieves the parents of this command.

If the command has no parents then it returns an empty list.

For example in commands ?a b c test, the parents are [c, b, a].

New in version 1.1.

Type:

List[Group]

property root_parent[source]

Retrieves the root parent of this command.

If the command has no parents then it returns None.

For example in commands ?a b c test, the root parent is a.

Type:

Optional[Group]

property qualified_name[source]

Retrieves the fully qualified command name.

This is the full parent name with the command name as well. For example, in ?one two three the qualified name would be one two three.

Type:

str

is_on_cooldown(ctx)[source]

Checks whether the command is currently on cooldown.

Parameters:

ctx (Context) – The invocation context to use when checking the commands cooldown status.

Returns:

A boolean indicating if the command is on cooldown.

Return type:

bool

reset_cooldown(ctx)[source]

Resets the cooldown on this command.

Parameters:

ctx (Context) – The invocation context to reset the cooldown under.

get_cooldown_retry_after(ctx)[source]

Retrieves the amount of seconds before this command can be tried again.

New in version 1.4.

Parameters:

ctx (Context) – The invocation context to retrieve the cooldown from.

Returns:

The amount of time left on this command’s cooldown in seconds. If this is 0.0 then the command isn’t on cooldown.

Return type:

float

has_error_handler()[source]

Whether the command has an error handler registered.

New in version 1.7.

Return type:

bool

property cog_name[source]

The name of the cog this command belongs to, if any.

Type:

Optional[str]

property short_doc[source]

Gets the “short” documentation of a command.

By default, this is the brief attribute. If that lookup leads to an empty string then the first line of the help attribute is used instead.

Type:

str

property signature[source]

Returns a POSIX-like signature useful for help command output.

Type:

str

await can_run(ctx)[source]

This function is a coroutine.

Checks if the command can be executed by checking all the predicates inside the checks attribute. This also checks whether the command is disabled.

Changed in version 1.3: Checks whether the command is disabled.

Parameters:

ctx (Context) – The ctx of the command currently being invoked.

Raises:

CommandError – Any command error that was raised during a check call will be propagated by this function.

Returns:

Whether the command can be invoked.

Return type:

bool

Group

Attributes
Methods
class disnake.ext.commands.Group(*args, **kwargs)[source]

A class that implements a grouping protocol for commands to be executed as subcommands.

This class is a subclass of Command and thus all options valid in Command are valid in here as well.

invoke_without_command

Indicates if the group callback should begin parsing and invocation only if no subcommand was found. Useful for making it an error handling function to tell the user that no subcommand was found or to have different functionality in case no subcommand was found. If this is False, then the group callback will always be invoked first. This means that the checks and the parsing dictated by its parameters will be executed. Defaults to False.

Type:

bool

case_insensitive

Indicates if the group’s commands should be case insensitive. Defaults to False.

Type:

bool

@after_invoke[source]

A decorator that registers a coroutine as a post-invoke hook.

A post-invoke hook is called directly after the command is called. This makes it a useful function to clean-up database connections or any type of clean up required.

This post-invoke hook takes a sole parameter, a Context.

See Bot.after_invoke() for more info.

Parameters:

coro (coroutine) – The coroutine to register as the post-invoke hook.

Raises:

TypeError – The coroutine passed is not actually a coroutine.

@before_invoke[source]

A decorator that registers a coroutine as a pre-invoke hook.

A pre-invoke hook is called directly before the command is called. This makes it a useful function to set up database connections or any type of set up required.

This pre-invoke hook takes a sole parameter, a Context.

See Bot.before_invoke() for more info.

Parameters:

coro (coroutine) – The coroutine to register as the pre-invoke hook.

Raises:

TypeError – The coroutine passed is not actually a coroutine.

@command(*args, **kwargs)[source]

A shortcut decorator that invokes command() and adds it to the internal command list via add_command().

Returns:

A decorator that converts the provided method into a Command, adds it to the bot, then returns it.

Return type:

Callable[…, Command]

@error[source]

A decorator that registers a coroutine as a local error handler.

A local error handler is an on_command_error() event limited to a single command. However, the on_command_error() is still invoked afterwards as the catch-all.

Parameters:

coro (coroutine) – The coroutine to register as the local error handler.

Raises:

TypeError – The coroutine passed is not actually a coroutine.

@group(*args, **kwargs)[source]

A shortcut decorator that invokes group() and adds it to the internal command list via add_command().

Returns:

A decorator that converts the provided method into a Group, adds it to the bot, then returns it.

Return type:

Callable[…, Group]

copy()[source]

Creates a copy of this Group.

Returns:

A new instance of this group.

Return type:

Group

add_check(func)[source]

Adds a check to the command.

This is the non-decorator interface to check().

New in version 1.3.

Parameters:

func – The function that will be used as a check.

add_command(command)[source]

Adds a Command into the internal list of commands.

This is usually not called, instead the command() or group() shortcut decorators are used instead.

Changed in version 1.4: Raise CommandRegistrationError instead of generic ClientException

Parameters:

command (Command) – The command to add.

Raises:
await can_run(ctx)[source]

This function is a coroutine.

Checks if the command can be executed by checking all the predicates inside the checks attribute. This also checks whether the command is disabled.

Changed in version 1.3: Checks whether the command is disabled.

Parameters:

ctx (Context) – The ctx of the command currently being invoked.

Raises:

CommandError – Any command error that was raised during a check call will be propagated by this function.

Returns:

Whether the command can be invoked.

Return type:

bool

property clean_params[source]

Dict[str, inspect.Parameter]: Retrieves the parameter dictionary without the context or self parameters.

Useful for inspecting signature.

property cog_name[source]

The name of the cog this command belongs to, if any.

Type:

Optional[str]

property commands[source]

A unique set of commands without aliases that are registered.

Type:

Set[Command]

property full_parent_name[source]

Retrieves the fully qualified parent command name.

This the base command name required to execute it. For example, in ?one two three the parent name would be one two.

Type:

str

get_command(name)[source]

Get a Command from the internal list of commands.

This could also be used as a way to get aliases.

The name could be fully qualified (e.g. 'foo bar') will get the subcommand bar of the group command foo. If a subcommand is not found then None is returned just as usual.

Parameters:

name (str) – The name of the command to get.

Returns:

The command that was requested. If not found, returns None.

Return type:

Optional[Command]

get_cooldown_retry_after(ctx)[source]

Retrieves the amount of seconds before this command can be tried again.

New in version 1.4.

Parameters:

ctx (Context) – The invocation context to retrieve the cooldown from.

Returns:

The amount of time left on this command’s cooldown in seconds. If this is 0.0 then the command isn’t on cooldown.

Return type:

float

has_error_handler()[source]

Whether the command has an error handler registered.

New in version 1.7.

Return type:

bool

is_on_cooldown(ctx)[source]

Checks whether the command is currently on cooldown.

Parameters:

ctx (Context) – The invocation context to use when checking the commands cooldown status.

Returns:

A boolean indicating if the command is on cooldown.

Return type:

bool

property parents[source]

Retrieves the parents of this command.

If the command has no parents then it returns an empty list.

For example in commands ?a b c test, the parents are [c, b, a].

New in version 1.1.

Type:

List[Group]

property qualified_name[source]

Retrieves the fully qualified command name.

This is the full parent name with the command name as well. For example, in ?one two three the qualified name would be one two three.

Type:

str

remove_check(func)[source]

Removes a check from the command.

This function is idempotent and will not raise an exception if the function is not in the command’s checks.

New in version 1.3.

Parameters:

func – The function to remove from the checks.

remove_command(name)[source]

Remove a Command from the internal list of commands.

This could also be used as a way to remove aliases.

Parameters:

name (str) – The name of the command to remove.

Returns:

The command that was removed. If the name is not valid then None is returned instead.

Return type:

Optional[Command]

reset_cooldown(ctx)[source]

Resets the cooldown on this command.

Parameters:

ctx (Context) – The invocation context to reset the cooldown under.

property root_parent[source]

Retrieves the root parent of this command.

If the command has no parents then it returns None.

For example in commands ?a b c test, the root parent is a.

Type:

Optional[Group]

property short_doc[source]

Gets the “short” documentation of a command.

By default, this is the brief attribute. If that lookup leads to an empty string then the first line of the help attribute is used instead.

Type:

str

property signature[source]

Returns a POSIX-like signature useful for help command output.

Type:

str

update(**kwargs)[source]

Updates Command instance with updated attribute.

This works similarly to the command() decorator in terms of parameters in that they are passed to the Command or subclass constructors, sans the name and callback.

for ... in walk_commands()[source]

An iterator that recursively walks through all commands and subcommands.

Changed in version 1.4: Duplicates due to aliases are no longer returned

Yields:

Union[Command, Group] – A command or group from the internal list of commands.

GroupMixin

Attributes
Methods
class disnake.ext.commands.GroupMixin(*args, case_insensitive=False, **kwargs)[source]

A mixin that implements common functionality for classes that behave similar to Group and are allowed to register commands.

all_commands

A mapping of command name to Command objects.

Type:

dict

case_insensitive

Whether the commands should be case insensitive. Defaults to False.

Type:

bool

@command(*args, **kwargs)[source]

A shortcut decorator that invokes command() and adds it to the internal command list via add_command().

Returns:

A decorator that converts the provided method into a Command, adds it to the bot, then returns it.

Return type:

Callable[…, Command]

@group(*args, **kwargs)[source]

A shortcut decorator that invokes group() and adds it to the internal command list via add_command().

Returns:

A decorator that converts the provided method into a Group, adds it to the bot, then returns it.

Return type:

Callable[…, Group]

property commands[source]

A unique set of commands without aliases that are registered.

Type:

Set[Command]

add_command(command)[source]

Adds a Command into the internal list of commands.

This is usually not called, instead the command() or group() shortcut decorators are used instead.

Changed in version 1.4: Raise CommandRegistrationError instead of generic ClientException

Parameters:

command (Command) – The command to add.

Raises:
remove_command(name)[source]

Remove a Command from the internal list of commands.

This could also be used as a way to remove aliases.

Parameters:

name (str) – The name of the command to remove.

Returns:

The command that was removed. If the name is not valid then None is returned instead.

Return type:

Optional[Command]

for ... in walk_commands()[source]

An iterator that recursively walks through all commands and subcommands.

Changed in version 1.4: Duplicates due to aliases are no longer returned

Yields:

Union[Command, Group] – A command or group from the internal list of commands.

get_command(name)[source]

Get a Command from the internal list of commands.

This could also be used as a way to get aliases.

The name could be fully qualified (e.g. 'foo bar') will get the subcommand bar of the group command foo. If a subcommand is not found then None is returned just as usual.

Parameters:

name (str) – The name of the command to get.

Returns:

The command that was requested. If not found, returns None.

Return type:

Optional[Command]

Functions

@disnake.ext.commands.command(name=..., cls=..., **attrs)[source]

A decorator that transforms a function into a Command or if called with group(), Group.

By default the help attribute is received automatically from the docstring of the function and is cleaned up with the use of inspect.cleandoc. If the docstring is bytes, then it is decoded into str using utf-8 encoding.

All checks added using the check() & co. decorators are added into the function. There is no way to supply your own checks through this decorator.

Parameters:

  • name (str) – The name to create the command with. By default this uses the function name unchanged.

  • cls – The class to construct with. By default this is Command. You usually do not change this.

  • attrs – Keyword arguments to pass into the construction of the class denoted by cls.

Raises:

TypeError – If the function is not a coroutine or is already a command.

@disnake.ext.commands.group(name=..., cls=..., **attrs)[source]

A decorator that transforms a function into a Group.

This is similar to the command() decorator but the cls parameter is set to Group by default.

Changed in version 1.1: The cls parameter can now be passed.

disnake.ext.commands.when_mentioned(bot, msg)[source]

A callable that implements a command prefix equivalent to being mentioned.

These are meant to be passed into the Bot.command_prefix attribute.

disnake.ext.commands.when_mentioned_or(*prefixes)[source]

A callable that implements when mentioned or other prefixes provided.

These are meant to be passed into the Bot.command_prefix attribute.

Example

bot = commands.Bot(command_prefix=commands.when_mentioned_or('!'))

Note

This callable returns another callable, so if this is done inside a custom callable, you must call the returned callable, for example:

async def get_prefix(bot, message):
    extras = await prefixes_for(message.guild) # returns a list
    return commands.when_mentioned_or(*extras)(bot, message)

See also

when_mentioned()

Events