Checks API Reference#

class lightbulb.checks.Check(p_callback: _CallbackT, s_callback: t.Optional[_CallbackT] = None, m_callback: t.Optional[_CallbackT] = None, u_callback: t.Optional[_CallbackT] = None, add_hook: t.Optional[t.Callable[[t.Union[plugins.Plugin, app.BotApp, commands.base.CommandLike]], t.Union[plugins.Plugin, app.BotApp, commands.base.CommandLike]]] = None)[source]#

Class representing a check. Check functions can be synchronous or asynchronous functions which take a single argument, which will be the context that the command is being invoked under, and return a boolean or raise a errors.CheckFailure indicating whether the check passed or failed.

Parameters:

  • p_callback (CallbackT) – Check function to use for prefix commands.

  • s_callback (Optional[CallbackT]) – Check function to use for slash commands.

  • m_callback (Optional[CallbackT]) – Check function to use for message commands.

  • u_callback (Optional[CallbackT]) – Check function to use for user commands.

  • add_hook (Optional[Callable[[T], T]]) – Function called when the check is added to an object.

lightbulb.checks.bot_has_channel_permissions(perm1: Permissions, *perms: Permissions) → Check[source]#

Prevents the command from being used if the bot is missing any of the required channel permissions (permissions granted a permission overwrite).

Parameters:

  • perm1 (hikari.Permissions) – Permission to check for.

  • *perms (hikari.Permissions) – Additional permissions to check for.

Note

This check will also prevent commands from being used in DMs, as you cannot have permissions in a DM channel.

Warning

This check is unavailable if your application is stateless and/or missing the intent hikari.Intents.GUILDS and will always raise an error on command invocation if either of these conditions are not met.

lightbulb.checks.bot_has_guild_permissions(perm1: Permissions, *perms: Permissions) → Check[source]#

Prevents the command from being used if the bot is missing any of the required permissions (this takes into account permissions granted by both roles and permission overwrites).

Parameters:

  • perm1 (hikari.Permissions) – Permission to check for.

  • *perms (hikari.Permissions) – Additional permissions to check for.

Note

This check will also prevent commands from being used in DMs, as you cannot have permissions in a DM channel.

Warning

This check is unavailable if your application is stateless and/or missing the intent hikari.Intents.GUILDS and will always raise an error on command invocation if either of these conditions are not met.

lightbulb.checks.bot_has_role_permissions(perm1: Permissions, *perms: Permissions) → Check[source]#

Prevents the command from being used if the bot is missing any of the required role permissions.

Parameters:

  • perm1 (hikari.Permissions) – Permission to check for.

  • *perms (hikari.Permissions) – Additional permissions to check for.

Note

This check will also prevent commands from being used in DMs, as you cannot have permissions in a DM channel.

Warning

This check is unavailable if your application is stateless and/or missing the intent hikari.Intents.GUILDS and will always raise an error on command invocation if either of these conditions are not met.

lightbulb.checks.has_attachments(*extensions: str) → Check[source]#

Prevents the command from being used if the invocation message does not include any attachments.

Parameters:

*extensions (str) – If specified, attachments with different file extensions will cause the check to fail.

Note

If extensions is specified then all attachments must conform to the restriction.

lightbulb.checks.has_channel_permissions(perm1: Permissions, *perms: Permissions) → Check[source]#

Prevents the command from being used by a member missing any of the required channel permissions (permissions granted by a permission overwrite).

Parameters:

  • perm1 (hikari.Permissions) – Permission to check for.

  • *perms (hikari.Permissions) – Additional permissions to check for.

Note

This check will also prevent commands from being used in DMs, as you cannot have permissions in a DM channel.

Warning

This check is unavailable if your application is stateless and/or missing the intent hikari.Intents.GUILDS and will always raise an error on command invocation if either of these conditions are not met.

lightbulb.checks.has_guild_permissions(perm1: Permissions, *perms: Permissions) → Check[source]#

Prevents the command from being used by a member missing any of the required permissions (this takes into account permissions granted by both roles and permission overwrites).

Parameters:

  • perm1 (hikari.Permissions) – Permission to check for.

  • *perms (hikari.Permissions) – Additional permissions to check for.

Note

This check will also prevent commands from being used in DMs, as you cannot have permissions in a DM channel.

Warning

This check is unavailable if your application is stateless and/or missing the intent hikari.Intents.GUILDS and will always raise an error on command invocation if either of these conditions are not met.

lightbulb.checks.has_role_permissions(perm1: Permissions, *perms: Permissions) → Check[source]#

Prevents the command from being used by a member missing any of the required role permissions.

Parameters:

  • perm1 (hikari.Permissions) – Permission to check for.

  • *perms (hikari.Permissions) – Additional permissions to check for.

Note

This check will also prevent commands from being used in DMs, as you cannot have permissions in a DM channel.

Warning

This check is unavailable if your application is stateless and/or missing the intent hikari.Intents.GUILDS and will always raise an error on command invocation if either of these conditions are not met.

lightbulb.checks.has_roles(role1: int, *roles: int, mode: ~typing.Callable[[~typing.Sequence[bool]], bool] = <built-in function all>) → Check[source]#

Prevents a command from being used by anyone missing roles according to the given mode. This check supports slash commands.

Parameters:

  • role1 (int) – Role ID to check for.

  • *roles (int) – Additional role IDs to check for.

Keyword Arguments:

mode (all or any) – The mode to check roles using. If all, all role IDs passed will be required. If any, only one of the role IDs will be required. Defaults to all.

Note

This check will also prevent commands from being used in DMs, as you cannot have roles in a DM channel.

lightbulb.checks.bot_only = Check(bot_only)#

Prevents a command from being used by anyone other than a bot.

lightbulb.checks.dm_only = Check(dm_only)#

Prevents a command from being used in a guild.

lightbulb.checks.guild_only = Check(guild_only)#

Prevents a command from being used in direct messages.

lightbulb.checks.human_only = Check(human_only)#

Prevents a command from being used by anyone other than a human.

lightbulb.checks.nsfw_channel_only = Check(nsfw_channel_only)#

Prevents a command from being used in any channel other than one marked as NSFW.

Deprecated since version 2.3.1: Use the nsfw kwarg in the command decorator instead. This will be removed in version 2.4.0.

lightbulb.checks.owner_only = Check(owner_only)#

Prevents a command from being used by anyone other than the owner of the application.

lightbulb.checks.webhook_only = Check(webhook_only)#

Prevents a command from being used by anyone other than a webhook.

Exclusive Checks#

New in version 2.0.1.

Check objects support the bitwise or (|) operator for the creation of exclusive checks. This allows you to add a check to the command which will pass if any one of the provided checks pass instead of requiring all of the checks to pass.

To create an exclusive check, use the bitwise or operator on two or more check objects:

import lightbulb

@lightbulb.add_checks(lightbulb.guild_only | lightbulb.owner_only)
@lightbulb.command(...)
@lightbulb.implements(...)
async def foo(...):
    ...

The above command is restricted to being used only in guilds, unless the invoker of the command is also the owner of the bot, in which case the owner would be allowed to use the command in DMs.