Commands API Reference

Base

class lightbulb.commands.base.ApplicationCommand(app: app_.BotApp, initialiser: CommandLike)

Abstract base class for all application command types.

abstract as_create_kwargs() → Dict[str, Any]

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

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

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)

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

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

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

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

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] = <factory>, checks: t.Sequence[t.Union[checks.Check, checks._ExclusiveCheck]] = <factory>, error_handler: t.Optional[t.Callable[[events.CommandErrorEvent], t.Coroutine[t.Any, t.Any, t.Optional[bool]]]] = None, aliases: t.Sequence[str] = <factory>, guilds: hikari.UndefinedOr[t.Sequence[int]] = UNDEFINED, subcommands: t.List[CommandLike] = <factory>, 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] = <factory>, description_localizations: t.Mapping[t.Union[hikari.Locale, str], str] = <factory>, nsfw: bool = False)

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

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

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]

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]

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 = False

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] = None

The default member permissions for this command, if an application command.

New in version 2.2.3.

app_command_dm_enabled: bool = True

Whether this command will be enabled in DMs, if an application command.

New in version 2.2.3.

auto_defer: bool = False

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]]]] = None

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] = None

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 = False

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]]]] = None

The error handler for the command.

guilds: hikari.UndefinedOr[t.Sequence[int]] = UNDEFINED

The guilds for the command. This only affects application commands.

help_getter: t.Optional[t.Callable[[Command, context_.base.Context], str]] = None

The function to call to get the command’s long help text.

hidden: bool = False

Whether or not the command should be hidden from the help command.

inherit_checks: bool = False

Whether or not the command should inherit checks from the parent group.

max_concurrency: t.Optional[t.Tuple[int, t.Type[buckets.Bucket]]] = None

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 = False

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]] = None

The argument parser to use for prefix commands.

pass_options: bool = False

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] = <factory>, description_localizations: ~typing.Mapping[~hikari.locales.Locale | str, str] = <factory>)

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

arg_type

The type of the option.

alias of str

as_application_command_option() → CommandOption

Convert this object into a CommandOption.

Returns:

Created CommandOption object.

Return type:

CommandOption

autocomplete: bool = False

Whether the option should be autocompleted or not. This only affects slash commands.

channel_types: Sequence[ChannelType] | None = None

The channel types for this option. This only affects slash commands.

choices: Sequence[str | int | float | CommandChoice] | None = None

The option’s choices. This only affects slash commands.

default: Any | UndefinedType = UNDEFINED

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 = 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 = 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 = 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 = 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 = 1

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 = True

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)

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

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)

Bases: Command

An implementation of Command representing a prefix command.

async invoke(context: Context, **kwargs: Any) → None

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)

Bases: PrefixCommand, PrefixGroupMixin

Class representing a prefix command group.

async invoke(context: Context, **kwargs: Any) → None

Invokes the command under the given context. All checks, cooldowns and concurrency limits will be processed prior to invocation.

class lightbulb.commands.prefix.PrefixGroupMixin

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)

Bases: PrefixCommand, SubCommandTrait

Class representing a prefix subcommand.

async invoke(context: Context, *, _arg_buffer: str = '', **kwargs: Any) → None

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)

Bases: PrefixCommand, PrefixGroupMixin, SubCommandTrait

Class representing a prefix subgroup of commands.

async invoke(context: Context, *, _arg_buffer: str = '', **kwargs: Any) → None

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)

Bases: ApplicationCommand

An implementation of Command representing a slash command.

See the API Documentation.

as_create_kwargs() → Dict[str, Any]

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)

Bases: SlashCommand, SlashGroupMixin

Class representing a slash command group.

as_create_kwargs() → Dict[str, Any]

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

Invokes the command under the given context. All checks, cooldowns and concurrency limits will be processed prior to invocation.

class lightbulb.commands.slash.SlashGroupMixin

Bases: ABC

get_subcommand(name: str) → SlashSubGroup | SlashSubCommand | None

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)

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)

Bases: SlashCommand, SlashGroupMixin, SubCommandTrait

Class representing a slash subgroup of commands.

async invoke(context: Context, **_: Any) → None

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)

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]

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)

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]

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.