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.