Extensions

Extensions are used to assist in splitting up your project into multiple files. A Python file is considered an extension if it declares one or more variables that are instances of lightbulb.Loaders. Upon loading an extension into the client, it will search for any loaders and apply them - adding commands, listeners, etc.

---

Loaders

A loader is the client’s ‘entry point’ for an extension.

In a new Python file, you can create a loader like so:

import lightbulb

loader = lightbulb.Loader()

This file is now an ‘extension’. Next you probably want to add some functionality that can be added when the extension is loaded. Currently, loaders support commands, listeners and error handlers natively - but support can easily be added for loading of other items.

Commands

@loader.command
class YourCommand(
    ...
):
    ...

Listeners

@loader.listener(...)
async def your_listener(...) -> None:
    ...

Error Handlers

@loader.error_handler
async def your_error_handler(...) -> bool:
    ...

Tip

Other items can be linked to loaders by implementing a custom lightbulb.Loadable that enables the desired behaviour. This loadable can be added to a given loader using the Loader.add() method.

---

Loading Extensions

Lightbulb provides two methods to help with loading extensions into the client. These are Client.load_extensions() - loading one or more extensions using the import path, and Client.load_extenions_from_package() - loading multiple extensions using an imported package that contains the extension files.

Warning

Unlike V2, the load extensions methods are now asynchronous. This means that you will need an event loop available in order to load them. It is recommended that you do this during a startup listener. It is important that you load any extensions before starting the client, otherwise any commands may not be synced with Discord.

Example file structure:

extensions/
├── __init__.py
├── echo.py
└── ping.py

load_extensions()

This method takes the import path for any extensions you want to load. Given the example file structure, this would look like the following:

await client.load_extensions("extensions.echo", "extensions.ping")

load_extensions_from_package()

This method takes an imported package containing the extensions you want to load. Given the example file structure, this would look like the following:

import extensions

await client.load_extensions_from_package(extensions)

If the recursive flag is set to True, this method will also search through subpackages for extensions. This defaults to False.

---

Example Usage

import hikari
import lightbulb

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


@bot.listen(hikari.StartingEvent)
async def on_starting(_: hikari.StartingEvent) -> None:
    # Load any extensions
    await client.load_extensions("extensions.foo", "extensions.bar", "extensions.baz")
    # Start the bot - make sure commands are synced properly
    await client.start()


bot.run()