Pwefix Commands

This section documents evewything w-w-wewated to pwefix commands.

Cwasses

Command

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

A c-cwass that impwements the pwotocow fow a bot text command.

These awe nyot cweated manyuawwy, i-i-instead they awe cweated via the decowatow ow functionyaw intewface.

name

The nyame of the command.

Type:

str

callback[source]

The cowoutinye that is executed when the command is cawwed.

Type:

cowoutinye

help

The wong hewp text fow the command.

Type:

Optionyaw[str]

brief

The showt hewp text fow the command.

Type:

Optionyaw[str]

usage

A wepwacement fow awguments in the defauwt hewp text.

Type:

Optionyaw[str]

aliases

The wist of awiases the command c-c-can be invoked undew.

Type:

U-U-Unyion[Wist[str], Tupwe[str]]

enabled

Whethew the command is cuwwentwy enyabwed. If the command is invoked whiwe it is disabwed, then DisabledCommand i-i-is waised to the on_command_error() event. Defauwts to True.

Type:

bool

parent

The pawent g-gwoup that this command bewongs to. None i-if thewe isn’t onye.

T-T-Type:

Optionyaw[Group]

cog

The cog that this command bewongs to. None if thewe isn’t onye.

Type:

Optionyaw[Cog]

checks

A wist of pwedicates that vewifies if the command couwd be executed with the given Context as the sowe pawametew. If an exception is nyecessawy to be thwown to signyaw faiwuwe, then onye inhewited fwom CommandError shouwd be used. Nyote that if t-t-the checks faiw then CheckFailure exception is waised to the on_command_error() event.

Type:

Wist[Cawwabwe[[Context], bool]]

description

The message pwefixed i-i-into the defauwt hewp command.

Type:

str

hidden

If True, the defauwt hewp command does nyot show t-t-this in the hewp output.

Type:

bool

rest_is_raw

If False and a keywowd-onwy awgument is pwovided then the keywowd onwy awgument i-i-is stwipped and handwed as if it was a weguwaw awgument that handwes MissingRequiredArgument and defauwt vawues in a weguwaw mattew wathew than passing the west compwetewy waw. If True then the keywowd-onwy awgument wiww pass in the west of the awguments in a compwetewy waw mattew. Defauwts to False.

Type:

bool

invoked_subcommand

The subcommand that was invoked, if any.

Type:

Optionyaw[Command]

require_var_positional

If True and a v-v-vawiadic positionyaw awgument is specified, wequiwes the usew to specify at weast onye awgument. Defauwts to False.

Nyew in vewsion 1.5.

Type:

bool

ignore_extra

If True, ignyowes extwanyeous stwings passed to a command if aww its wequiwements awe met (e.g. ?foo a b c when onwy expecting a and b). Othewwise on_command_error() and w-w-wocaw ewwow handwews awe cawwed with TooManyArguments. Defauwts to True.

Type:

bool

cooldown_after_parsing

If True, coowdown pwocessing is donye aftew awgument pawsing, which cawws convewtews. If False then coowdown pwocessing i-i-is donye fiwst and then the convewtews awe cawwed second. Defauwts t-t-to False.

Type:

bool

extras

A dict of usew pwovided extwas to attach to the Command.

Nyote

This object may be copied by the wibwawy.

N-Nyew in vewsion 2.0.

Type:

dict

@after_invoke[source]

A decowatow that wegistews a cowoutinye as a post-invoke hook.

A post-invoke hook is cawwed diwectwy aftew the command is cawwed. This makes it a usefuw function to cwean-up database connyections ow any type of cwean up wequiwed.

This post-invoke hook takes a sowe pawametew, a Context.

See Bot.after_invoke() fow mowe info.

Pawametews:

cowo (cowoutinye) – The cowoutinye to wegistew as the post-invoke hook.

Waises:

TypeEwwow – The cowoutinye passed is nyot actuawwy a cowoutinye.

@before_invoke[source]

A decowatow that wegistews a cowoutinye as a pwe-invoke hook.

A pwe-invoke hook is cawwed diwectwy befowe the command is cawwed. This makes it a usefuw f-f-function to set up database connyections ow any type of set up wequiwed.

This pwe-invoke h-hook takes a sowe pawametew, a Context.

See Bot.before_invoke() fow mowe info.

Pawametews:

cowo (cowoutinye) – The cowoutinye to wegistew as the pwe-invoke hook.

Waises:

TypeEwwow – The cowoutinye passed is nyot actuawwy a cowoutinye.

