lightbulb.loaders¶

class Loadable[source]¶

Abstract class containing the logic required to add and remove a feature from a client instance.

abstract async load(client: client_.Client) → None[source]¶

Add the feature to the client instance.

Parameters:: client – The client instance to add the feature to.
Returns:: None

Warning

This method must be idempotent. I.e. if the item being loaded is already loaded, the method must not attempt to load the item a second time.

abstract async unload(client: client_.Client) → None[source]¶

Remove the feature from the client instance.

Parameters:: client – The client instance to remove the feature from.
Returns:: None

Warning

This method must be idempotent. I.e. if the item being unloaded is already unloaded, the method must not attempt to unload the item a second time.

class Loader(should_load_hook: Callable[[], types.MaybeAwaitable[bool]] = <function Loader.<lambda>>)[source]¶

Class used for loading features into the client from extensions.

Parameters:: should_load_hook – Synchronous or asynchronous function which will be called when the loader is added to the client. Returns a boolean indicating whether this loader should be loaded or not. If it returns False, the loader will not be loaded and none of its features will be added to the client.

add(loadable: Loadable) → Loadable[source]¶

Add the given loadable to this loader.

Parameters:: loadable – The loadable to add.
Returns:: The added loadable, unchanged.

async add_to_client(client: client_.Client) → None[source]¶

Add the features contained within this loader to the given client.

Parameters:: client – The client to add this loader’s features to.
Returns:: None

command(*, guilds: Sequence[Snowflake | int] | None = None, global_: bool | None = None) → Callable[[CommandOrGroupT], CommandOrGroupT][source]¶

command(*, defer_guilds: Literal[True]) → Callable[[CommandOrGroupT], CommandOrGroupT]

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

command(command: CommandOrGroupT, *, defer_guilds: Literal[True]) → CommandOrGroupT

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

Parameters:

command – The command class or command group to register with the client.
guilds – The guilds to create the command or group in.
global – Whether the command should be registered globally.
defer_guilds – Whether the guilds to create this command in should be resolved when the client is started. If True, the client’s deferred_registration_callback will be used to resolve which guilds to create the command in. You can also use this to conditionally prevent the command from being registered to any guilds.

Returns:

The registered command or group, unchanged.

Example

loader = lightbulb.Loader()

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

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

See also

register()

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

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 – The priority that this handler should be registered at. Higher priority handlers will be executed first.

listener(*event_types: type[EventT]) → Callable[[Callable['t.Concatenate[EventT, ...]', Awaitable[None]]], Callable[[EventT], Awaitable[None]]][source]¶

Decorator to register a listener with this loader. Also enables dependency injection on the listener callback.

If an hikari.api.event_manager.EventManager instance is not available through dependency injection then adding this loader to the client will fail at runtime.

Parameters:: *event_types – The event class(es) for the listener to listen to.

Example

loader = lightbulb.Loader()

@loader.listener(hikari.MessageCreateEvent)
async def message_create_listener(event: hikari.MessageCreateEvent) -> None:
    ...

async remove_from_client(client: client_.Client) → None[source]¶

Remove the features contained within this loader from the given client. If any single loadable’s unload method raises an exception then the remaining loadables will still be unloaded.

Parameters:: client – The client to remove this loader’s features from.
Returns:: None

task(trigger: tasks.Trigger, /, auto_start: bool = True, max_failures: int = 1, max_invocations: int = -1) → Callable[[tasks.TaskFunc], Task][source]¶

Second order decorator to register a repeating task with this loader. Task functions will have dependency injection enabled on them automatically. Task functions must be asynchronous.

Parameters:

trigger – The trigger function to use to resolve the interval between task executions.
auto_start – Whether the task should be started automatically. This means that if the task is added to the client upon the client being started, the task will also be started; it will also be started if being added to an already-started client.
max_failures – The maximum number of failed attempts to execute the task before it is cancelled. Setting this to a negative number will prevent the task from being cancelled, regardless of how often the task fails.
max_invocations – The maximum number of times the task can be invoked before being stopped. Setting this to a negative number will disable this behaviour, allowing unlimited invocations.

Example

loader = lightbulb.Loader()

@loader.task(lightbulb.uniformtrigger(minutes=1))
async def print_hi() -> None:
    print("HI")