Prefix Commands¶
This section documents everything related to prefix commands.
Classes¶
Command¶
- async__call__
- defadd_check
- @after_invoke
- @before_invoke
- asynccan_run
- defcopy
- @error
- defget_cooldown_retry_after
- defhas_error_handler
- defis_on_cooldown
- defremove_check
- defreset_cooldown
- defupdate
- 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.
- enabled¶
Whether the command is currently enabled. If the command is invoked while it is disabled, then
DisabledCommand
is raised to theon_command_error()
event. Defaults toTrue
.- Type:
- parent¶
The parent group that this command belongs to.
None
if there isn’t one.- Type:
Optional[
Group
]
- 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 fromCommandError
should be used. Note that if the checks fail thenCheckFailure
exception is raised to theon_command_error()
event.
If
True
, the default help command does not show this in the help output.- Type:
- 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 handlesMissingRequiredArgument
and default values in a regular matter rather than passing the rest completely raw. IfTrue
then the keyword-only argument will pass in the rest of the arguments in a completely raw matter. Defaults toFalse
.- Type:
- require_var_positional¶
If
True
and a variadic positional argument is specified, requires the user to specify at least one argument. Defaults toFalse
.New in version 1.5.
- Type:
- 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 expectinga
andb
). Otherwiseon_command_error()
and local error handlers are called withTooManyArguments
. Defaults toTrue
.- Type:
- cooldown_after_parsing¶
If
True
, cooldown processing is done after argument parsing, which calls converters. IfFalse
then cooldown processing is done first and then the converters are called second. Defaults toFalse
.- Type:
- 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:
- @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.
- @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.
- @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, theon_command_error()
is still invoked afterwards as the catch-all.
- 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 theCommand
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:
- 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 beone two
.- Type:
- 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 isa
.- 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 beone two three
.- Type:
- 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.
- has_error_handler()[source]¶
Whether the command has an error handler registered.
New in version 1.7.
- Return type:
- 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 thehelp
attribute is used instead.- Type:
- 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:
Group¶
- defadd_check
- defadd_command
- @after_invoke
- @before_invoke
- asynccan_run
- @command
- defcopy
- @error
- defget_command
- defget_cooldown_retry_after
- @group
- defhas_error_handler
- defis_on_cooldown
- defremove_check
- defremove_command
- defreset_cooldown
- defupdate
- defwalk_commands
- 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 inCommand
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 toFalse
.- Type:
- case_insensitive¶
Indicates if the group’s commands should be case insensitive. Defaults to
False
.- Type:
- @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.
- @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.
- @command(*args, **kwargs)[source]¶
A shortcut decorator that invokes
command()
and adds it to the internal command list viaadd_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, theon_command_error()
is still invoked afterwards as the catch-all.
- @group(*args, **kwargs)[source]¶
A shortcut decorator that invokes
group()
and adds it to the internal command list viaadd_command()
.- Returns:
A decorator that converts the provided method into a Group, adds it to the bot, then returns it.
- Return type:
Callable[…,
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()
orgroup()
shortcut decorators are used instead.Changed in version 1.4: Raise
CommandRegistrationError
instead of genericClientException
- Parameters:
command (
Command
) – The command to add.- Raises:
CommandRegistrationError – If the command or its alias is already registered by different command.
TypeError – If the command passed is not a subclass of
Command
.
- 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:
- property clean_params[source]¶
Dict[
str
,inspect.Parameter
]: Retrieves the parameter dictionary without the context or self parameters.Useful for inspecting signature.
- 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 beone two
.- Type:
- 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 subcommandbar
of the group commandfoo
. If a subcommand is not found thenNone
is returned just as usual.
- get_cooldown_retry_after(ctx)[source]¶
Retrieves the amount of seconds before this command can be tried again.
New in version 1.4.
- has_error_handler()[source]¶
Whether the command has an error handler registered.
New in version 1.7.
- Return type:
- 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 beone two three
.- Type:
- 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.
- 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 isa
.- 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 thehelp
attribute is used instead.- Type:
GroupMixin¶
- defadd_command
- @command
- defget_command
- @group
- defremove_command
- defwalk_commands
- 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.- @command(*args, **kwargs)[source]¶
A shortcut decorator that invokes
command()
and adds it to the internal command list viaadd_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 viaadd_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()
orgroup()
shortcut decorators are used instead.Changed in version 1.4: Raise
CommandRegistrationError
instead of genericClientException
- Parameters:
command (
Command
) – The command to add.- Raises:
CommandRegistrationError – If the command or its alias is already registered by different command.
TypeError – If the command passed is not a subclass of
Command
.
- remove_command(name)[source]¶
Remove a
Command
from the internal list of commands.This could also be used as a way to remove aliases.
- 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
Functions¶
- @disnake.ext.commands.command(name=..., cls=..., **attrs)[source]¶
A decorator that transforms a function into a
Command
or if called withgroup()
,Group
.By default the
help
attribute is received automatically from the docstring of the function and is cleaned up with the use ofinspect.cleandoc
. If the docstring isbytes
, then it is decoded intostr
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:
- 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 thecls
parameter is set toGroup
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