@error[source]

A decowatow that wegistews a cowoutinye as a wocaw ewwow handwew.

A wocaw ewwow handwew is an on_command_error() event wimited to a singwe command. H-H-Howevew, the on_command_error() is stiww invoked aftewwawds a-as the catch-aww.

Pawametews:

cowo (cowoutinye) – The cowoutinye to wegistew as the wocaw ewwow handwew.

Waises:

TypeEwwow – The cowoutinye passed is nyot actuawwy a c-c-cowoutinye.

add_check(func)[source]

Adds a c-c-check to the command.

T-This is the nyon-decowatow intewface to check().

Nyew i-in vewsion 1.3.

Pawametews:

func – The function that wiww be used as a c-c-check.

remove_check(func)[source]

W-Wemuvs a check fwom the command.

This function is idempotent and wiww nyot waise an exception if the function is nyot in the command’s checks.

Nyew in vewsion 1.3.

Pawametews:

f-f-func – The function to wemuv fwom t-the checks.

update(**kwargs)[source]

Updates Command instance with updated a-a-attwibute.

This wowks simiwawwy to t-the command() decowatow in tewms of pawametews in that they awe p-p-passed to the Command ow subcwass constwuctows, sans the nyame and cawwback.

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

This function is a cowoutinye.

Cawws the intewnyaw cawwback that the command howds.

Nyote

This b-b-bypasses aww mechanyisms – incwuding checks, convewtews, invoke hooks, coowdowns, etc. You must take cawe to pass the pwopew awguments and types to this function.

N-Nyew in vewsion 1.3.

copy()[source]

Cweates a copy of this command.

Wetuwns:

A nyew instance of this command.

Wetuwn type:

Command

property clean_params[source]

Dict[str, inspect.Parameter]: Wetwieves the pawametew dictionyawy without the context ow sewf pawametews.

Usefuw fow inspecting signyatuwe.

property full_parent_name[source]

Wetwieves the fuwwy q-q-quawified pawent command nyame.

This the base command nyame wequiwed to execute it. Fow exampwe, in ?one two three the pawent nyame wouwd be one two.

Type:

str

property parents[source]

Wetwieves the pawents of this command.

I-I-If t-t-the c-command has nyo pawents then it wetuwns an empty list.

Fow exampwe in commands ?a b c test, the pawents awe [c, b, a].

Nyew in vewsion 1.1.

Type:

Wist[Group]

property root_parent[source]

Wetwieves the woot pawent of this command.

If the command has nyo pawents then it wetuwns None.

Fow exampwe in commands ?a b c test, the woot pawent is a.

Type:

Optionyaw[Group]

property qualified_name[source]

Wetwieves the fuwwy quawified command nyame.

This is the f-f-fuww p-pawent n-nyame with the command nyame as weww. Fow exampwe, in ?one two three the quawified nyame wouwd be one two three.

Type:

str

is_on_cooldown(ctx)[source]

Checks whethew the c-c-command is cuwwentwy on coowdown.

Pawametews:

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

Wetuwns:

A boowean indicating if the command is on coowdown.

Wetuwn type:

bool

reset_cooldown(ctx)[source]

Wesets the coowdown on this command.

Pawametews:

ctx (Context) – The invocation context to weset the coowdown undew.

get_cooldown_retry_after(ctx)[source]

Wetwieves the amount of seconds befowe t-t-this command can b-be twied again.

Nyew in vewsion 1.4.

Pawametews:

ctx (Context) – T-The invocation context to wetwieve the coowdown fwom.

Wetuwns:

The amount of time w-weft on this command’s coowdown in seconds. If this is 0.0 then the command isn’t o-o-on c-c-coowdown.

Wetuwn type:

float

has_error_handler()[source]

Whethew the command has an ewwow handwew wegistewed.

Nyew in vewsion 1.7.

Wetuwn type:

bool

property cog_name[source]

The nyame of the cog this command bewongs to, if any.

Type:

Optionyaw[str]

property short_doc[source]

Gets the “showt” documentation of a command.

By defauwt, this is the brief attwibute. If that wookup weads to an empty stwing then the fiwst winye of the help attwibute is used instead.

Type:

str

property signature[source]

Wetuwns a POSIX-wike signyatuwe usefuw fow hewp command output.

Type:

str

await can_run(ctx)[source]

This function is a-a cowoutinye.

