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: Optional[int] = None) hikari.commands.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

Notes

If creating a command globally, it will take up to 1 hour to appear and be usable. As mentioned in the API documentation

async delete(guild: Optional[int]) 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.

aliases: t.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.

auto_defer: bool#

Whether or not to automatically defer the response when the command is invoked.

property bot: app_.BotApp#

Alias for app

callback: CommandCallbackT#

The callback function for the command.

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.

checks: t.Sequence[t.Union[checks.Check, checks._ExclusiveCheck]]#

The checks for the command.

cooldown_manager: t.Optional[cooldowns.CooldownManager]#

The cooldown manager instance to use for the command.

default_ephemeral: bool#

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

description: str#

The description of the command.

error_handler: t.Optional[t.Callable[[events.CommandErrorEvent], t.Coroutine[t.Any, t.Any, t.Optional[bool]]]]#

The error handler function for the command.

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.

property is_subcommand: bool#

Boolean representing whether or not this object is a subcommand.

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

The max concurrency rule for the command.

name: str#

The name of the command.

options: t.MutableMapping[str, OptionLike]#

The options for the command.

parent: t.Optional[Command]#

The parent 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.

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

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

autocomplete(opt1: str, *opts: str) Callable[[lightbulb.commands.base.AutocompleteCallbackT], lightbulb.commands.base.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.

child(cmd_like: Optional[lightbulb.commands.base.CommandLike] = None) Union[lightbulb.commands.base.CommandLike, Callable[[lightbulb.commands.base.CommandLike], lightbulb.commands.base.CommandLike]][source]#

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.

set_error_handler(func: t.Optional[t.Callable[[events.CommandErrorEvent], t.Coroutine[t.Any, t.Any, t.Optional[bool]]]] = None) t.Union[t.Callable[[events.CommandErrorEvent], t.Coroutine[t.Any, t.Any, t.Optional[bool]]], t.Callable[[t.Callable[[events.CommandErrorEvent], t.Coroutine[t.Any, t.Any, t.Optional[bool]]]], t.Callable[[events.CommandErrorEvent], t.Coroutine[t.Any, t.Any, t.Optional[bool]]]]][source]#

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.

aliases: t.Sequence[str]#

The aliases for the command. This only affects prefix commands.

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.

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.

name: str#

The name of the command.

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.

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.Optional[typing.Sequence[typing.Union[str, int, float, hikari.commands.CommandChoice]]] = None, channel_types: typing.Optional[typing.Sequence[hikari.channels.ChannelType]] = None, default: typing.Union[typing.Any, hikari.undefined.UndefinedType] = UNDEFINED, modifier: lightbulb.commands.base.OptionModifier = OptionModifier.NONE, min_value: typing.Optional[typing.Union[float, int]] = None, max_value: typing.Optional[typing.Union[float, int]] = None, autocomplete: bool = False)[source]#

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() hikari.commands.CommandOption[source]#

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: Optional[Sequence[hikari.channels.ChannelType]] = None#

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

choices: Optional[Sequence[Union[str, int, float, hikari.commands.CommandChoice]]] = None#

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

default: Union[Any, hikari.undefined.UndefinedType] = UNDEFINED#

The default value for this option.

description: str#

The description of the option

max_value: Optional[Union[float, int]] = None#

The maximum value permitted for this option (inclusive). The option must be INTEGER or FLOAT to use this.

min_value: Optional[Union[float, int]] = None#

The minimum value permitted for this option (inclusive). The option must be INTEGER or FLOAT to use this.

modifier: lightbulb.commands.base.OptionModifier = 1#

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

name: str#

The name of the option.

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)[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: lightbulb.commands.base.Command

An implementation of Command representing a prefix command.

async invoke(context: lightbulb.context.base.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: lightbulb.commands.prefix.PrefixCommand, lightbulb.commands.prefix.PrefixGroupMixin

Class representing a prefix command group.

async invoke(context: lightbulb.context.base.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.ABC

property subcommands: Dict[str, Union[lightbulb.commands.prefix.PrefixSubGroup, lightbulb.commands.prefix.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: lightbulb.commands.prefix.PrefixCommand, lightbulb.commands.base.SubCommandTrait

Class representing a prefix subcommand.

async invoke(context: lightbulb.context.base.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: lightbulb.commands.prefix.PrefixCommand, lightbulb.commands.prefix.PrefixGroupMixin, lightbulb.commands.base.SubCommandTrait

Class representing a prefix subgroup of commands.

async invoke(context: lightbulb.context.base.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: lightbulb.commands.base.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: lightbulb.commands.slash.SlashCommand, lightbulb.commands.slash.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: lightbulb.context.base.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.ABC

get_subcommand(name: str) Optional[Union[lightbulb.commands.slash.SlashSubGroup, lightbulb.commands.slash.SlashSubCommand]][source]#

Get the group’s subcommand with the given name.

property subcommands: Dict[str, Union[lightbulb.commands.slash.SlashSubGroup, lightbulb.commands.slash.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: lightbulb.commands.slash.SlashCommand, lightbulb.commands.base.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: lightbulb.commands.slash.SlashCommand, lightbulb.commands.slash.SlashGroupMixin, lightbulb.commands.base.SubCommandTrait

Class representing a slash subgroup of commands.

async invoke(context: lightbulb.context.base.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: lightbulb.commands.base.ApplicationCommand

An implementation of Command representing a message context menu 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]


User Commands#

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

Bases: lightbulb.commands.base.ApplicationCommand

An implementation of Command representing a user context menu 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]