Commands API Reference#

Base#

class lightbulb.commands.base.ApplicationCommand(app: app_.BotApp, initialiser: CommandLike)[source]#

Abstract base class for all application command types.

abstract as_create_kwargs() → Dict[str, Any][source]#

Converts this class into a dictionary of kwargs required by create_application_command.

Returns:: Kwargs required in order to create the command.
Return type:: Dict[str, Any]

async create(guild: int | None = None) → PartialCommand[source]#

Creates the command in the guild with the given ID, or globally if no guild ID was provided.

Parameters:: guild (Optional[int]) – ID of the guild to create the command in, or None if to create globally.
Returns:: Created hikari Command object.
Return type:: PartialCommand

async delete(guild: int | None) → None[source]#

Deletes the command in the guild with the given ID, or globally if no guild ID was provided.

Parameters:: guild (Optional[int]) – ID of the guild to delete the command in, or None if to delete globally.
Returns:: None

property guilds: Sequence[int]#: The guilds that this command is available in.

instances: t.Dict[t.Union[int, None], hikari.PartialCommand]#: Mapping of guild ID to created hikari PartialCommand objects for this command.

property signature: str#: The command’s text signature.

class lightbulb.commands.base.Command(app: app_.BotApp, initialiser: CommandLike)[source]#

Abstract base class for all command types.

Parameters:

app (BotApp) – The BotApp instance that the command is registered to.
initialiser (CommandLike) – The CommandLike object to create the command from.

async evaluate_checks(context: context_.base.Context) → bool[source]#: Evaluate the command’s checks under the given context. This method will either return True if all the checks passed, or it will raise CheckFailure.

async evaluate_cooldowns(context: context_.base.Context) → None[source]#: Evaluate the command’s cooldown under the given context. This method will either return None if the command is not on cooldown or raise errors.CommandIsOnCooldown.

get_help(context: context_.base.Context) → str[source]#

Get the help text for the command under the given context. This method calls the help getter provided by the set_help decorator. An empty string will be returned if no help getter function was set.

Parameters:: context (Context) – Context to get the help text under.
Returns:: Command’s help text.
Return type:: str

async invoke(context: context_.base.Context, **kwargs: t.Any) → None[source]#: Invokes the command under the given context. All checks, cooldowns and concurrency limits will be processed prior to invocation.

property aliases: Sequence[str]#: The aliases for the command. This value means nothing for application commands.

app: app_.BotApp#: The BotApp instance the command is registered to.

property app_command_bypass_author_permission_checks: bool#: Whether invocations of this command as an application command will bypass author permission checks.

property app_command_default_member_permissions: Permissions | None#: The default member permissions for this command, as an application command.

property app_command_dm_enabled: bool#: Whether this command, as an application command, is enabled in DMs.

property auto_defer: bool#: Whether to automatically defer the response when the command is invoked.

property bot: app_.BotApp#: Alias for app.

property callback: CommandCallbackT#: The callback function for the command.

property check_exempt: t.Callable[[context_.base.Context], t.Union[bool, t.Coroutine[t.Any, t.Any, bool]]]#: Check exempt predicate to use for the command.

property checks: t.Sequence[t.Union[checks.Check, checks._ExclusiveCheck]]#: The checks for the command.

property cooldown_manager: t.Optional[cooldowns.CooldownManager]#: The cooldown manager instance to use for the command.

property default_ephemeral: bool#: Whether to send responses from this command as ephemeral messages by default.

property description: str#: The description of the command.

property description_localizations: Mapping[Locale | str, str]#: A mapping of locale to description localizations for this command.

New in version 2.3.0.

property error_handler: t.Optional[t.Callable[[events.CommandErrorEvent], t.Coroutine[t.Any, t.Any, t.Optional[bool]]]]#: The error handler function for the command.

property hidden: bool#: Whether the command should be hidden from the help command.

property inherit_checks: bool#: Whether the command should inherit checks from the parent group.

property is_subcommand: bool#: Boolean representing whether this object is a subcommand.

property max_concurrency: t.Optional[t.Tuple[int, t.Type[buckets.Bucket]]]#: The max concurrency rule for the command.

property name: str#: The name of the command.

property name_localizations: Mapping[Locale | str, str]#: A mapping of locale to name localizations for this command.

