checks#

exception ContextCheckFailure(redirect_channel)[source]#

Bases: CheckFailure

Raised when a context-specific check fails.

__init__(redirect_channel)[source]#
exception InWhitelistCheckFailure(redirect_channel)[source]#

Bases: ContextCheckFailure

Raised when the in_whitelist check fails.

cooldown_with_role_bypass(rate, per, type=('default', 0), *, bypass_roles)[source]#

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)[source]#

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:
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)[source]#

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:
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)[source]#

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.