Command Checks

Checks ready to use with discord.ext.commands

dpytools.checks.admin_or_roles(*roles: Union[int, str]) → discord.ext.commands.core.check

Returns True under these conditions:

  • The command is run in a guild

  • ctx.author has admin permissions OR has any role in :param roles:

Parameters

roles (Union[int,str]) – Any number of strings or integers corresponding to the desired roles

Raises

  • discord.ext.commands.NoPrivateMessage – If ran from DM

  • discord.ext.commands.MissingPermissions – If user doesn’t have correct roles or admin permissions

dpytools.checks.any_checks(f: discord.ext.commands.core.Command)

Decorator to handle optional checks

This Decorator will make any @checks placed below itself to be called with a logical OR. This means that if one or more return True, the command will be able to run

Note

When using this decorator remember that you don’t need to call it:

# correct
@any_checks

# incorrect
@any_checks()

Example

from dpytools.checks import any_checks

@commands.guild_only()       # This command must be called inside a server
@any_checks                  # Place the decorator above the checks you with to compare using "OR"
@commands.is_owner()         # The command will run if ctx.author is the owner of the bot
@commands.has_role('Admin')  # __OR__ if ctx.author has the role "Admin"
@bot.command()               # this decorator transforms this function in a command
async def test(ct):
    await ctx.send('The command works')

Warning

This decorator makes it impossible to know which optional checks succeded or failed.

Note

The decorator will raise CheckFailure if all checks below itself fail

Raises

commands.CheckFailure – If all checks below itself fail.

dpytools.checks.any_of_permissions(**permissions) → discord.ext.commands.core.check

Returns True under the following conditions:

  • ctx.author matches any permission passed in the decorator

Parameters

permissions – appropriate permission flags. Keys are the permissions names and values the bool setting

Example

The command below will send success only if ctx.author has any or more of administrator, manage_guild or manage_messages permissions:

@bot.command()
@any_of_permissions(administrator=True, manage_guild=True, manage_messages=True)
async def test(ctx):
    await ctx.send('success')
Raises

  • discord.ext.commands.NoPrivateMessage – If ran outside a guild

  • discord.ext.commands.MissingPermissions – If ctx.author does not have any of the passed permissions

dpytools.checks.between_datetimes(from_dt: datetime.datetime, to_dt: datetime.datetime) → discord.ext.commands.core.check
Returns True under the following conditions:

  • ctx.message.created_at is in the interval from :param from_dt: to :param to_dt:

Note

Parameters must be of type datetime

Note

If parameters are timezone aware they must share the same timezone. In this case The check will convert ctx.message.created_at to the timezone of the parameters

Parameters

  • from_dt (datetime) –

  • to_dt (datetime) –

dpytools.checks.between_times(from_time: datetime.time, to_time: datetime.time) → discord.ext.commands.core.check
Returns True under the following conditions:

  • ctx.message.created_at.time() is in the interval from :param from_time: to :param to_time:

Note

Parameters must be datetime.time instances

Parameters

  • from_time (datetime.time) –

  • to_time (datetime.time) –

dpytools.checks.dm_from_this_guild(guild_id: int, delete: bool = False) → discord.ext.commands.core.check

Returns True under the following conditions:

  • param guild_id

    is found within the ctx.bot.guilds.

  • ctx.guild is None

For this check to work the guilds and members intents must be enabled.

Parameters

  • guild_id (int) – id of the guild the author of the context must be a part of

  • delete (bool (default: False)) – If True, it will try to delete ctx.message. This will only happen if the message is called from the specificed guild_id, if the command is called from another guild the check will just return False.

Raises

  • discord.ext.commands.PrivateMessageOnly – If called from a guild

  • NotMemberOfCorrectGuild – If not a member of the specified guild

dpytools.checks.in_these_channels(*channels: int) → discord.ext.commands.core.check
Returns True under the following conditions:

  • ctx.channel.id is found within :param channels:

Warning

If no channels are specified this command will be effectively unusable

Parameters

channels (int) – One or more channel ids where this command can run

dpytools.checks.is_guild_owner() → discord.ext.commands.core.check
Returns True under the following conditions:

  • ctx.author is the owner of the guild where this command was called from

dpytools.checks.only_these_users(*users: int) → discord.ext.commands.core.check
Returns True under the following conditions:

  • ctx.author is authorized by this check

Warning

If no users are specified this command will be effectively unusable.

Parameters

users (int) – the ids of the user’s that are authorized to use this command

dpytools.checks.only_this_guild(guild_id: int) → discord.ext.commands.core.check

Returns True under the following conditions:

  • ctx.guild has same id as :param guild_id:

Raises

  • discord.ext.commands.NoPrivateMessage – If ran outside a guild

  • IncorrectGuild – If id doesn’t check

dpytools.checks.this_or_higher_role(role: Union[str, int]) → discord.ext.commands.core.check
Returns True under the following conditions:

  • ctx.author has the specified role or another hierarchically higher

Parameters

role (Union[str, int]) – The role as its name (case sensitive) or id (int).

Raises

discord.ext.commands.NoPrivateMessage – If called outside a guild