-
Notifications
You must be signed in to change notification settings - Fork 2
Plugins
Plugins are Python modules that are loaded in the main task before networks are initialized.
Plugins can provide additional IRC-related functionality (IRCv3, CTCP, DCC, ...) or bot features that are exposed to users (command triggers, auto-op, flood-protection ...). Furthermore, plugins can provide features for other plugins.
Plugins may be provided:
- in a
pluginssub-package ofshanghai - in a folder that is referenced in the configuration
Plugins that are found later in the discovery process override references to existing plugins before they are loaded. This makes it easy to patch plugins from the default distribution with custom variants.
Plugin names are determined by the module name. Due to the override behavior described above, plugin names must be unique or they will override the previously found plugin.
All plugins will be added to the shanghai.plugins package
for other plugins to be imported.
The Shanghai core operates on an event queue and (almost) all events are exposed to plugins in the for of event hooks.
The different event hooks include:
- fundamental events such as establishing or losing connection or re-loading configuration (by identifier) [cannot be consumed]
- any server message (all; by command name/reply code)
- any client message (all; by command name)
- custom plugin-emitted messages (all; by identifier)
Plugins can intercept these events, process them and either pass them along or consume them in the process. In the case of consumption, neither other plugins nor the Shanghai core are able to receive said event. Additionally, plugins may generate events on their own, which will go through the entire event handling process again. Generated events will store information about the event they have been generated from, thus forming a so-called "event chain". A single hook may elect not to be called twice for the same event chain.
On registering a hook, a priority (TODO enum or signed 0-based int) may be provided. Hooks will be grouped by their priority. These groups will be called in a specific order, but within the same group call order is not deterministic. Furthermore, a consumed event will only be consumed for all groups following the current group, meaning all hooks in the same priority group will be guaranteed to either receive the event or nothing.
Plugins may wish to provide functionality to other plugins.
For example,
a cmd plugin may provide features for "trigger-based" plugins
that only operate on an IRC message
starting with !trigger.
For this reason,
plugins are exposed in the shanghai.plugins package
under their module name,
e.g. shanghai.plugins.cmd.
Plugins can have arbitrary serializable configuration entries, storable in the main YAML configuration file. This configuration will be managed by the Shanghai core and will feature a global configuration, network- and channel-specific overrides as well as an enable/disable flag in the same places. If a plugin is not enabled for a specific context, its event hooks will be ignored and not be called.
TODO exact configuration loading process to be determined
Plugins can depend on other plugins or other Python packages.
Plugins can list a number of plugin dependencies as a module-level variable/attribute. This list will be read by the plugin loader before executing the module itself.
If a plugin dependency cannot be satisfied, the plugin will not be loaded and an error message is emitted instead.
Dependencies chains cannot contain cycles and must form a linear tree.
TODO
Plugins can depend on other Python packages as they are made available on pypi.
TODO (?)
TODO (not a priority)