Skip to content

tanjun.checks#

A collection of common standard checks designed for Tanjun commands.

AuthorPermissionCheck #

Bases: _Check

Standard author permission check callback registered by tanjun.with_author_permission_check.

This check will only pass if the current author has the specified permission.

__init__(permissions, /, *, error=None, error_message="You don't have the permissions required to use this command", halt_execution=False) #

Initialise an author permission check.

PARAMETER DESCRIPTION
permissions

The permission(s) required for this command to run.

TYPE: typing.Union[hikari.Permissions, int]

error

Callback used to create a custom error to raise if the check fails.

This should take 1 positional argument of type hikari.permissions.Permissions which represents the missing permissions required for this command to run.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[hikari.Permissions], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

Setting this to None will disable the error message allowing the command search to continue.

TYPE: typing.Optional[str] DEFAULT: "You don't have the permissions required to use this command"

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

DmCheck #

Bases: _Check

Standard DM check callback registered by tanjun.with_dm_check.

This check will only pass if the current channel is a DM channel.

__init__(*, error=None, error_message='Command can only be used in DMs', halt_execution=False) #

Initialise a DM check.

PARAMETER DESCRIPTION
error

Callback used to create a custom error to raise if the check fails.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

Setting this to None will disable the error message allowing the command search to continue.

TYPE: typing.Optional[str] DEFAULT: 'Command can only be used in DMs'

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

GuildCheck #

Bases: _Check

Standard guild check callback registered by tanjun.with_guild_check.

This check will only pass if the current channel is in a guild.

__init__(*, error=None, error_message='Command can only be used in guild channels', halt_execution=False) #

Initialise a guild check.

PARAMETER DESCRIPTION
error

Callback used to create a custom error to raise if the check fails.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

Setting this to None will disable the error message allowing the command search to continue.

TYPE: typing.Optional[str] DEFAULT: 'Command can only be used in guild channels'

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

NsfwCheck #

Bases: _Check

Standard NSFW check callback registered by tanjun.with_nsfw_check.

This check will only pass if the current channel is NSFW.

__init__(*, error=None, error_message='Command can only be used in NSFW channels', halt_execution=False) #

Initialise a NSFW check.

PARAMETER DESCRIPTION
error

Callback used to create a custom error to raise if the check fails.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

Setting this to None will disable the error message allowing the command search to continue.

TYPE: typing.Optional[str] DEFAULT: 'Command can only be used in NSFW channels'

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

OwnPermissionCheck #

Bases: _Check

Standard own permission check callback registered by tanjun.with_own_permission_check.

This check will only pass if the current bot user has the specified permission.

__init__(permissions, /, *, error=None, error_message="Bot doesn't have the permissions required to run this command", halt_execution=False) #

Initialise a own permission check.

PARAMETER DESCRIPTION
permissions

The permission(s) required for this command to run.

TYPE: typing.Union[hikari.Permissions, int]

error

Callback used to create a custom error to raise if the check fails.

This should take 1 positional argument of type hikari.permissions.Permissions which represents the missing permissions required for this command to run.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[hikari.Permissions], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

Setting this to None will disable the error message allowing the command search to continue.

TYPE: typing.Optional[str] DEFAULT: "Bot doesn't have the permissions required to run this command"

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

OwnerCheck #

Bases: _Check

Standard owner check callback registered by tanjun.with_owner_check.

This check will only pass if the author of the command is a bot owner.

__init__(*, error=None, error_message='Only bot owners can use this command', halt_execution=False) #

Initialise an owner check.

PARAMETER DESCRIPTION
error

Callback used to create a custom error to raise if the check fails.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

Setting this to None will disable the error message allowing the command search to continue.

TYPE: typing.Optional[str] DEFAULT: 'Only bot owners can use this command'

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

SfwCheck #

Bases: _Check

Standard SFW check callback registered by tanjun.with_sfw_check.

This check will only pass if the current channel is SFW.

__init__(*, error=None, error_message='Command can only be used in SFW channels', halt_execution=False) #

Initialise a SFW check.

PARAMETER DESCRIPTION
error

Callback used to create a custom error to raise if the check fails.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

Setting this to None will disable the error message allowing the command search to continue.

TYPE: typing.Optional[str] DEFAULT: 'Command can only be used in SFW channels'

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

all_checks(check, /, *checks) #

Combine multiple check callbacks into a check which will only pass if all the callbacks pass.

This ensures that the callbacks are run in the order they were supplied in rather than concurrently.

PARAMETER DESCRIPTION
check

The first check callback to combine.

TYPE: tanjun.CheckSig

*checks

Additional check callbacks to combine.

TYPE: tanjun.CheckSig DEFAULT: ()

RETURNS DESCRIPTION
collections.abc.Callable[[tanjun.abc.Context], collections.abc.Coroutine[typing.Any, typing.Any, bool]]

