Skip to content

tanjun.checks#

A collection of common standard checks designed for Tanjun commands.

AuthorPermissionCheck #

Bases: _Check

Standard author permission check callback.

This is registered by 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.

Parameters:

  • permissions (Permissions | int) –

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

  • error (Callable[[Permissions], Exception] | None, default: None ) –

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

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None, default: "You don't have the permissions required to use this command" ) –

    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 "tanjun.AuthorPermissionCheck" for global overrides.

  • halt_execution (bool, default: False ) –

    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.

DmCheck #

Bases: _Check

Standard DM check callback registered by 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.

Parameters:

  • error (Callable[[], Exception] | None, default: None ) –

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None, default: 'Command can only be used in DMs' ) –

    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 "tanjun.DmCheck" for global overrides.

  • halt_execution (bool, default: False ) –

    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.

GuildCheck #

Bases: _Check

Standard guild check callback registered by 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.

Parameters:

  • error (Callable[[], Exception] | None, default: None ) –

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None, default: 'Command can only be used in guild channels' ) –

    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 "tanjun.GuildCheck" for global overrides.

  • halt_execution (bool, default: False ) –

    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.

NsfwCheck #

Bases: _Check

Standard NSFW check callback registered by 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.

Parameters:

  • error (Callable[[], Exception] | None, default: None ) –

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None, default: 'Command can only be used in NSFW channels' ) –

    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 "tanjun.NsfwCheck" for global overrides.

  • halt_execution (bool, default: False ) –

    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.

OwnPermissionCheck #

Bases: _Check

Standard own permission check callback.

This is registered by 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.

Parameters:

  • permissions (Permissions | int) –

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

  • error (Callable[[Permissions], Exception] | None, default: None ) –

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

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None, default: "Bot doesn't have the permissions required to run this command" ) –

    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 "tanjun.OwnPermissionCheck" for global overrides.

  • halt_execution (bool, default: False ) –

    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.

OwnerCheck #

Bases: _Check

Standard owner check callback registered by 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.

Parameters:

  • error (Callable[[], Exception] | None, default: None ) –

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None, default: 'Only bot owners can use this command' ) –

    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 "tanjun.OwnerCheck" for global overrides.

  • halt_execution (bool, default: False ) –

    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.

SfwCheck #

Bases: _Check

Standard SFW check callback registered by 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.

Parameters:

  • error (Callable[[], Exception] | None, default: None ) –

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None, default: 'Command can only be used in SFW channels' ) –

    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 "tanjun.SfwCheck" for global overrides.

  • halt_execution (bool, default: False ) –

    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.

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.

Parameters:

  • check (CheckSig[_ContextT]) –

    The first check callback to combine.

  • *checks (CheckSig[_ContextT], default: () ) –

    Additional check callbacks to combine.

