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. 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. This supports localisation and uses the check name `"tanjun.AuthorPermissionCheck"` for global overrides. TYPE: `typing.Union[str, collections.Mapping[str, str], None]` 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 #

__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.

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

TYPE: typing.Union[str, collections.Mapping[str, str], None] 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 #

__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.

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

TYPE: typing.Union[str, collections.Mapping[str, str], None] 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 #

__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.

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

TYPE: typing.Union[str, collections.Mapping[str, str], None] 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 #

__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. This supports localisation and uses the check name `"tanjun.OwnPermissionCheck"` for global overrides. TYPE: `typing.Union[str, collections.Mapping[str, str], None]` 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 #

__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.

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

TYPE: typing.Union[str, collections.Mapping[str, str], None] 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 #

__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.

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

TYPE: typing.Union[str, collections.Mapping[str, str], None] 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 #

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[_ContextT]

*checks

Additional check callbacks to combine.

TYPE: tanjun.CheckSig[_ContextT] 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 #

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[_ContextT]`
`*checks`	Additional check callbacks to combine. TYPE: `tanjun.CheckSig[_ContextT]` 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. This supports localisation and uses the check name `"tanjun.any_check"` for global overrides. TYPE: `typing.Union[str, collections.Mapping[str, str], None]`
`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 #

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[typing.Any]

*checks

Additional check callbacks to combine.

TYPE: tanjun.CheckSig[typing.Any] 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 #

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[typing.Any]`
`*checks`	Additional check callbacks to combine. TYPE: `tanjun.CheckSig[typing.Any]` 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. This supports localisation and uses the check name `"tanjun.any_check"` for global overrides. TYPE: `typing.Union[str, collections.Mapping[str, str], None]`
`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 #

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. This supports localisation and uses the check name `"tanjun.AuthorPermissionCheck"` for global overrides. TYPE: `typing.Union[str, collections.Mapping[str, str], None]` 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 #

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[typing.Any]

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 #

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. This supports localisation and uses the check name `"tanjun.DmCheck"` for global overrides. TYPE: `typing.Union[str, collections.Mapping[str, str], None]` 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 #

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. This supports localisation and uses the check name `"tanjun.GuildCheck"` for global overrides. TYPE: `typing.Union[str, collections.Mapping[str, str], None]` 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 #

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. This supports localisation and uses the check name `"tanjun.NsfwCheck"` for global overrides. TYPE: `typing.Union[str, collections.Mapping[str, str], None]` 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 #

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. This supports localisation and uses the check name `"tanjun.OwnPermissionCheck"` for global overrides. TYPE: `typing.Union[str, collections.Mapping[str, str], None]` 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 #

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. This supports localisation and uses the check name `"tanjun.OwnerCheck"` for global overrides. TYPE: `typing.Union[str, collections.Mapping[str, str], None]` 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 #

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. This supports localisation and uses the check name `"tanjun.SfwCheck"` for global overrides. TYPE: `typing.Union[str, collections.Mapping[str, str], None]` 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.

tanjun.checks#

AuthorPermissionCheck #

__init__ #

DmCheck #

__init__ #

GuildCheck #

__init__ #

NsfwCheck #

__init__ #

OwnPermissionCheck #

__init__ #

OwnerCheck #

__init__ #

SfwCheck #

__init__ #

all_checks #

any_checks #

with_all_checks #

with_any_checks #

with_author_permission_check #

with_check #

with_dm_check #

with_guild_check #

with_nsfw_check #

with_own_permission_check #

with_owner_check #

with_sfw_check #

init #

init #

init #

init #

init #

init #

init #