A check which will pass if all of the provided check callbacks pass.

any_checks(check, /, *checks, error=None, error_message, halt_execution=False, suppress=(errors.CommandError, errors.HaltExecution)) #

Combine multiple checks into a check which'll pass if any of the callbacks pass.

This ensures that the callbacks are run in the order they were supplied in rather than concurrently.

PARAMETER DESCRIPTION
check

The first check callback to combine.

TYPE: tanjun.CheckSig

*checks

Additional check callbacks to combine.

TYPE: tanjun.CheckSig DEFAULT: ()

error

Callback used to create a custom error to raise if the check fails.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

TYPE: typing.Optional[str]

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

suppress

Tuple of the exceptions to suppress when a check fails.

TYPE: tuple[type[Exception], ...] DEFAULT: (errors.CommandError, errors.HaltExecution)

RETURNS DESCRIPTION
collections.Callable[[tanjun.abc.ExecutableCommand], tanjun.abc.ExecutableCommand]

A decorator which adds the generated check to a command.

with_all_checks(check, /, *checks, follow_wrapped=False) #

Add a check which will pass if all the provided checks pass through a decorator call.

This ensures that the callbacks are run in the order they were supplied in rather than concurrently.

PARAMETER DESCRIPTION
check

The first check callback to combine.

TYPE: tanjun.CheckSig

*checks

Additional check callbacks to combine.

TYPE: tanjun.CheckSig DEFAULT: ()

follow_wrapped

Whether to also add this check to any other command objects this command wraps in a decorator call chain.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
collections.abc.Callable[[tanjun.abc.Context], collections.abc.Coroutine[typing.Any, typing.Any, bool]]

A check which will pass if all of the provided check callbacks pass.

with_any_checks(check, /, *checks, error=None, error_message, follow_wrapped=False, halt_execution=False, suppress=(errors.CommandError, errors.HaltExecution)) #

Add a check which'll pass if any of the provided checks pass through a decorator call.

This ensures that the callbacks are run in the order they were supplied in rather than concurrently.

PARAMETER DESCRIPTION
check

The first check callback to combine.

TYPE: tanjun.CheckSig

*checks

Additional check callbacks to combine.

TYPE: tanjun.CheckSig DEFAULT: ()

error

Callback used to create a custom error to raise if the check fails.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

TYPE: typing.Optional[str]

follow_wrapped

Whether to also add this check to any other command objects this command wraps in a decorator call chain.

TYPE: bool DEFAULT: False

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

suppress

Tuple of the exceptions to suppress when a check fails.

TYPE: tuple[type[Exception], ...] DEFAULT: (errors.CommandError, errors.HaltExecution)

RETURNS DESCRIPTION
collections.Callable[[tanjun.abc.ExecutableCommand], tanjun.abc.ExecutableCommand]

A decorator which adds the generated check to a command.

with_author_permission_check(permissions, *, error=None, error_message="You don't have the permissions required to use this command", follow_wrapped=False, halt_execution=False) #

Only let a command run if the author has certain permissions in the current channel.

Note