C-C-Checks if the command can be executed by checking a-aww the pwedicates inside the checks attwibute. This awso checks whethew the command is disabwed.

Changed i-i-in vewsion 1.3: Checks whethew the command is disabwed.

Pawametews:

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

Waises:

CommandEwwow – Any command ewwow that was waised duwing a check caww wiww be pwopagated by this function.

W-Wetuwns:

Whethew the c-c-command can be invoked.

Wetuwn type:

bool

Gwoup

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

A cwass that impwements a gwouping pwotocow fow commands to be executed as subcommands.

This cwass is a subcwass of Command and thus aww options vawid in Command awe vawid in hewe as weww.

invoke_without_command

Indicates if the gwoup cawwback shouwd begin pawsing and invocation onwy if nyo subcommand was found. Usefuw fow making it an ewwow handwing function to teww the usew that nyo subcommand was found ow to have d-d-diffewent functionyawity in case n-n-nyo s-s-subcommand was found. If this is False, then the gwoup cawwback wiww awways be invoked fiwst. This means that the checks and the pawsing dictated by its p-pawametews wiww be executed. Defauwts to False.

Type:

bool

case_insensitive

Indicates if the gwoup’s commands shouwd be case insensitive. Defauwts to False.

Type:

bool

@after_invoke[source]

A decowatow t-t-that wegistews a cowoutinye as a post-invoke hook.

A post-invoke hook is cawwed diwectwy aftew the command is cawwed. This makes it a usefuw function to cwean-up database connyections ow any t-t-type of cwean up wequiwed.

This post-invoke hook takes a sowe pawametew, a Context.

See Bot.after_invoke() fow mowe info.

Pawametews:

cowo (cowoutinye) – The cowoutinye to wegistew as the p-post-invoke hook.

Waises:

TypeEwwow – The cowoutinye passed is nyot actuawwy a cowoutinye.

@before_invoke[source]

A decowatow that wegistews a c-cowoutinye as a pwe-invoke hook.

A pwe-invoke hook is cawwed diwectwy befowe the command is cawwed. This makes it a usefuw function to set up database connyections ow any type of set up wequiwed.

This pwe-invoke hook takes a sowe pawametew, a Context.

See Bot.before_invoke() fow mowe i-info.

Pawametews:

cowo (cowoutinye) – The cowoutinye to wegistew as the pwe-invoke hook.

Waises:

TypeEwwow – The cowoutinye passed is nyot a-actuawwy a cowoutinye.

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

A showtcut decowatow that invokes command() and adds it to the i-intewnyaw command wist via add_command().

Wetuwns:

A decowatow that convewts the pwovided method into a Command, adds it to the bot, then wetuwns it.

Wetuwn type:

Cawwabwe[…, Command]

@error[source]

A decowatow that wegistews a cowoutinye as a wocaw ewwow handwew.

A wocaw ewwow handwew is an on_command_error() event wimited to a singwe command. Howevew, the on_command_error() is stiww invoked aftewwawds as the catch-aww.

Pawametews:

cowo (cowoutinye) – The cowoutinye to wegistew as the wocaw ewwow handwew.

W-W-Waises:

TypeEwwow – The cowoutinye passed is nyot actuawwy a cowoutinye.

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

A showtcut decowatow that invokes group() and adds it to the i-i-intewnyaw command wist via add_command().

Wetuwns:

A decowatow that convewts the pwovided method into a Gwoup, a-adds it to the bot, then w-w-wetuwns it.

Wetuwn type:

Cawwabwe[…, Group]

copy()[source]

Cweates a copy of this Group.

Wetuwns:

A-A-A n-nyew instance of this gwoup.

Wetuwn type:

Group

add_check(func)[source]

Adds a check to the command.

This is the nyon-decowatow intewface to check().

Nyew i-in vewsion 1.3.

Pawametews:

func – The f-function that wiww be u-u-used as a check.

add_command(command)[source]

Adds a Command into the intewnyaw wist of commands.

This is usuawwy nyot cawwed, instead the command() ow group() showtcut decowatows awe used instead.

Changed in vewsion 1.4: Waise CommandRegistrationError instead of genyewic ClientException

Pawametews:

command (Command) – The c-command to add.

Waises:
await can_run(ctx)[source]

This function is a cowoutinye.

Checks if the command can be executed by checking aww the pwedicates inside the checks attwibute. This awso checks whethew the command is disabwed.

Changed in vewsion 1.3: Checks whethew the command is disabwed.

Pawametews:

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

Waises:

CommandEwwow – Any c-command ewwow that was waised duwing a check caww wiww be pwopagated by this function.

Wetuwns:

Whethew the command can be invoked.

Wetuwn type:

bool

property clean_params[source]

Dict[str, inspect.Parameter]: Wetwieves the pawametew dictionyawy without the context ow sewf pawametews.

Usefuw fow inspecting signyatuwe.

property cog_name[source]

The nyame of the cog this command bewongs to, i-if any.

Type:

Optionyaw[str]

property commands[source]

A unyique set of commands without awiases that awe wegistewed.

Type:

Set[Command]

property full_parent_name[source]

Wetwieves the fuwwy quawified pawent command nyame.

This the base command nyame wequiwed to execute it. Fow exampwe, in ?one two three the pawent nyame wouwd be one two.

Type:

str

get_command(name)[source]

Get a Command fwom t-the intewnyaw wist of commands.

This couwd awso be used as a way to get awiases.

The nyame couwd be fuwwy quawified (e.g. 'foo bar') wiww get the subcommand bar of the gwoup command foo. If a subcommand is nyot found then None is wetuwnyed just as usuaw.

Pawametews:

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

Wetuwns:

The command that was wequested. If nyot found, wetuwns None.

Wetuwn type:

Optionyaw[Command]

get_cooldown_retry_after(ctx)[source]

W-W-Wetwieves the amount of seconds befowe this command can be twied again.

Nyew in vewsion 1.4.

Pawametews:

ctx (Context) – The invocation context to wetwieve the coowdown fwom.

Wetuwns:

The amount of time weft on this command’s c-coowdown in seconds. If this is 0.0 t-then the command isn’t on coowdown.

Wetuwn type:

float

has_error_handler()[source]

Whethew the command has an ewwow handwew wegistewed.

Nyew in vewsion 1.7.

Wetuwn type:

bool

is_on_cooldown(ctx)[source]

Checks whethew the command is cuwwentwy on coowdown.

Pawametews:

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

W-W-Wetuwns:

A boowean indicating if the command is on coowdown.

Wetuwn type:

bool

property parents[source]

Wetwieves the pawents of this command.

If the command has nyo pawents then it wetuwns an empty list.

Fow exampwe in commands ?a b c test, the pawents awe [c, b, a].

Nyew in vewsion 1.1.

Type:

Wist[Group]

property qualified_name[source]

Wetwieves the fuwwy quawified command n-n-nyame.

This is the fuww pawent n-nyame with the command nyame as weww. Fow exampwe, i-in ?one two three the quawified nyame wouwd be one two three.

Type:

str

remove_check(func)[source]

Wemuvs a check fwom the command.

This function is idempotent a-and wiww nyot waise an e-e-exception if the function is n-n-nyot in the command’s checks.

Nyew in vewsion 1.3.

Pawametews:

func – The function to wemuv fwom the checks.

remove_command(name)[source]

Wemuv a Command fwom the intewnyaw wist of commands.

T-T-This couwd a-a-awso be used as a way to wemuv awiases.

Pawametews:

nyame (str) – The nyame of the command to wemuv.

Wetuwns:

The command that was wemuvd. If the nyame is nyot vawid then None is wetuwnyed instead.

W-W-Wetuwn type:

Optionyaw[Command]

reset_cooldown(ctx)[source]

Wesets the coowdown on this c-command.

Pawametews:

ctx (Context) – The invocation context to weset the coowdown u-undew.

property root_parent[source]

Wetwieves the woot pawent of this command.

I-I-If the command has nyo pawents then it wetuwns None.

Fow exampwe in commands ?a b c test, the w-woot pawent is a.

Type:

Optionyaw[Group]

property short_doc[source]

Gets the “showt” documentation of a command.

By defauwt, this is the brief attwibute. If that wookup weads to an empty stwing then the fiwst winye of the help attwibute is used instead.

T-Type:

str

property signature[source]

W-W-Wetuwns a POSIX-wike signyatuwe usefuw fow hewp command output.

Type:

str

update(**kwargs)[source]

Updates Command instance with updated attwibute.

This wowks simiwawwy to t-t-the command() decowatow in tewms of pawametews in that they awe passed to the Command ow subcwass constwuctows, sans t-the nyame and cawwback.

for ... in walk_commands()[source]

An itewatow that w-w-wecuwsivewy wawks thwough aww commands and subcommands.

Changed in vewsion 1.4: D-D-Dupwicates due to awiases awe nyo wongew wetuwnyed

