Package: lightbulb-ext-hecate
HecateFile driven wrappers around lightbulb extensions and plugins.InstallationHecate can be installed throughpippipinstalllightbulb-ext-hecateFirst StepsA pong slash command template for a basic hecate extension can be generated by runningpython-mlightbulb.ext.hecate--templateREL_PATH_TO_PYgranted a .py extension file already exists in the desired directory.The following directory structure.
└──extension.pywill become.
├──events
│├──GuildMessageCreateEvent.py
│├──_GuildMessageDeleteEvent.py
├──slash-commands
│├──ping.py
│└──pong_count.py
├──__modify__.py
└──extension.pywhereREL_PATH_TO_PYisextension.pyUsageThe structure of a hecate extension file is as follows:# File: extension.py# Import the Plugin classfromlightbulb.ext.hecateimportPlugin# Create a Plugin instance (__file__ is necessary to fetch the commands and events in other files)plugin=Plugin('EXTENSION',__file__)# Plain lightbulb extension load methoddefload(bot):bot.add_plugin(plugin)Adding commandsA command associated with a hecate extension can be added by creating a python file -COMMAND_TYPE/COMMAND_NAME- in the extension directory.COMMAND_TYPEshould be one of:prefix-commandsmessage-commandsuser-commandsslash-commands(matching thelightbulb.commands.Commandsubclass of the same name).
Hecate, by default, will interpret the file nameCOMMAND_NAMEas 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 acommandasync method:asyncdefcommand(ctx:lightbulb.Context):passCommand attributes likedescription,optionsandnamecan 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, thehecate.Paramsobject 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 eventsAn event associated with a hecate extension can be added by creating a python file -events/HIKARI_EVENT- in the extension directory.HIKARI_EVENTshould be a valid hikari event.All events must declare aneventasync method:asyncdefevent(e:hikari.Event):passShared attributesIt may be necessary for commands to share attributes, such as in the template. Thehecate.Propertiesobject 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 methodproperties=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 valueNone, 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.pyproperties=Properties(foo=0)# File command2.pyproperties=Properties(foo=5)# ...# OK (properties.foo == 5 for both)# File: command1.pyproperties=Properties(foo=0)# File command2.pyproperties=Properties(foo=0)# ...# OK (properties.foo == 0 for both)# File: command1.pyproperties=Properties(foo=3)# File command2.pyproperties=Properties(foo=5)# ...# ERRORThe optional argumentdefault_propertieson thehecate.Pluginobject will, if defined, override all previous logic and set the default value of the given attributes.plugin=Plugin('EXTENSION',__file__,default_properties={'foo':5})ModifiersModifiers 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__.pyin the extension directory.Implemented modifiers:on_event_error(e_ctx: hecate.EventContext, e: hikari.Event)- called when an event throws an erroron_command_error(com_ctx: hecate.CommandContext, lightbulb.ctx: Context)- called when a command throws an erroron_command_enter(com_ctx: CommandContext, ctx: Context)- called before a commandon_command_exit(com_ctx: CommandContext, ctx: Context)- called after a commandThey can also be declared on thehecate.Pluginobject, which will override the__modify__.pydeclaration:plugin=Plugin('EXTENSION',__file__,on_event_error=func1,on_command_error=func2,...)Other featuresPrefixing the file name of a command or event with_will disable it, making the hecate extension ignore the file completely.IssuesIf 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.ContributingPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.