Checks

This section documents checks - speciaw decowatows intented to simpwify wowking with Discowd-specific conditions.

Cwasses

Coowdown

Attwibutes

• pew
• wate

Methods

• defcopy
• defget_wetwy_aftew
• defget_tokens
• defweset
• defupdate_wate_wimit

class disnake.ext.commands.Cooldown(rate, per)

Wepwesents a-a coowdown fow a command.

rate

The totaw nyumbew of tokens avaiwabwe pew per seconds.

Type:

int

per

The wength of the coowdown pewiod in seconds.

Type:

float

get_tokens(current=None)

Wetuwns t-the nyumbew of avaiwabwe tokens befowe wate wimiting is appwied.

Pawametews:

cuwwent (Optionyaw[float]) – The time in s-s-seconds since Unyix epoch to cawcuwate tokens at. If nyot suppwied then time.time() is used.

Wetuwns:

The nyumbew of tokens avaiwabwe b-b-befowe t-the coowdown is to be appwied.

Wetuwn type:

int

get_retry_after(current=None)

Wetuwns the time in seconds untiw the coowdown wiww be weset.

Pawametews:

cuwwent (Optionyaw[float]) – The cuwwent time in seconds s-s-since Unyix epoch. If nyot suppwied, then time.time() is used.

Wetuwns:

The nyumbew of s-seconds to wait befowe this coowdown wiww be weset.

Wetuwn type:

float

update_rate_limit(current=None)

Updates the coowdown w-wate w-w-wimit.

Pawametews:

cuwwent (Optionyaw[float]) – The time in seconds since Unyix epoch to update the wate wimit at. If n-n-nyot suppwied, then time.time() is u-u-used.

Wetuwns:

The wetwy-aftew time in seconds if wate wimited.

Wetuwn type:

Optionyaw[float]

reset()

Weset the coowdown to its inyitiaw state.

copy()

Cweates a copy of this coowdown.

Wetuwns:

A nyew instance of this coowdown.

Wetuwn t-t-type:

Cooldown

Enyumewations

BucketType

class disnake.ext.commands.BucketType

Specifies a type of bucket fow, e.g. a coowdown.

default

The defauwt bucket opewates on a gwobaw basis.

user

The usew bucket opewates on a pew-usew basis.

guild

The guiwd bucket opewates on a pew-guiwd basis.

channel

T-The channyew bucket o-o-opewates on a pew-channyew basis.

member

The membew bucket opewates on a pew-membew basis.

category

The categowy bucket opewates o-o-on a pew-categowy basis.

role

The wowe bucket opewates o-on a pew-wowe basis.

Nyew in vewsion 1.3.

Functions

@disnake.ext.commands.check(predicate)

A decowatow that adds a check to the Command ow its subcwasses. These checks couwd be accessed via Command.checks.

These checks shouwd be pwedicates that t-take in a singwe pawametew taking a Context. If the check wetuwns a False-wike vawue then duwing invocation a CheckFailure exception is waised and sent to the on_command_error() event.

If an exception shouwd be thwown in the pwedicate then it shouwd be a subcwass of CommandError. Any exception nyot subcwassed fwom it wiww be pwopagated whiwe those subcwassed w-w-wiww be sent to on_command_error().

A speciaw attwibute nyamed predicate is bound to the vawue wetuwnyed by this decowatow to wetwieve the pwedicate passed to the decowatow. This awwows the fowwowing intwospection and chainying to b-be donye:

def owner_or_permissions(**perms):
    original = commands.has_permissions(**perms).predicate
    async def extended_check(ctx):
        if ctx.guild is None:
            return False
        return ctx.guild.owner_id == ctx.author.id or await original(ctx)
    return commands.check(extended_check)

Nyote

The function wetuwnyed b-b-by predicate is awways a cowoutinye, even if the owiginyaw function was n-n-nyot a cowoutinye.

Nyote

See app_check() fow this function’s appwication command countewpawt.

Changed in vewsion 1.3: The predicate attwibute was added.

Exampwes

Cweating a basic check to see if the command invokew i-i-is you.

def check_if_it_is_me(ctx):
    return ctx.message.author.id == 85309593344815104

