radkii / lightbulb-ext-hecate

File driven wrappers around lightbulb extensions and plugins.

Hecate

File driven wrappers around lightbulb extensions and plugins.

Installation

Hecate can be installed through pip

pip install lightbulb-ext-hecate

First Steps

A pong slash command template for a basic hecate extension can be generated by running

python -m lightbulb.ext.hecate --template REL_PATH_TO_PY

granted a .py extension file already exists in the desired directory.

The following directory structure

.
└── extension.py

will become

.
├── events
│   ├── GuildMessageCreateEvent.py
│   ├── _GuildMessageDeleteEvent.py
├── slash-commands
│   ├── ping.py
│   └── pong_count.py
├── __modify__.py
└── extension.py

where REL_PATH_TO_PY is extension.py

Usage

The structure of a hecate extension file is as follows:

# File: extension.py

# Import the Plugin class
from lightbulb.ext.hecate import Plugin

# Create a Plugin instance (__file__ is necessary to fetch the commands and events in other files)
plugin = Plugin('EXTENSION', __file__)

# Plain lightbulb extension load method
def load(bot):
    bot.add_plugin(plugin)

Adding commands

A command associated with a hecate extension can be added by creating a python file - COMMAND_TYPE/COMMAND_NAME - in the extension directory. COMMAND_TYPE should be one of:

• prefix-commands
• message-commands
• user-commands
• slash-commands

(matching the lightbulb.commands.Command subclass of the same name). Hecate, by default, will interpret the file name COMMAND_NAME as the name of the command (without the extension :P). However, a different name can be set in the contents of the file.

All commands must declare a command async method:

async def command(ctx: lightbulb.Context):
    pass

Command attributes like description, options and name can be set by simply declaring the appropriate variables:

description : str = "Replies with 'Pong!'"
options : list[hecate.Option] = [Option('amount', "Number of times to ping", int)]
name : str = 'ping'

Alternatively, the hecate.Params object can be used. A hecate extension will prioritize any attributes set in the params object.

params = hecate.Params(
    description="Replies with 'Pong!'",
    options=[Option('amount', "Number of times to ping", int)],
    name='ping'
)

Adding events

An event associated with a hecate extension can be added by creating a python file - events/HIKARI_EVENT - in the extension directory. HIKARI_EVENT should be a valid hikari event.

All events must declare an event async method:

async def event(e: hikari.Event):
    pass

Shared attributes

It may be necessary for commands to share attributes, such as in the template. The hecate.Properties object can be used to achieve this. A command/event can request to access a shared attribute, and all the requests will be resolved when the hecate extension loads. The requests are made by means of keyword arguments in the constructor:

# properties.foo and properties.bar will be available in the command/event method
properties = hecate.Properties(foo=0, bar="")

A command/event will not have access to attributes that it didn't specify in the constructor, even if they were requested somewhere else. Requests should have as value None, a falsy value or all hold the same truthy value. The last truthy value found will be the default value for the given attribute, upon resolving.

# File: command1.py
properties = Properties(foo=0)
# File command2.py
properties = Properties(foo=5)
# ...
# OK (properties.foo == 5 for both)

# File: command1.py
properties = Properties(foo=0)
# File command2.py
properties = Properties(foo=0)
# ...
# OK (properties.foo == 0 for both)

# File: command1.py
properties = Properties(foo=3)
# File command2.py
properties = Properties(foo=5)
# ...
# ERROR

The optional argument default_properties on the hecate.Plugin object will, if defined, override all previous logic and set the default value of the given attributes.

plugin = Plugin('EXTENSION', __file__, default_properties={'foo': 5})

Modifiers

Modifiers can be useful to add the same piece of functionality to all commands at once, for example, to debug commands or handle errors. They are declared as async methods in the python file __modify__.py in the extension directory.

Implemented modifiers:

• on_event_error(e_ctx: hecate.EventContext, e: hikari.Event) - called when an event throws an error
• on_command_error(com_ctx: hecate.CommandContext, lightbulb.ctx: Context) - called when a command throws an error
• on_command_enter(com_ctx: CommandContext, ctx: Context) - called before a command
• on_command_exit(com_ctx: CommandContext, ctx: Context) - called after a command

They can also be declared on the hecate.Plugin object, which will override the __modify__.py declaration:

plugin = Plugin('EXTENSION', __file__, on_event_error=func1, on_command_error=func2, ...)

Other features

Prefixing the file name of a command or event with _ will disable it, making the hecate extension ignore the file completely.

Issues

If you find any bugs, issues, or unexpected behaviour while using the library, you should open an issue with details of the problem and how to reproduce if possible. Please also open an issue for any new features you would like to see added.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.