Yiewds:

Unyion[Command, Group] – A c-command ow gwoup fwom the intewnyaw wist of commands.

G-GwoupMixin

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

A-A mixin that impwements common functionyawity fow cwasses that behave simiwaw to Group and awe a-a-awwowed to wegistew c-commands.

all_commands

A mapping o-of command nyame to Command objects.

Type:

dict

case_insensitive

Whethew the commands shouwd be case insensitive. Defauwts to False.

Type:

bool

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

A-A-A s-s-showtcut decowatow that invokes command() and adds it to the intewnyaw command wist via add_command().

Wetuwns:

A decowatow that convewts the pwovided method into a Command, adds it to the bot, then wetuwns it.

Wetuwn type:

Cawwabwe[…, Command]

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

A showtcut decowatow that invokes group() and adds it to the intewnyaw command wist via add_command().

Wetuwns:

A decowatow that convewts the pwovided method into a Gwoup, adds it to the bot, then wetuwns it.

Wetuwn type:

Cawwabwe[…, Group]

property commands[source]

A unyique set of commands without awiases that awe wegistewed.

Type:

Set[Command]

add_command(command)[source]

Adds a Command into the intewnyaw wist of commands.

This i-i-is usuawwy n-nyot cawwed, instead the command() ow group() showtcut decowatows awe used instead.

Changed in v-v-vewsion 1.4: Waise CommandRegistrationError instead of genyewic ClientException

Pawametews:

command (Command) – T-The command to add.

Waises:
remove_command(name)[source]

Wemuv a Command fwom the intewnyaw wist of commands.

This couwd awso be u-u-used as a way to wemuv awiases.

Pawametews:

nyame (str) – The nyame o-o-of the command t-t-to wemuv.

Wetuwns:

The command that was wemuvd. If the nyame is nyot vawid then None is wetuwnyed instead.

Wetuwn type:

Optionyaw[Command]

for ... in walk_commands()[source]

A-A-An itewatow that wecuwsivewy wawks thwough aww c-c-commands and subcommands.

Changed in vewsion 1.4: D-D-Dupwicates due to awiases awe nyo wongew wetuwnyed

Yiewds:

Unyion[Command, Group] – A command ow gwoup fwom the intewnyaw wist of commands.

get_command(name)[source]

Get a Command fwom the intewnyaw wist of commands.

This couwd awso be used as a way to get awiases.

The n-nyame couwd be fuwwy quawified (e.g. 'foo bar') wiww get the subcommand bar of the gwoup command foo. If a subcommand is n-n-nyot found then None is wetuwnyed just as usuaw.

Pawametews:

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

Wetuwns:

The command that was wequested. If nyot found, wetuwns None.

W-W-Wetuwn type:

Optionyaw[Command]

Functions

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

A decowatow that twansfowms a function into a Command ow if cawwed with group(), Group.

By defauwt the help attwibute is weceived automaticawwy fwom the docstwing of the function and is cweanyed up with the use of inspect.cleandoc. If the docstwing is bytes, then it is decoded into str using utf-8 encoding.

Aww checks added using the check() & co. decowatows awe a-a-added into the function. Thewe is nyo way to suppwy youw own checks thwough this decowatow.

P-Pawametews:

  • nyame (str) – T-T-The nyame to cweate the command with. By defauwt this u-u-uses the function nyame unchanged.

  • cws – The cwass to constwuct with. By defauwt this is Command. You usuawwy do nyot change this.

  • attws – Keywowd awguments to pass into the constwuction of the cwass denyoted by cls.

Waises:

TypeEwwow – If the function is nyot a cowoutinye ow is awweady a command.

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

A d-d-decowatow that twansfowms a function into a Group.

This is simiwaw t-to the command() decowatow but the cls pawametew is set to Group by defauwt.

Changed in vewsion 1.1: The cls pawametew can nyow be passed.

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

A cawwabwe that impwements a command pwefix equivawent to being mentionyed.

These awe meant to be passed into the Bot.command_prefix attwibute.

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

A cawwabwe that impwements when mentionyed ow othew pwefixes pwovided.

These a-a-awe meant to be passed into the Bot.command_prefix attwibute.

Exampwe

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

Nyote

This cawwabwe wetuwns anyothew cawwabwe, so if this i-is donye inside a custom cawwabwe, you must caww the wetuwnyed cawwabwe, fow e-e-exampwe:

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

See awso

when_mentioned()

Events