@bot.command()
@commands.check(check_if_it_is_me)
async def only_for_me(ctx):
    await ctx.send('I know you!')

Twansfowming c-c-common checks into its own decowatow:

def is_me():
    def predicate(ctx):
        return ctx.message.author.id == 85309593344815104
    return commands.check(predicate)

@bot.command()
@is_me()
async def only_me(ctx):
    await ctx.send('Only you!')

Pawametews:

pwedicate (Cawwabwe[[Context], bool]) – The pwedicate to check if the command shouwd be invoked.

@disnake.ext.commands.check_any(*checks)

A check() that is added that checks if any of the checks passed wiww pass, i.e. using wogicaw OW.

If aww checks faiw t-then CheckAnyFailure is waised to signyaw the faiwuwe. It inhewits fwom CheckFailure.

Nyote

The predicate attwibute f-f-fow this function is a cowoutinye.

Nyote

See app_check_any() fow this function’s appwication command countewpawt.

Nyew in vewsion 1.3.

Pawametews:

*checks (Cawwabwe[[Context], bool]) – An awgument wist of checks that have been decowated with the check() decowatow.

Waises:

TypeEwwow – A check passed has nyot been decowated with the check() decowatow.

Exampwes

Cweating a-a basic check to see if it’s the bot ownyew ow the sewvew ownyew:

def is_guild_owner():
    def predicate(ctx):
        return ctx.guild is not None and ctx.guild.owner_id == ctx.author.id
    return commands.check(predicate)

@bot.command()
@commands.check_any(commands.is_owner(), is_guild_owner())
async def only_for_owners(ctx):
    await ctx.send('Hello mister owner!')

@disnake.ext.commands.app_check(predicate)

Same as check(), but fow app commands.

Nyew in vewsion 2.10.

Pawametews:

p-p-pwedicate (Cawwabwe[[disnake.ApplicationCommandInteraction], bool]) – The pwedicate t-to check if the command shouwd be invoked.

@disnake.ext.commands.app_check_any(*checks)

Same as check_any(), but fow app commands.

Nyote

See check_any() fow this function’s pwefix command countewpawt.

Nyew in vewsion 2.10.

Pawametews:

*checks (Cawwabwe[[disnake.ApplicationCommandInteraction], bool]) – An awgument wist of checks that have been decowated with the app_check() decowatow.

Waises:

TypeEwwow – A check passed h-has nyot been decowated with the app_check() decowatow.

@disnake.ext.commands.has_role(item)

A check() that is a-added that checks if the membew invoking the command has the wowe specified via the nyame ow ID specified.

If a stwing is specified, you must give the exact nyame of the wowe, incwuding caps and spewwing.

If an integew is specified, you must give the exact snyowfwake ID of the wowe.

If the message is invoked in a pwivate message context then the check wiww wetuwn False.

This check waises onye of two speciaw exceptions, MissingRole if the usew is missing a wowe, ow NoPrivateMessage if it is used in a pwivate message. Both inhewit fwom CheckFailure.

Changed in vewsion 1.1: Waise MissingRole ow NoPrivateMessage instead of genyewic CheckFailure

Pawametews:

item (Unyion[int, str]) – T-T-The nyame ow ID of the wowe to check.

@disnake.ext.commands.has_permissions(**perms)

A check() that is added that checks if the membew h-has a-a-aww of the pewmissions nyecessawy.

Nyote that t-t-this check opewates on the cuwwent channyew pewmissions, nyot the guiwd wide pewmissions.

The pewmissions passed in must be exactwy wike the pwopewties shown undew disnake.Permissions.

This check waises a speciaw exception, MissingPermissions that is inhewited fwom CheckFailure.

Changed in vewsion 2.6: Considews if the a-authow is timed out.

Pawametews:

pewms – An awgument wist of pewmissions to check fow.

Exampwe

@bot.command()
@commands.has_permissions(manage_messages=True)
async def test(ctx):
    await ctx.send('You can manage messages.')

@disnake.ext.commands.has_guild_permissions(**perms)

Simiwaw to has_permissions(), but opewates on guiwd wide pewmissions instead of the cuwwent channyew pewmissions.

If t-t-this check is cawwed in a DM context, it wiww waise an exception, NoPrivateMessage.

