lightbulb.client

class lightbulb.client.Client(rest: hikari.api.RESTClient, default_enabled_guilds: t.Sequence[hikari.Snowflakeish], execution_step_order: t.Sequence[execution.ExecutionStep], default_locale: hikari.Locale, localization_provider: localization.LocalizationProviderT, delete_unknown_commands: bool, deferred_registration_callback: t.Callable[[CommandOrGroup], MaybeAwaitable[hikari.Snowflakeish | t.Sequence[hikari.Snowflakeish]]] | None)

Base client implementation supporting generic application command handling.

Parameters:

• rest (RESTClient) – The rest client to use.

• default_enabled_guilds (Sequence [ Snowflakeish ]) – The guilds that application commands should be created in by default. Can be overridden on a per-command basis.

• execution_step_order (Sequence [ ExecutionStep ]) – The order that execution steps will be run in upon command processing.

• default_locale (Locale) – The default locale to use for command names and descriptions, as well as option names and descriptions. Has no effect if localizations are not being used.

• localization_provider – The localization provider function to use. This will be called whenever the client needs to get the localizations for a key.

• delete_unknown_commands (bool) – Whether to delete existing commands that the client does not have an implementation for during command syncing.

• deferred_registration_callback – The callback to use to resolve which guilds a command should be created in if a command is registered using register_deferred(). Allows for commands to be dynamically created in guilds, for example enabled on a per-guild basis using feature flags.

build_autocomplete_context(interaction: AutocompleteInteraction, options: Sequence[AutocompleteInteractionOption], command_cls: type[CommandBase]) → AutocompleteContext

Build a context object from the given parameters.

Parameters:

• interaction (AutocompleteInteraction) – The interaction for the autocomplete invocation.

• options (Sequence [ hikari.CommandInteractionOption ]) – The options supplied with the interaction.

• command_cls (Type [ CommandBase ]) – The command class that represents the command that has the option being autocompleted.

Returns:

The built context.

Return type:

AutocompleteContext

build_command_context(interaction: CommandInteraction, options: Sequence[CommandInteractionOption], command_cls: type[CommandBase]) → Context

Build a context object from the given parameters.

Parameters:

• interaction (CommandInteraction) – The interaction for the command invocation.

• options (Sequence [ hikari.CommandInteractionOption ]) – The options to use to invoke the command with.

• command_cls (Type [ CommandBase ]) – The command class that represents the command that should be invoked for the interaction.

Returns:

The built context.

Return type:

Context

error_handler(*, priority: int = 0) → Callable[[ErrorHandlerT], ErrorHandlerT]

error_handler(func: ErrorHandlerT, *, priority: int = 0) → ErrorHandlerT

Register an error handler function to call when an ExecutionPipeline fails. Also enables dependency injection for the error handler function.

The function must take the exception as its first argument, which will be an instance of ExecutionPipelineFailedException. The function must return a boolean indicating whether the exception was successfully handled. Non-boolean return values will be cast to booleans.

Parameters:

• func – The function to register as a command error handler.

• priority (int) – The priority that this handler should be registered at. Higher priority handlers will be executed first.

async load_extensions(*import_paths: str) → None

Load extensions from the given import paths. If loading of a single extension fails it will be skipped and any loaders already processed, as well as the one that caused the error will be removed.

Parameters:

*import_paths (str) – The import paths for the extensions to be loaded.

Returns:

None

See also

load_extensions_from_package()

async load_extensions_from_package(package: types.ModuleType, *, recursive: bool = False) → None

Load all extension modules from the given package. Ignores any files with a name that starts with an underscore.

Parameters:

• package (ModuleType) – The package to load extensions from. Expects the imported module for the __init__.py file in the package.

• recursive (bool) – Whether to recursively load extensions from subpackages. Defaults to False.

Returns:

None

Raises:

TypeError – If the given module is not for the __init__.py file of a package.

Example

Given the following file structure:

To load all extensions in the extensions package you should do the following:

import extensions

await client.load_extensions_from_package(extensions)

See also

load_extensions()

register(*, guilds: Sequence[Snowflake | int] | None = None) → Callable[[CommandOrGroupT], CommandOrGroupT]

register(command: CommandOrGroupT, *, guilds: Sequence[Snowflake | int] | None = None) → CommandOrGroupT

