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__ #
__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. |
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
TYPE:
|
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. This supports localisation and uses the check name
TYPE:
|
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
TYPE:
|
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__ #
__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
TYPE:
|
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. This supports localisation and uses the check name
TYPE:
|
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
TYPE:
|
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__ #
__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
TYPE:
|
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. This supports localisation and uses the check name
TYPE:
|
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
TYPE:
|
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__ #
__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
TYPE:
|
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. This supports localisation and uses the check name
TYPE:
|
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
TYPE:
|
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__ #
__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. |
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
TYPE:
|
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. This supports localisation and uses the check name
TYPE:
|
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
TYPE:
|
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__ #
__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
TYPE:
|
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. This supports localisation and uses the check name
TYPE:
|
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
TYPE:
|
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__ #
__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
TYPE:
|
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. This supports localisation and uses the check name
TYPE:
|
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
TYPE:
|
all_checks #
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. |
*checks |
Additional check callbacks to combine. |
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 #
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. |
*checks |
Additional check callbacks to combine. |
error |
Callback used to create a custom error to raise if the check fails. This takes priority over
TYPE:
|
error_message |
The error message to send in response as a command error if the check fails. This supports localisation and uses the check name
TYPE:
|
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
TYPE:
|
suppress |
Tuple of the exceptions to suppress when a check fails.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
collections.Callable[[tanjun.abc.ExecutableCommand], tanjun.abc.ExecutableCommand]
|
A decorator which adds the generated check to a command. |
with_all_checks #
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. |
*checks |
Additional check callbacks to combine. |
follow_wrapped |
Whether to also add this check to any other command objects this command wraps in a decorator call chain.
TYPE:
|
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 #
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. |
*checks |
Additional check callbacks to combine. |
error |
Callback used to create a custom error to raise if the check fails. This takes priority over
TYPE:
|
error_message |
The error message to send in response as a command error if the check fails. This supports localisation and uses the check name
TYPE:
|
follow_wrapped |
Whether to also add this check to any other command objects this command wraps in a decorator call chain.
TYPE:
|
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
TYPE:
|
suppress |
Tuple of the exceptions to suppress when a check fails.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
collections.Callable[[tanjun.abc.ExecutableCommand], tanjun.abc.ExecutableCommand]
|
A decorator which adds the generated check to a command. |
with_author_permission_check #
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. |
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
TYPE:
|
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. This supports localisation and uses the check name
TYPE:
|
follow_wrapped |
Whether to also add this check to any other command objects this command wraps in a decorator call chain.
TYPE:
|
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
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
collections.abc.Callable[[tanjun.abc.ExecutableCommand], tanjun.abc.ExecutableCommand]
|
A command decorator callback which adds the check. |
with_check #
with_check(check, /, *, follow_wrapped=False)
Add a generic check to a command.
PARAMETER | DESCRIPTION |
---|---|
check |
The check to add to this command. |
follow_wrapped |
Whether to also add this check to any other command objects this command wraps in a decorator call chain.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
collections.abc.Callable[[tanjun.abc.ExecutableCommand], tanjun.abc.ExecutableCommand]
|
A command decorator callback which adds the check. |
with_dm_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:
|
error |
Callback used to create a custom error to raise if the check fails. This takes priority over
TYPE:
|
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. This supports localisation and uses the check name
TYPE:
|
follow_wrapped |
Whether to also add this check to any other command objects this command wraps in a decorator call chain.
TYPE:
|
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
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
tanjun.abc.ExecutableCommand
|
The command this check was added to. |
with_guild_check #
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:
|
error |
Callback used to create a custom error to raise if the check fails. This takes priority over
TYPE:
|
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. This supports localisation and uses the check name
TYPE:
|
follow_wrapped |
Whether to also add this check to any other command objects this command wraps in a decorator call chain.
TYPE:
|
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
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
tanjun.abc.ExecutableCommanmd
|
The command this check was added to. |
with_nsfw_check #
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:
|
error |
Callback used to create a custom error to raise if the check fails. This takes priority over
TYPE:
|
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. This supports localisation and uses the check name
TYPE:
|
follow_wrapped |
Whether to also add this check to any other command objects this command wraps in a decorator call chain.
TYPE:
|
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
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
tanjun.abc.ExecutableCommand
|
The command this check was added to. |
with_own_permission_check #
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. |
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
TYPE:
|
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. This supports localisation and uses the check name
TYPE:
|
follow_wrapped |
Whether to also add this check to any other command objects this command wraps in a decorator call chain.
TYPE:
|
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
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
collections.abc.Callable[[tanjun.abc.ExecutableCommand], tanjun.abc.ExecutableCommand]
|
A command decorator callback which adds the check. |
with_owner_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:
|
error |
Callback used to create a custom error to raise if the check fails. This takes priority over
TYPE:
|
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. This supports localisation and uses the check name
TYPE:
|
follow_wrapped |
Whether to also add this check to any other command objects this command wraps in a decorator call chain.
TYPE:
|
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
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
tanjun.abc.ExecutableCommand
|
The command this check was added to. |
with_sfw_check #
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:
|
error |
Callback used to create a custom error to raise if the check fails. This takes priority over
TYPE:
|
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. This supports localisation and uses the check name
TYPE:
|
follow_wrapped |
Whether to also add this check to any other command objects this command wraps in a decorator call chain.
TYPE:
|
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
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
tanjun.abc.ExecutableCommand
|
The command this check was added to. |