New in version 2.3.0.

property nsfw: bool#

Whether the command should only be enabled in NSFW channels.

For prefix commands, this will add an NSFW-channel only check to the command automatically. For slash commands, this will behave as specified in the Discord documentation.

New in version 2.3.1.

property options: MutableMapping[str, OptionLike]#: The options for the command.

parent: t.Optional[Command]#: The parent for the command.

property parser: t.Optional[t.Type[parser_.BaseParser]]#: The argument parser to use for prefix commands.

property pass_options: bool#: Whether the command will have its options passed as keyword arguments when invoked.

property plugin: t.Optional[plugins.Plugin]#: The plugin that the command belongs to.

property qualname: str#: The qualified name for the command.

abstract property signature: str#: The command’s text signature.

class lightbulb.commands.base.CommandLike(callback: CommandCallbackT, name: str, description: str, options: t.MutableMapping[str, OptionLike] = _Nothing.NOTHING, checks: t.Sequence[t.Union[checks.Check, checks._ExclusiveCheck]] = _Nothing.NOTHING, error_handler: t.Optional[t.Callable[[events.CommandErrorEvent], t.Coroutine[t.Any, t.Any, t.Optional[bool]]]] = None, aliases: t.Sequence[str] = _Nothing.NOTHING, guilds: hikari.UndefinedOr[t.Sequence[int]] = UNDEFINED, subcommands: t.List[CommandLike] = _Nothing.NOTHING, parser: t.Optional[t.Type[parser_.BaseParser]] = None, cooldown_manager: t.Optional[cooldowns.CooldownManager] = None, help_getter: t.Optional[t.Callable[[Command, context_.base.Context], str]] = None, auto_defer: bool = False, ephemeral: bool = False, check_exempt: t.Optional[t.Callable[[context_.base.Context], t.Union[bool, t.Coroutine[t.Any, t.Any, bool]]]] = None, hidden: bool = False, inherit_checks: bool = False, pass_options: bool = False, max_concurrency: t.Optional[t.Tuple[int, t.Type[buckets.Bucket]]] = None, app_command_default_member_permissions: t.Optional[hikari.Permissions] = None, app_command_dm_enabled: bool = True, app_command_bypass_author_permission_checks: bool = False, name_localizations: t.Mapping[t.Union[hikari.Locale, str], str] = _Nothing.NOTHING, description_localizations: t.Mapping[t.Union[hikari.Locale, str], str] = _Nothing.NOTHING, nsfw: bool = False)[source]#

Generic dataclass representing a command. This can be converted into any command object.

autocomplete(opt1: str, *opts: str) → Callable[[AutocompleteCallbackT], AutocompleteCallbackT][source]#

Second order decorator that registers a function as an autocomplete callback for this command.

The autocomplete callback must be an asynchronous function that takes exactly two arguments: option (an instance of hikari.interactions.command_interactions.AutocompleteInteractionOption) which is the option being autocompleted, and interaction (an instance of hikari.interactions.command_interactions.AutocompleteInteraction) which is the interaction that triggered the autocomplete.

Autocomplete can only be enabled for options with type str, int, or float.

The callback should return one of the following: a single item of the option type, a sequence of items of the option type, a single hikari.commands.CommandChoice, or a sequence of hikari.commands.CommandChoice.

Parameters:

opt1 (str) – Option that this callback will do autocomplete for.
*opts (str) – Additional options that this callback will do autocomplete for.

Example

@lightbulb.option("foo", "bar", autocomplete=True)
@lightbulb.command(...)
@lightbulb.implements(lightbulb.SlashCommand)
async def foo(ctx: lightbulb.Context) -> None
    ...

@foo.autocomplete("foo")  # Name of the option you want to autocomplete
async def foo_autocomplete(
    opt: hikari.AutocompleteInteractionOption, inter: hikari.AutocompleteInteraction
) -> Union[str, Sequence[str], hikari.api.AutocompleteChoiceBuilder, Sequence[hikari.api.AutocompleteChoiceBuilder]]:
    ...

child() → Callable[[CommandLike], CommandLike][source]#

child(cmd_like: CommandLike) → CommandLike

Registers a CommandLike object as a child to this command. This can be used as a first or second order decorator, or called manually with the CommandLike instance to add as a child.