This will only pass for commands in DMs if permissions is valid for a DM context (e.g. can't have any moderation permissions)

PARAMETER DESCRIPTION
permissions

The permission(s) required for this command to run.

TYPE: typing.Union[hikari.Permissions, int]

error

Callback used to create a custom error to raise if the check fails.

This should take 1 positional argument of type hikari.permissions.Permissions which represents the missing permissions required for this command to run.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[hikari.Permissions], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

Setting this to None will disable the error message allowing the command search to continue.

TYPE: typing.Optional[str] DEFAULT: "You don't have the permissions required to use this command"

follow_wrapped

Whether to also add this check to any other command objects this command wraps in a decorator call chain.

TYPE: bool DEFAULT: False

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
collections.abc.Callable[[tanjun.abc.ExecutableCommand], tanjun.abc.ExecutableCommand]

A command decorator callback which adds the check.

with_check(check, /, *, follow_wrapped=False) #

Add a generic check to a command.

PARAMETER DESCRIPTION
check

The check to add to this command.

TYPE: tanjun.CheckSig

follow_wrapped

Whether to also add this check to any other command objects this command wraps in a decorator call chain.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
collections.abc.Callable[[tanjun.abc.ExecutableCommand], tanjun.abc.ExecutableCommand]

A command decorator callback which adds the check.

with_dm_check(command=None, /, *, error=None, error_message='Command can only be used in DMs', follow_wrapped=False, halt_execution=False) #

Only let a command run in a DM channel.

PARAMETER DESCRIPTION
command

The command to add this check to.

TYPE: tanjun.abc.ExecutableCommand | None DEFAULT: None

error

Callback used to create a custom error to raise if the check fails.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

Setting this to None will disable the error message allowing the command search to continue.

TYPE: typing.Optional[str] DEFAULT: 'Command can only be used in DMs'

follow_wrapped

Whether to also add this check to any other command objects this command wraps in a decorator call chain.

TYPE: bool DEFAULT: False

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
tanjun.abc.ExecutableCommand

The command this check was added to.

with_guild_check(command=None, /, *, error=None, error_message='Command can only be used in guild channels', follow_wrapped=False, halt_execution=False) #

Only let a command run in a guild channel.

PARAMETER DESCRIPTION
command

The command to add this check to.

TYPE: tanjun.abc.ExecutableCommand | None DEFAULT: None

error

Callback used to create a custom error to raise if the check fails.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

Setting this to None will disable the error message allowing the command search to continue.

TYPE: typing.Optional[str] DEFAULT: 'Command can only be used in guild channels'

follow_wrapped

Whether to also add this check to any other command objects this command wraps in a decorator call chain.

TYPE: bool DEFAULT: False

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
tanjun.abc.ExecutableCommanmd

The command this check was added to.

with_nsfw_check(command=None, /, *, error=None, error_message='Command can only be used in NSFW channels', follow_wrapped=False, halt_execution=False) #

Only let a command run in a channel that's marked as nsfw.

PARAMETER DESCRIPTION
command

The command to add this check to.

TYPE: tanjun.abc.ExecutableCommand | None DEFAULT: None

error

Callback used to create a custom error to raise if the check fails.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

Setting this to None will disable the error message allowing the command search to continue.

TYPE: typing.Optional[str] DEFAULT: 'Command can only be used in NSFW channels'

follow_wrapped

Whether to also add this check to any other command objects this command wraps in a decorator call chain.

TYPE: bool DEFAULT: False

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
tanjun.abc.ExecutableCommand

The command this check was added to.

with_own_permission_check(permissions, *, error=None, error_message="Bot doesn't have the permissions required to run this command", follow_wrapped=False, halt_execution=False) #

Only let a command run if we have certain permissions in the current channel.

Note

This will only pass for commands in DMs if permissions is valid for a DM context (e.g. can't have any moderation permissions)

PARAMETER DESCRIPTION
permissions

The permission(s) required for this command to run.

TYPE: typing.Union[hikari.Permissions, int]

error

Callback used to create a custom error to raise if the check fails.

This should take 1 positional argument of type hikari.permissions.Permissions which represents the missing permissions required for this command to run.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[hikari.Permissions], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

Setting this to None will disable the error message allowing the command search to continue.

TYPE: typing.Optional[str] DEFAULT: "Bot doesn't have the permissions required to run this command"

follow_wrapped

Whether to also add this check to any other command objects this command wraps in a decorator call chain.

TYPE: bool DEFAULT: False

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
collections.abc.Callable[[tanjun.abc.ExecutableCommand], tanjun.abc.ExecutableCommand]

A command decorator callback which adds the check.

with_owner_check(command=None, /, *, error=None, error_message='Only bot owners can use this command', follow_wrapped=False, halt_execution=False) #

Only let a command run if it's being triggered by one of the bot's owners.

PARAMETER DESCRIPTION
command

The command to add this check to.

TYPE: tanjun.abc.ExecutableCommand | None DEFAULT: None

error

Callback used to create a custom error to raise if the check fails.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

Setting this to None will disable the error message allowing the command search to continue.

TYPE: typing.Optional[str] DEFAULT: 'Only bot owners can use this command'

follow_wrapped

Whether to also add this check to any other command objects this command wraps in a decorator call chain.

TYPE: bool DEFAULT: False

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
tanjun.abc.ExecutableCommand

The command this check was added to.

with_sfw_check(command=None, /, *, error=None, error_message='Command can only be used in SFW channels', follow_wrapped=False, halt_execution=False) #

Only let a command run in a channel that's marked as sfw.

PARAMETER DESCRIPTION
command

The command to add this check to.

TYPE: tanjun.abc.ExecutableCommand | None DEFAULT: None

error

Callback used to create a custom error to raise if the check fails.

This takes priority over error_message.

TYPE: typing.Optional[collections.Callable[[], Exception]] DEFAULT: None

error_message

The error message to send in response as a command error if the check fails.

Setting this to None will disable the error message allowing the command search to continue.

TYPE: typing.Optional[str] DEFAULT: 'Command can only be used in SFW channels'

follow_wrapped

Whether to also add this check to any other command objects this command wraps in a decorator call chain.

TYPE: bool DEFAULT: False

halt_execution

Whether this check should raise tanjun.HaltExecution to end the execution search when it fails instead of returning False.

This takes priority over error_message.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
tanjun.abc.ExecutableCommand

The command this check was added to.