checks

exception ContextCheckFailure(redirect_channel)

Bases: CheckFailure

Raised when a context-specific check fails.

__init__(redirect_channel)

exception InWhitelistCheckFailure(redirect_channel)

Bases: ContextCheckFailure

Raised when the in_whitelist check fails.

cooldown_with_role_bypass(rate, per, type=('default', 0), *, bypass_roles)

Decorate a command to have a cooldown, which can be bypassed by users with specified roles.

Note: This replaces the Command.before_invoke callback, which might introduce problems in the future.

Parameters:

• rate (int) – Number of times a command can be used before triggering a cooldown.

• per (float) – The duration (in seconds) for how long the cooldown lasts.

• type (discord.ext.commands.BucketType) – The type of cooldown (per user, per channel, per guild, etc.).

• bypass_roles (Iterable[int]) – An iterable of role IDs that bypass the cooldown.

Returns:

A decorator that adds the described cooldown behavior to the command.

Return type:

Callable

Raises:

TypeError – If the decorator is not applied to an instance of Command.

async has_any_role_check(ctx, *roles)

Verify if the context’s author has any of the specified roles.

This check will always fail if the context is a DM, since DMs don’t have roles.

Parameters:

• ctx (discord.ext.commands.Context) – The context where the command is being invoked.

• roles (Union[str, int], ...) – A collection of role IDs.

Returns:

True if the context’s author has at least one of the specified roles; False otherwise.

Return type:

bool

async has_no_roles_check(ctx, *roles)

Verify if the context’s author doesn’t have any of the specified roles.

This check will always fail if the context is a DM, since DMs don’t have roles.

Parameters:

• ctx (discord.ext.commands.Context) – The context where the command is being invoked.

• roles (Union[str, int], ...) – A collection of role IDs.

Returns:

True if the context’s author doesn’t have any of the specified roles; False otherwise.

Return type:

bool

in_whitelist_check(ctx, redirect, channels=(), categories=(), roles=(), fail_silently=False)

Check if a command was issued in a context that is whitelisted by channel, category, or roles.

Parameters:

• ctx (discord.ext.commands.Context) – The context in which the command is being invoked.

• redirect (int | None) – The channel ID to redirect the user to, if any.

• channels (Container[int]) – Whitelisted channel IDs. Defaults to ().

• categories (Container[int]) – Whitelisted category IDs. Defaults to ().

• roles (Container[int]) – Whitelisted role IDs. Defaults to ().

• fail_silently (bool) – Whether to fail silently without raising an exception. Defaults to False.

Returns:

True if the command is used in a whitelisted context; False otherwise.

Return type:

bool

Raises:

InWhitelistCheckFailure – If the context is not whitelisted and fail_silently is False.