Returns:

  • Callable[[Context], Coroutine[Any, 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.

Parameters:

  • check (CheckSig[_ContextT]) –

    The first check callback to combine.

  • *checks (CheckSig[_ContextT], default: () ) –

    Additional check callbacks to combine.

  • error (Callable[[], Exception] | None, default: None ) –

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None) –

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

    This supports localisation and uses the check name "tanjun.any_check" for global overrides.

  • halt_execution (bool, default: False ) –

    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.

  • suppress (tuple[type[Exception], ...], default: (CommandError, HaltExecution) ) –

    Tuple of the exceptions to suppress when a check fails.

Returns:

  • Callable[[ExecutableCommand], ExecutableCommand] –

    A decorator which adds the generated check to a command.

with_all_checks #

with_all_checks(check: tanjun.AnyCheckSig, /, *checks: tanjun.AnyCheckSig, follow_wrapped: bool = False) -> collections.Callable[[_CommandT], _CommandT]

with_all_checks(check: tanjun.CheckSig[tanjun.MenuContext], /, *checks: tanjun.CheckSig[tanjun.MenuContext], follow_wrapped: bool = False) -> collections.Callable[[_MenuCommandT], _MenuCommandT]

with_all_checks(check: tanjun.CheckSig[tanjun.MessageContext], /, *checks: tanjun.CheckSig[tanjun.MessageContext], follow_wrapped: bool = False) -> collections.Callable[[_MessageCommandT], _MessageCommandT]

with_all_checks(check: tanjun.CheckSig[tanjun.SlashContext], /, *checks: tanjun.CheckSig[tanjun.SlashContext], follow_wrapped: bool = False) -> collections.Callable[[_SlashCommandT], _SlashCommandT]

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.

Parameters:

  • check (CheckSig[Any]) –

    The first check callback to combine.

  • *checks (CheckSig[Any], default: () ) –

    Additional check callbacks to combine.

  • follow_wrapped (bool, default: False ) –

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

Returns:

  • Callable[[Context], Coroutine[Any, Any, bool]] –

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

with_any_checks #

with_any_checks(check: tanjun.AnyCheckSig, /, *checks: tanjun.AnyCheckSig, error: collections.Callable[[], Exception] | None = None, error_message: str | collections.Mapping[str, str] | None, follow_wrapped: bool = False, halt_execution: bool = False, suppress: tuple[type[Exception], ...] = (errors.CommandError, errors.HaltExecution)) -> collections.Callable[[_CommandT], _CommandT]

with_any_checks(check: tanjun.CheckSig[tanjun.MenuContext], /, *checks: tanjun.CheckSig[tanjun.MenuContext], error: collections.Callable[[], Exception] | None = None, error_message: str | collections.Mapping[str, str] | None, follow_wrapped: bool = False, halt_execution: bool = False, suppress: tuple[type[Exception], ...] = (errors.CommandError, errors.HaltExecution)) -> collections.Callable[[_MenuCommandT], _MenuCommandT]

with_any_checks(check: tanjun.CheckSig[tanjun.MessageContext], /, *checks: tanjun.CheckSig[tanjun.MessageContext], error: collections.Callable[[], Exception] | None = None, error_message: str | collections.Mapping[str, str] | None, follow_wrapped: bool = False, halt_execution: bool = False, suppress: tuple[type[Exception], ...] = (errors.CommandError, errors.HaltExecution)) -> collections.Callable[[_MessageCommandT], _MessageCommandT]

with_any_checks(check: tanjun.CheckSig[tanjun.SlashContext], /, *checks: tanjun.CheckSig[tanjun.SlashContext], error: collections.Callable[[], Exception] | None = None, error_message: str | collections.Mapping[str, str] | None, follow_wrapped: bool = False, halt_execution: bool = False, suppress: tuple[type[Exception], ...] = (errors.CommandError, errors.HaltExecution)) -> collections.Callable[[_SlashCommandT], _SlashCommandT]

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.

Parameters:

  • check (CheckSig[Any]) –

    The first check callback to combine.

  • *checks (CheckSig[Any], default: () ) –

    Additional check callbacks to combine.

  • error (Callable[[], Exception] | None, default: None ) –

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None) –

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

    This supports localisation and uses the check name "tanjun.any_check" for global overrides.

  • follow_wrapped (bool, default: False ) –

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

  • halt_execution (bool, default: False ) –

    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.

  • suppress (tuple[type[Exception], ...], default: (CommandError, HaltExecution) ) –

    Tuple of the exceptions to suppress when a check fails.

Returns:

  • Callable[[ExecutableCommand], 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)

Parameters:

  • permissions (Permissions | int) –

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

  • error (Callable[[Permissions], Exception] | None, default: None ) –

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

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None, default: "You don't have the permissions required to use this command" ) –

    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 "tanjun.AuthorPermissionCheck" for global overrides.

  • follow_wrapped (bool, default: False ) –

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

  • halt_execution (bool, default: False ) –

    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.

Returns:

  • Callable[[ExecutableCommand], ExecutableCommand] –

    A command decorator callback which adds the check.

with_check #

with_check(check: tanjun.AnyCheckSig, /, *, follow_wrapped: bool = False) -> collections.Callable[[_CommandT], _CommandT]

with_check(check: tanjun.CheckSig[tanjun.MenuContext], /, *, follow_wrapped: bool = False) -> collections.Callable[[_MenuCommandT], _MenuCommandT]

with_check(check: tanjun.CheckSig[tanjun.MessageContext], /, *, follow_wrapped: bool = False) -> collections.Callable[[_MessageCommandT], _MessageCommandT]

with_check(check: tanjun.CheckSig[tanjun.SlashContext], /, *, follow_wrapped: bool = False) -> collections.Callable[[_SlashCommandT], _SlashCommandT]

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

Add a generic check to a command.

Parameters:

  • check (CheckSig[Any]) –

    The check to add to this command.

  • follow_wrapped (bool, default: False ) –

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

Returns:

  • Callable[[ExecutableCommand], ExecutableCommand] –

    A command decorator callback which adds the check.

with_dm_check #

with_dm_check(command: _CommandT) -> _CommandT

