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.