Example

@lightbulb.command(...)
@lightbulb.implements(...)
async def foo(ctx: lightbulb.Context) -> None:
    ...

# Valid
@foo.child
@lightbulb.command(...)
@lightbulb.implements(...)
async def foo_child(event: lightbulb.Context) -> None:
    ...

# Also valid
@foo.child()
@lightbulb.command(...)
@lightbulb.implements(...)
async def foo_child(event: lightbulb.Context) -> None:
    ...

# Also valid
@lightbulb.command(...)
@lightbulb.implements(...)
async def foo_child(event: lightbulb.Context) -> None:
    ...

foo.child(foo_child)

set_error_handler() → Callable[[ErrorHandlerCallbackT], ErrorHandlerCallbackT][source]#

set_error_handler(func: ErrorHandlerCallbackT) → ErrorHandlerCallbackT

Registers a coroutine function as an error handler for this command. This can be used as a first or second order decorator, or called manually with the function to register.

Example

@lightbulb.command(...)
@lightbulb.implements(...)
async def foo(ctx: lightbulb.Context) -> None:
    ...

# Valid
@foo.set_error_handler
async def foo_error_handler(event: lightbulb.CommandErrorEvent) -> bool:
    ...

# Also valid
@foo.set_error_handler()
async def foo_error_handler(event: lightbulb.CommandErrorEvent) -> bool:
    ...

# Also valid
async def foo_error_handler(event: lightbulb.CommandErrorEvent) -> bool:
    ...

foo.set_error_handler(foo_error_handler)

aliases: t.Sequence[str]#: The aliases for the command. This only affects prefix commands.

app_command_bypass_author_permission_checks: bool#: Whether invocations of this command will bypass author permission checks, if an application command.

New in version 2.2.3.

app_command_default_member_permissions: t.Optional[hikari.Permissions]#: The default member permissions for this command, if an application command.

New in version 2.2.3.

app_command_dm_enabled: bool#: Whether this command will be enabled in DMs, if an application command.

New in version 2.2.3.

auto_defer: bool#: Whether or not to automatically defer the response when the command is invoked.

callback: CommandCallbackT#: The callback function for the command.

check_exempt: t.Optional[t.Callable[[context_.base.Context], t.Union[bool, t.Coroutine[t.Any, t.Any, bool]]]]#: Check exempt predicate to use for the command.

checks: t.Sequence[t.Union[checks.Check, checks._ExclusiveCheck]]#: The checks for the command.

cooldown_manager: t.Optional[cooldowns.CooldownManager]#: The cooldown manager for the command.

description: str#: The description of the command.

description_localizations: t.Mapping[t.Union[hikari.Locale, str], str]#: A mapping of locale to description localizations for this command

New in version 2.3.0.

ephemeral: bool#: Whether or not to send responses from this command as ephemeral messages by default.

error_handler: t.Optional[t.Callable[[events.CommandErrorEvent], t.Coroutine[t.Any, t.Any, t.Optional[bool]]]]#: The error handler for the command.

guilds: hikari.UndefinedOr[t.Sequence[int]]#: The guilds for the command. This only affects application commands.

help_getter: t.Optional[t.Callable[[Command, context_.base.Context], str]]#: The function to call to get the command’s long help text.

hidden: bool#: Whether or not the command should be hidden from the help command.

inherit_checks: bool#: Whether or not the command should inherit checks from the parent group.

max_concurrency: t.Optional[t.Tuple[int, t.Type[buckets.Bucket]]]#: The max concurrency rule for the command.

New in version 2.2.1.

name: str#: The name of the command.

name_localizations: t.Mapping[t.Union[hikari.Locale, str], str]#: A mapping of locale to name localizations for this command

New in version 2.3.0.

nsfw: bool#

Whether the command should only be enabled in NSFW channels.

For prefix commands, this will add an NSFW-channel only check to the command automatically. For slash commands, this will behave as specified in the Discord documentation.

New in version 2.3.1.

options: t.MutableMapping[str, OptionLike]#: The options for the command.

parser: t.Optional[t.Type[parser_.BaseParser]]#: The argument parser to use for prefix commands.

pass_options: bool#: Whether or not the command will have its options passed as keyword arguments when invoked.