with_dm_check(*, error: collections.Callable[[], Exception] | None = None, error_message: str | collections.Mapping[str, str] | None = 'Command can only be used in DMs', follow_wrapped: bool = False, halt_execution: bool = False) -> collections.Callable[[_CommandT], _CommandT]

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.

Parameters:

  • command (ExecutableCommand | None, default: None ) –

    The command to add this check to.

  • error (Callable[[], Exception] | None, default: None ) –

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None, default: 'Command can only be used in DMs' ) –

    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 "tanjun.DmCheck" for global overrides.

  • follow_wrapped (bool, default: False ) –

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

  • halt_execution (bool, default: False ) –

    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.

Returns:

  • ExecutableCommand –

    The command this check was added to.

with_guild_check #

with_guild_check(command: _CommandT) -> _CommandT

with_guild_check(*, error: collections.Callable[[], Exception] | None = None, error_message: str | collections.Mapping[str, str] | None = 'Command can only be used in guild channels', follow_wrapped: bool = False, halt_execution: bool = False) -> collections.Callable[[_CommandT], _CommandT]

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.

Parameters:

  • command (ExecutableCommand | None, default: None ) –

    The command to add this check to.

  • error (Callable[[], Exception] | None, default: None ) –

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None, default: 'Command can only be used in guild channels' ) –

    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 "tanjun.GuildCheck" for global overrides.

  • follow_wrapped (bool, default: False ) –

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

  • halt_execution (bool, default: False ) –

    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.

Returns:

  • ExecutableCommand –

    The command this check was added to.

with_nsfw_check #

with_nsfw_check(command: _CommandT) -> _CommandT

with_nsfw_check(*, error: collections.Callable[[], Exception] | None = None, error_message: str | collections.Mapping[str, str] | None = 'Command can only be used in NSFW channels', follow_wrapped: bool = False, halt_execution: bool = False) -> collections.Callable[[_CommandT], _CommandT]

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.

Parameters:

  • command (ExecutableCommand | None, default: None ) –

    The command to add this check to.

  • error (Callable[[], Exception] | None, default: None ) –

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None, default: 'Command can only be used in NSFW channels' ) –

    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 "tanjun.NsfwCheck" for global overrides.

  • follow_wrapped (bool, default: False ) –

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

  • halt_execution (bool, default: False ) –

    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.

Returns:

  • 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)

Parameters:

  • permissions (Permissions | int) –

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

  • error (Callable[[Permissions], Exception] | None, default: None ) –

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

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None, default: "Bot doesn't have the permissions required to run this command" ) –

    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 "tanjun.OwnPermissionCheck" for global overrides.

  • follow_wrapped (bool, default: False ) –

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

  • halt_execution (bool, default: False ) –

    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.

Returns:

  • Callable[[ExecutableCommand], ExecutableCommand] –

    A command decorator callback which adds the check.

with_owner_check #

with_owner_check(command: _CommandT) -> _CommandT

with_owner_check(*, error: collections.Callable[[], Exception] | None = None, error_message: str | collections.Mapping[str, str] | None = 'Only bot owners can use this command', follow_wrapped: bool = False, halt_execution: bool = False) -> collections.Callable[[_CommandT], _CommandT]

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.

Parameters:

  • command (ExecutableCommand | None, default: None ) –

    The command to add this check to.

  • error (Callable[[], Exception] | None, default: None ) –

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None, default: 'Only bot owners can use this command' ) –

    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 "tanjun.OwnerCheck" for global overrides.

  • follow_wrapped (bool, default: False ) –

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

  • halt_execution (bool, default: False ) –

    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.

Returns:

  • ExecutableCommand –

    The command this check was added to.

with_sfw_check #

with_sfw_check(command: _CommandT) -> _CommandT

with_sfw_check(*, error: collections.Callable[[], Exception] | None = None, error_message: str | collections.Mapping[str, str] | None = 'Command can only be used in SFW channels', follow_wrapped: bool = False, halt_execution: bool = False) -> collections.Callable[[_CommandT], _CommandT]

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.

Parameters:

  • command (ExecutableCommand | None, default: None ) –

    The command to add this check to.

  • error (Callable[[], Exception] | None, default: None ) –

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

    This takes priority over error_message.

  • error_message (str | Mapping[str, str] | None, default: 'Command can only be used in SFW channels' ) –

    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 "tanjun.SfwCheck" for global overrides.

  • follow_wrapped (bool, default: False ) –

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

  • halt_execution (bool, default: False ) –

    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.

Returns:

  • ExecutableCommand –

    The command this check was added to.