Decorators API Reference#

lightbulb.decorators.add_checks(*cmd_checks: Check | _ExclusiveCheck) → Callable[[CommandLike], CommandLike][source]#

Second order decorator that adds one or more checks to the decorated CommandLike object.

Parameters:

*cmd_checks (Check) – Check object(s) to add to the command.

lightbulb.decorators.add_cooldown(length: float, uses: int, bucket: Type[Bucket], algorithm: Type[CooldownAlgorithm] = cooldown_algorithms.BangBangCooldownAlgorithm) → Callable[[CommandLike], CommandLike][source]#
lightbulb.decorators.add_cooldown(*, callback: t.Callable[[context.base.Context], t.Union[buckets.Bucket, t.Coroutine[t.Any, t.Any, buckets.Bucket]]]) → Callable[[CommandLike], CommandLike]

Second order decorator that sets the cooldown manager for a command.

Parameters:

  • length (float) – The length in seconds of the cooldown timer.

  • uses (int) – The number of command invocations before the cooldown will be triggered.

  • bucket (Type[Bucket]) – The bucket to use for cooldowns.

  • algorithm (Type[CooldownAlgorithm]) – The cooldown algorithm to use. Defaults to BangBangCooldownAlgorithm.

Keyword Arguments:

  • callback (Callable[[Bucket, Coroutine[Any, Any, Bucket]]]) – Callable that takes the context the command was invoked under and returns the appropriate bucket object to use for cooldowns in the context.

  • cls (Type[CooldownManager]) – The cooldown manager class to use. Defaults to CooldownManager.

lightbulb.decorators.app_command_permissions(perms: Permissions | None = None, *, dm_enabled: bool = True, bypass_checks: bool = False) → Callable[[CommandLike], CommandLike][source]#

Second order decorator that defines the application command permissions v2 configuration for a command.

Parameters:

  • perms (Optional[hikari.Permissions]) – The permissions to set as the default for the command when it is created in a guild. If None, no default permissions will be set.

  • dm_enabled (bool) – Whether the command should be available in DM. If the command is not global then this will have no effect.

  • bypass_checks (bool) – Whether author permissions checks will be bypassed when this command is invoked as an application command. This allows guild admins to dictate who is allowed to use the command as opposed to enforcing a set of permissions.

New in version 2.2.3.

lightbulb.decorators.check_exempt(predicate: t.Callable[[context.base.Context], t.Union[bool, t.Coroutine[t.Any, t.Any, bool]]]) → t.Callable[[commands.base.CommandLike], commands.base.CommandLike][source]#

Second order decorator which allows all checks to be bypassed if the predicate conditions are met. Predicate can be a synchronous or asynchronous function but must take a single argument - context - and must return a boolean - True if checks should be bypassed or False if not.

Parameters:

predicate (Callable[[Context], Union[bool, Coroutine[Any, Any, bool]]) – The function to call to check if the checks should be bypassed for the given context.

lightbulb.decorators.command(name: str, description: str, *, cls: ~typing.Type[~lightbulb.commands.base.CommandLike] = <class 'lightbulb.commands.base.CommandLike'>, **kwargs: ~typing.Any) → Callable[[CommandCallbackT], CommandLike][source]#

Second order decorator that converts the decorated function into a CommandLike object.

Parameters:

  • name (str) – The name of the command .

  • description (str) – The description of the command.

Keyword Arguments:

  • error_handler (Optional[ListenerT]) – The function to register as the command’s error handler. Defaults to None. This can also be set with the set_error_handler decorator.

  • aliases (Sequence[str]) – Aliases for the command. This will only affect prefix commands. Defaults to an empty list.

  • guilds (Sequence[int]) – The guilds that the command will be created in. This will only affect application commands. Defaults to an empty list.

  • parser (BaseParser) – The argument parser to use for prefix commands. Defaults to Parser.

  • auto_defer (bool) – Whether to automatically defer the response when the command is invoked. If True, the bot will send an initial response of type DEFERRED_MESSAGE_CREATE for interactions, and for prefix commands, typing will be triggered in the invocation channel.

  • ephemeral (bool) – Whether to send responses from the invocation of this command as ephemeral by default. If True then all responses from the command will use the flag hikari.MessageFlags.EPHEMERAL. This will not affect prefix commands as responses from prefix commands cannot be ephemeral.

  • hidden (bool) – Whether to hide the command from the help command. Defaults to False.

  • inherit_checks (bool) – Whether or not the command should inherit checks from the parent group. Only affects subcommands. Defaults to False.

  • pass_options (bool) – Whether the command will have its options passed as keyword arguments when invoked.

  • name_localizations (Mapping[Union[hikari.locales.Locale, str], str]) – A mapping of locale to name localizations for this command. Defaults to an empty dictionary.

  • description_localizations (Mapping[Union[hikari.locales.Locale, str], str]) – A mapping of locale to description localizations for this command. Defaults to an empty dictionary.

  • 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.

  • cls (Type[CommandLike]) – CommandLike class to instantiate from this decorator. Defaults to CommandLike.

New in version 2.1.0: cls kwarg.

New in version 2.2.1: pass_options kwarg.

New in version 2.3.0: name_localizations and description_localizations kwargs.

lightbulb.decorators.implements(*command_types: Type[Command]) → Callable[[CommandCallbackT], CommandCallbackT][source]#

Second order decorator that defines the command types that a given callback function will implement.

Parameters:

*command_types (Type[Command]) – Command types that the function will implement.

lightbulb.decorators.option(name: str, description: str, type: ~typing.Any = <class 'str'>, *, required: bool | ~hikari.undefined.UndefinedType = UNDEFINED, 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 | ~typing.Callable[[~hikari.interactions.command_interactions.CommandInteractionOption, ~hikari.interactions.command_interactions.AutocompleteInteraction], ~typing.Coroutine[~typing.Any, ~typing.Any, str | ~hikari.api.special_endpoints.AutocompleteChoiceBuilder | ~typing.Sequence[str | ~hikari.api.special_endpoints.AutocompleteChoiceBuilder]]] = False, cls: ~typing.Type[~lightbulb.commands.base.OptionLike] = <class 'lightbulb.commands.base.OptionLike'>, **kwargs: ~typing.Any) → Callable[[CommandLike], CommandLike][source]#

Second order decorator that adds an option to the decorated CommandLike object.

Parameters:

  • name (str) – The name of the option.

  • description (str) – The description of the option.

  • type (Any) – The type of the option. This will be used as the converter for prefix commands.

Keyword Arguments:

  • required (UndefinedOr[bool]) – Whether this option is required. This will be inferred from whether a default value for the option was specified if not otherwise specified.

  • choices (Optional[Sequence[Union[str, int, float, CommandChoice]]]) – The choices for the option. This will only affect slash commands. Defaults to None.

  • channel_types (Optional[Sequence[hikari.channels.ChannelType]]) – The channel types allowed for the option. This will only affect slash commands. Defaults to None.

  • default (UndefinedOr[Any]) – The default value for the option. Defaults to UNDEFINED.

  • modifier (OptionModifier) – Modifier controlling how the option should be parsed. Defaults to OptionModifier.NONE.

  • min_value (Optional[Union[float, int]]) – The minimum value permitted for this option (inclusive). Only available if the option type is numeric (integer or float). Defaults to None.

  • max_value (Optional[Union[float, int]]) – The maximum value permitted for this option (inclusive). Only available if the option type is numeric (integer or float). Defaults to None.

  • min_length (Optional[int]) – The minimum length permitted for this option. Only available if this option is string type.

  • max_length (Optional[int]) – The maximum length permitted for this option. Only available if this option is string type.

  • autocomplete (Union[bool, AutocompleteCallbackT]) – Boolean representing whether the option will use autocomplete or the callback to use for autocomplete for this option. This will only affect slash commands. Defaults to False.

  • name_localizations (Mapping[Union[hikari.locales.Locale, str], str]) – A mapping of locale to name localizations for this option. Defaults to an empty dictionary.

  • description_localizations (Mapping[Union[hikari.locales.Locale, str], str]) – A mapping of locale to description localizations for this option. Defaults to an empty dictionary.

  • cls (Type[OptionLike]) – OptionLike class to instantiate from this decorator. Defaults to OptionLike.

New in version 2.1.0: cls kwarg.

New in version 2.1.3: min_value and max_value kwargs.

New in version 2.3.2: min_length and max_length kwargs.

lightbulb.decorators.set_help(text: t.Optional[t.Union[str, t.Callable[[commands.base.Command, context.base.Context], str]]] = None, *, docstring: bool = False) → t.Callable[[commands.base.CommandLike], commands.base.CommandLike][source]#

Second order decorator that defines the long help text for a command, or how the long help text should be retrieved. If text is provided then it will override the value for docstring.

Parameters:

text (Union[Callable[[Command, Context], str], str]) – The long help text for the command, or a synchronous function called with the Command object to get help text for and the Context that the help text should be retrieved for. If this is not provided, then you must pass the kwarg docstring=True.

Keyword Arguments:

docstring (bool) – Whether the command help text should be extracted from the command’s docstring. If this is False (default) then a value must be provided for the text arg.

lightbulb.decorators.set_max_concurrency(uses: int, bucket: Type[Bucket]) → Callable[[CommandLike], CommandLike][source]#

Second order decorator that defines the max concurrency limit for a command.

Parameters:

  • uses (int) – The maximum number of uses of the command that can be executing concurrently before a MaxConcurrencyLimitReached will be raised upon invocation.

  • bucket (Type[Bucket]) – Bucket that command max concurrency will be processed under.

New in version 2.2.1.