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, orNone
if to create globally.- Returns
Created hikari
Command
object.- Return type
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, orNone
if to delete globally.- Returns
None
- class lightbulb.commands.base.Command(app: app_.BotApp, initialiser: CommandLike)[source]#
Abstract base class for all command types.
- Parameters
app (
BotApp
) – TheBotApp
instance that the command is registered to.initialiser (
CommandLike
) – TheCommandLike
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 raiseCheckFailure
.
- 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 raiseerrors.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.
- 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.
- 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.
- error_handler: t.Optional[t.Callable[[events.CommandErrorEvent], t.Coroutine[t.Any, t.Any, t.Optional[bool]]]]#
The error handler function for the command.
Whether or not the command should be hidden from the help command.
- max_concurrency: t.Optional[t.Tuple[int, t.Type[buckets.Bucket]]]#
The max concurrency rule for the command.
- 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.
- property plugin: t.Optional[plugins.Plugin]#
The plugin that the command belongs to.
- 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 ofhikari.interactions.command_interactions.AutocompleteInteractionOption
) which is the option being autocompleted, andinteraction
(an instance ofhikari.interactions.command_interactions.AutocompleteInteraction
) which is the interaction that triggered the autocomplete.Autocomplete can only be enabled for options with type
str
,int
, orfloat
.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 ofhikari.commands.CommandChoice
.
- 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 theCommandLike
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.
- 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.
- 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.
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.
- 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.
- as_application_command_option() hikari.commands.CommandOption [source]#
Convert this object into a
CommandOption
.- Returns
Created
CommandOption
object.- Return type
- 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.
- max_value: Optional[Union[float, int]] = None#
The maximum value permitted for this option (inclusive). The option must be
INTEGER
orFLOAT
to use this.
- min_value: Optional[Union[float, int]] = None#
The minimum value permitted for this option (inclusive). The option must be
INTEGER
orFLOAT
to use this.
- modifier: lightbulb.commands.base.OptionModifier = 1#
Additional modifier controlling how the option should be parsed. This only affects prefix commands.
- 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.
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.
- 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.
- 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.
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.
- 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.
- 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.
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.
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.