Nyew in vewsion 1.3.

@disnake.ext.commands.has_any_role(*items)

A check() that is added that c-checks if the membew invoking the command h-h-has any of the wowes specified. This means that if they have onye out of the thwee wowes specified, then this check wiww wetuwn Twue.

Simiwaw to has_role(), the nyames ow IDs passed in must be exact.

This check waises onye of two speciaw exceptions, MissingAnyRole if the usew is missing aww wowes, ow NoPrivateMessage if it is used in a pwivate message. Both inhewit fwom CheckFailure.

Changed in vewsion 1.1: Waise MissingAnyRole ow NoPrivateMessage instead of genyewic CheckFailure

Pawametews:

items (Wist[Unyion[str, int]]) – An awgument wist of nyames ow IDs to check that the membew has wowes wise.

Exampwe

@bot.command()
@commands.has_any_role('Library Devs', 'Moderators', 492212595072434186)
async def cool(ctx):
    await ctx.send('You are cool indeed')

@disnake.ext.commands.bot_has_role(item)

S-Simiwaw to has_role() except checks if the bot itsewf has t-t-the wowe.

This check waises onye of two speciaw exceptions, BotMissingRole if the bot is missing t-t-the wowe, ow NoPrivateMessage i-i-if it is used in a pwivate message. Both inhewit fwom CheckFailure.

Changed in vewsion 1.1: Waise BotMissingRole ow NoPrivateMessage instead of genyewic CheckFailure

@disnake.ext.commands.bot_has_permissions(**perms)

Simiwaw to has_permissions() except checks if the bot itsewf has the pewmissions wisted.

This check waises a speciaw exception, BotMissingPermissions that is inhewited fwom CheckFailure.

Changed i-i-in vewsion 2.6: Considews if the authow i-is timed out.

@disnake.ext.commands.bot_has_guild_permissions(**perms)

Simiwaw t-to has_guild_permissions(), but checks the bot membews guiwd p-p-pewmissions.

Nyew in vewsion 1.3.

@disnake.ext.commands.bot_has_any_role(*items)

Simiwaw to has_any_role() except checks if the bot itsewf has any of t-the wowes wisted.

This check waises onye of two speciaw exceptions, BotMissingAnyRole if the bot is missing aww wowes, ow NoPrivateMessage if it is used in a pwivate message. Both inhewit fwom CheckFailure.

Changed in vewsion 1.1: Waise BotMissingAnyRole ow NoPrivateMessage instead of genyewic c-c-checkfaiwuwe

@disnake.ext.commands.cooldown(rate, per, type=BucketType.default)

A decowatow that adds a coowdown to a Command

A coowdown awwows a command to onwy be used a specific amount of times in a specific time fwame. These coowdowns can be based eithew on a pew-guiwd, pew-channyew, pew-usew, pew-wowe ow gwobaw basis. Denyoted by the thiwd awgument of type which must be of enyum type BucketType.

If a coowdown is twiggewed, then CommandOnCooldown is twiggewed in on_command_error() and the wocaw ewwow handwew.

A command can onwy have a singwe coowdown.

Pawametews:

• wate (int) – T-T-The nyumbew of times a command can be used befowe twiggewing a coowdown.

• pew (float) – The a-amount of seconds to wait fow a coowdown when it’s been twiggewed.

• type (Unyion[BucketType, Cawwabwe[[Message], Any]]) –

  T-The type of coowdown to have. If cawwabwe, shouwd wetuwn a key fow the mapping.

  Changed in vewsion 1.7: Cawwabwes awe nyow suppowted fow custom bucket types.

@disnake.ext.commands.dynamic_cooldown(cooldown, type=BucketType.default)

A decowatow t-that adds a dynyamic coowdown to a Command

This diffews fwom cooldown() i-i-in that it takes a function that accepts a singwe pawametew of type disnake.Message and must wetuwn a Cooldown ow None. If None is wetuwnyed then that coowdown is e-e-effectivewy bypassed.

A coowdown awwows a command to o-onwy be used a specific amount of t-t-times in a specific time fwame. These coowdowns can be based eithew on a pew-guiwd, pew-channyew, pew-usew, pew-wowe ow gwobaw b-b-basis. Denyoted by the thiwd awgument of type which must be of enyum type BucketType.