New in version 2.2.1.

subcommands: t.List[CommandLike]#: Subcommands for the command.

class lightbulb.commands.base.OptionLike(name: str, description: str, arg_type: ~typing.Any = <class 'str'>, required: bool = True, choices: ~typing.Sequence[str | int | float | ~hikari.commands.CommandChoice] | None = None, channel_types: ~typing.Sequence[~hikari.channels.ChannelType] | None = None, default: ~typing.Any | ~hikari.undefined.UndefinedType = UNDEFINED, modifier: ~lightbulb.commands.base.OptionModifier = OptionModifier.NONE, min_value: float | int | None = None, max_value: float | int | None = None, min_length: int | None = None, max_length: int | None = None, autocomplete: bool = False, name_localizations: ~typing.Mapping[~hikari.locales.Locale | str, str] = _Nothing.NOTHING, description_localizations: ~typing.Mapping[~hikari.locales.Locale | str, str] = _Nothing.NOTHING)[source]#

Generic dataclass representing a command option. Compatible with both prefix and application commands.

as_application_command_option() → CommandOption[source]#

Convert this object into a CommandOption.

Returns:: Created CommandOption object.
Return type:: CommandOption

arg_type: Any#: The type of the option.

autocomplete: bool#: Whether the option should be autocompleted or not. This only affects slash commands.

channel_types: Sequence[ChannelType] | None#: The channel types for this option. This only affects slash commands.

choices: Sequence[str | int | float | CommandChoice] | None#: The option’s choices. This only affects slash commands.

default: Any | UndefinedType#: The default value for this option.

description: str#: The description of the option

description_localizations: Mapping[Locale | str, str]#: A mapping of locale to description localizations for this option

New in version 2.3.0.

max_length: int | None#: The maximum length permitted for this option. The option must be STRING to use this.

New in version 2.3.2.

max_value: float | int | None#: The maximum value permitted for this option (inclusive). The option must be INTEGER or FLOAT to use this.

New in version 2.1.3.

min_length: int | None#: The minimum length permitted for this option. The option must be STRING to use this.

New in version 2.3.2.

min_value: float | int | None#: The minimum value permitted for this option (inclusive). The option must be INTEGER or FLOAT to use this.

New in version 2.1.3.

modifier: OptionModifier#: Additional modifier controlling how the option should be parsed. This only affects prefix commands.

name: str#: The name of the option.

name_localizations: Mapping[Locale | str, str]#: A mapping of locale to name localizations for this option

New in version 2.3.0.

required: bool#: Whether or not the option is required. This will be inferred from whether or not a default value was provided if unspecified.