Register a command or group with this client instance. Optionally, a sequence of guild ids can be provided to make the commands created in specific guilds only - overriding the value for default enabled guilds.

This method can be used as a function, or a first or second order decorator.

Parameters:

• command (Union [ Type [ Group ]) – The command class or command group to register with the client.

• guilds (Optional [ Sequence [ Snowflakeish ]]) – The guilds to create the command or group in. If set to None, then this will fall back to the default enabled guilds. To override default enabled guilds and make the command or group global, this should be set to an empty sequence.

Returns:

The registered command or group, unchanged.

Example

client = lightbulb.client_from_app(...)

# valid
@client.register
# also valid
@client.register(guilds=[...])
class Example(
    lightbulb.SlashCommand,
    ...
):
    ...

# also valid
client.register(Example, guilds=[...])

async start(_: Any = None) → None

Starts the client. Ensures that commands are registered properly with the client, and that commands have been synced with discord.

Returns:

None

async sync_application_commands() → None

Sync all application commands registered to the bot with discord.

Returns:

None

class lightbulb.client.GatewayEnabledClient(app: GatewayClientAppT, *args: Any, **kwargs: Any)

Client implementation for applications that support gateway events.

Warning

This client should not be instantiated manually. Use client_from_app() instead.

Warning

This client will not be started automatically (see: start()). It is recommended that you start the client in a listener for StartedEvent. You should ensure that any commands are registered and extensions have been loaded before starting the client - otherwise command syncing may not work properly.

For example:

bot = hikari.GatewayBot(...)
client = lightbulb.client_from_app(bot, ...)

bot.subscribe(hikari.StartedEvent, client.start)

class lightbulb.client.RestEnabledClient(app: RestClientAppT, *args: Any, **kwargs: Any)

Client implementation for applications that support an interaction server.

Warning

This client should not be instantiated manually. Use client_from_app() instead.

Warning

This client will not be started automatically (see: start()). It is recommended that you start the client in a RESTBot startup callback. You should ensure that any commands are registered and extensions have been loaded before starting the client - otherwise command syncing may not work properly.

For example:

bot = hikari.RESTBot(...)
client = lightbulb.client_from_app(bot, ...)

async def start_client() -> None:
    # Load extensions here
    await client.start()

lightbulb.client.client_from_app(app: GatewayClientAppT | RestClientAppT, default_enabled_guilds: t.Sequence[hikari.Snowflakeish] = (0,), execution_step_order: t.Sequence[execution.ExecutionStep] = (ExecutionStep(name='MAX_CONCURRENCY'), ExecutionStep(name='CHECKS'), ExecutionStep(name='COOLDOWNS'), ExecutionStep(name='INVOKE'), ExecutionStep(name='POST_INVOKE')), default_locale: hikari.Locale = <Locale.EN_US: 'en-US'>, localization_provider: localization.LocalizationProviderT = <function localization_unsupported>, delete_unknown_commands: bool = True, deferred_registration_callback: t.Callable[[CommandOrGroup], MaybeAwaitable[hikari.Snowflakeish | t.Sequence[hikari.Snowflakeish]]] | None = None) → Client

Create and return the appropriate client implementation from the given application.

Parameters:

• app – Application that either supports gateway events, or an interaction server.

• default_enabled_guilds (Sequence [ Snowflakeish ]) – The guilds that application commands should be created in by default.

• execution_step_order (Sequence [ ExecutionStep ]) – The order that execution steps will be run in upon command processing.

• default_locale – (Locale): The default locale to use for command names and descriptions, as well as option names and descriptions. Has no effect if localizations are not being used. Defaults to hikari.locales.Locale.EN_US.

• localization_provider (Callable [ [ str ], Mapping [ Locale, str ] ]) – The localization provider function to use. This will be called whenever the client needs to get the localizations for a key. Defaults to localization_unsupported - the client does not support localizing commands. Must be passed if you intend to support localizations.

• delete_unknown_commands (bool) – Whether to delete existing commands that the client does not have an implementation for during command syncing. Defaults to True.

• deferred_registration_callback – The callback to use to resolve which guilds a command should be created in if a command is registered using register_deferred(). Allows for commands to be dynamically created in guilds, for example enabled on a per-guild basis using feature flags. Defaults to None.

Returns:

The created client instance.

Return type:

Client