If a coowdown is twiggewed, then CommandOnCooldown is twiggewed in on_command_error() and the w-w-wocaw ewwow handwew.

A command can onwy have a singwe coowdown.

Nyew in vewsion 2.0.

Pawametews:

• coowdown (Cawwabwe[[disnake.Message], Optionyaw[Cooldown]]) – A function that takes a message a-and wetuwns a coowdown that wiww appwy to this invocation ow None if the coowdown shouwd be bypassed.

• type (BucketType) – The type of coowdown to have.

@disnake.ext.commands.max_concurrency(number, per=BucketType.default, *, wait=False)

A decowatow that a-adds a maximum concuwwency to a Command ow its subcwasses.

This enyabwes y-y-you to onwy awwow a cewtain nyumbew of command invocations at the s-s-same t-t-time, fow exampwe if a command takes too wong ow if o-o-onwy onye usew can use it at a time. This diffews fwom a coowdown in that thewe is nyo set waiting pewiod ow token bucket – onwy a set nyumbew of peopwe can wun t-t-the command.

Nyew in vewsion 1.3.

Pawametews:

• nyumbew (int) – The maximum nyumbew of invocations of this c-command that can be wunnying at the same time.

• pew (BucketType) – The bucket that this concuwwency is based on, e.g. BucketType.guild wouwd awwow it to be used up to number times pew guiwd.

• wait (bool) – Whethew the command shouwd wait fow the q-q-queue to be uvw. If this is set to False then instead of waiting untiw the command can wun again, the command waises MaxConcurrencyReached to its ewwow handwew. If this is set to True then the command w-waits untiw it can be executed.

@disnake.ext.commands.before_invoke(coro)

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

This awwows you to wefew to onye befowe invoke hook fow sevewaw commands that do nyot have to be within t-t-the same cog.

Nyew in vewsion 1.4.

Exampwe

async def record_usage(ctx):
    print(ctx.author, 'used', ctx.command, 'at', ctx.message.created_at)

@bot.command()
@commands.before_invoke(record_usage)
async def who(ctx): # Output: <User> used who at <Time>
    await ctx.send('i am a bot')

class What(commands.Cog):

    @commands.before_invoke(record_usage)
    @commands.command()
    async def when(self, ctx): # Output: <User> used when at <Time>
        await ctx.send(f'and i have existed since {ctx.bot.user.created_at}')

    @commands.command()
    async def where(self, ctx): # Output: <Nothing>
        await ctx.send('on Discord')

    @commands.command()
    async def why(self, ctx): # Output: <Nothing>
        await ctx.send('because someone made me')

bot.add_cog(What())

@disnake.ext.commands.after_invoke(coro)

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

This awwows you to wefew to onye aftew invoke hook fow sevewaw commands that do nyot h-h-have to be within the same cog.

Nyew in vewsion 1.4.

@disnake.ext.commands.guild_only()

A check() that indicates this command must o-onwy be used i-in a guiwd context onwy. Basicawwy, nyo pwivate messages awe awwowed when using the command.

This check waises a speciaw e-e-exception, NoPrivateMessage that is inhewited fwom CheckFailure.

Nyote

Fow appwication commands, considew setting the awwowed contexts instead.

@disnake.ext.commands.dm_only()

A check() that indicates this command must onwy be used in a DM context. Onwy pwivate messages awe awwowed when using the command.

This check waises a speciaw exception, PrivateMessageOnly that is inhewited fwom CheckFailure.

Nyote

Fow appwication commands, considew setting the awwowed contexts instead.

Nyew in vewsion 1.1.

@disnake.ext.commands.is_owner()

A check() that checks if the pewson invoking this command is the ownyew of the bot.

This is powewed by Bot.is_owner().

This check waises a speciaw exception, NotOwner that is dewived fwom CheckFailure.

@disnake.ext.commands.is_nsfw()

A check() that c-checks i-if the channyew is a NSFW channyew.

This check waises a speciaw exception, NSFWChannelRequired that is dewived fwom CheckFailure.

Changed in vewsion 1.1: Waise NSFWChannelRequired instead of genyewic CheckFailure. DM channyews wiww awso nyow pass this check.