class lightbulb.commands.base.OptionModifier(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Enum representing option modifiers that affect parsing for prefix commands.

CONSUME_REST = 3#: Consume rest option. This will consume the entire remainder of the string.

GREEDY = 2#: Greedy option. This will consume arguments until the string is exhausted or conversion fails.

NONE = 1#: No modifier. This will be parsed as a normal argument.

class lightbulb.commands.base.SubCommandTrait[source]#

Trait that all subcommands and subgroups have.

You can check if any given command is a subcommand by checking issubclass on the command’s class or isinstance if you have the object.

Prefix Commands#

class lightbulb.commands.prefix.PrefixCommand(app: app_.BotApp, initialiser: CommandLike)[source]#

Bases: Command

An implementation of Command representing a prefix command.

async invoke(context: Context, **kwargs: Any) → None[source]#: Invokes the command under the given context. All checks, cooldowns and concurrency limits will be processed prior to invocation.

property signature: str#: The command’s text signature.

class lightbulb.commands.prefix.PrefixCommandGroup(app: app_.BotApp, initialiser: base.CommandLike)[source]#

Bases: PrefixCommand, PrefixGroupMixin

Class representing a prefix command group.

async invoke(context: Context, **kwargs: Any) → None[source]#: Invokes the command under the given context. All checks, cooldowns and concurrency limits will be processed prior to invocation.

class lightbulb.commands.prefix.PrefixGroupMixin[source]#

Bases: ABC

property subcommands: Dict[str, PrefixSubGroup | PrefixSubCommand]#: Mapping of command name to command object containing the group’s subcommands.

class lightbulb.commands.prefix.PrefixSubCommand(app: app_.BotApp, initialiser: CommandLike)[source]#

Bases: PrefixCommand, SubCommandTrait

Class representing a prefix subcommand.

async invoke(context: Context, *, _arg_buffer: str = '', **kwargs: Any) → None[source]#: Invokes the command under the given context. All checks, cooldowns and concurrency limits will be processed prior to invocation.

property qualname: str#: The qualified name for the command.

class lightbulb.commands.prefix.PrefixSubGroup(app: app_.BotApp, initialiser: base.CommandLike)[source]#

Bases: PrefixCommand, PrefixGroupMixin, SubCommandTrait

Class representing a prefix subgroup of commands.

async invoke(context: Context, *, _arg_buffer: str = '', **kwargs: Any) → None[source]#: Invokes the command under the given context. All checks, cooldowns and concurrency limits will be processed prior to invocation.

property qualname: str#: The qualified name for the command.

Slash Commands#

class lightbulb.commands.slash.SlashCommand(app: app_.BotApp, initialiser: CommandLike)[source]#

Bases: ApplicationCommand

An implementation of Command representing a slash command.

See the API Documentation.

as_create_kwargs() → Dict[str, Any][source]#

Converts this class into a dictionary of kwargs required by create_application_command.

Returns:: Kwargs required in order to create the command.
Return type:: Dict[str, Any]

class lightbulb.commands.slash.SlashCommandGroup(app: app_.BotApp, initialiser: base.CommandLike)[source]#

Bases: SlashCommand, SlashGroupMixin

Class representing a slash command group.

as_create_kwargs() → Dict[str, Any][source]#

Converts this class into a dictionary of kwargs required by create_application_command.

Returns:: Kwargs required in order to create the command.
Return type:: Dict[str, Any]

async invoke(context: Context, **_: Any) → None[source]#: Invokes the command under the given context. All checks, cooldowns and concurrency limits will be processed prior to invocation.

class lightbulb.commands.slash.SlashGroupMixin[source]#

Bases: ABC

get_subcommand(name: str) → SlashSubGroup | SlashSubCommand | None[source]#: Get the group’s subcommand with the given name.

property subcommands: Dict[str, SlashSubGroup | SlashSubCommand]#: Mapping of command name to command object containing the group’s subcommands.

class lightbulb.commands.slash.SlashSubCommand(app: app_.BotApp, initialiser: CommandLike)[source]#

Bases: SlashCommand, SubCommandTrait

Class representing a slash subcommand.

property qualname: str#: The qualified name for the command.

class lightbulb.commands.slash.SlashSubGroup(app: app_.BotApp, initialiser: base.CommandLike)[source]#

Bases: SlashCommand, SlashGroupMixin, SubCommandTrait

Class representing a slash subgroup of commands.

async invoke(context: Context, **_: Any) → None[source]#: Invokes the command under the given context. All checks, cooldowns and concurrency limits will be processed prior to invocation.

property qualname: str#: The qualified name for the command.

Message Commands#

class lightbulb.commands.message.MessageCommand(*args: Any, **kwargs: Any)[source]#

Bases: ApplicationCommand

An implementation of Command representing a message context menu command.

See the API Documentation.

New in version 2.2.0.

as_create_kwargs() → Dict[str, Any][source]#

Converts this class into a dictionary of kwargs required by create_application_command.

Returns:: Kwargs required in order to create the command.
Return type:: Dict[str, Any]

property description_localizations: Mapping[Locale | str, str]#: A mapping of locale to description localizations for this command.

New in version 2.3.0.

property options: Dict[str, Any]#: The options for the command.

User Commands#

class lightbulb.commands.user.UserCommand(*args: Any, **kwargs: Any)[source]#

Bases: ApplicationCommand

An implementation of Command representing a user context menu command.

See the API Documentation.

New in version 2.2.0.

as_create_kwargs() → Dict[str, Any][source]#

Converts this class into a dictionary of kwargs required by create_application_command.

Returns:: Kwargs required in order to create the command.
Return type:: Dict[str, Any]

property description_localizations: Mapping[Locale | str, str]#: A mapping of locale to description localizations for this command.

New in version 2.3.0.

property options: Dict[str, Any]#: The options for the command.