Andrei
8 years ago
8 changed files with 71 additions and 18 deletions
@ -0,0 +1,32 @@ |
|||
# Plugins |
|||
|
|||
Plugins are Disco are a core abstraction which attempt to encapsulate the functionality of your bot into contained modules. To boil it down, commands related to one another, or listeners that control the same functionality should be within the same Plugin. Although it's possible to call and pass data between Plugins, you should generally attempt to avoid it. |
|||
|
|||
## Plugin Lifecycle |
|||
|
|||
### Loading |
|||
|
|||
Plugins are loaded when the Bot is initially created, and when this happens the `Plugin.load` function is called. If the plugin is being reloaded, the call to this function will contain a dictionary of data returned by the previous `unload` call. Using this, you can pass data between loaded instances of your plugin to help aid in seamless reloads. Often plugins will require some level of configuration and setup before running, and this code can be inserted within an overridden version of the load function, as such: |
|||
|
|||
```python |
|||
class ExamplePlugin(Plugin): |
|||
def load(self, ctx): |
|||
super(ExamplePlugin, self).load(ctx) |
|||
setup_database() |
|||
self.data = ctx.get('data', {}) |
|||
``` |
|||
|
|||
The load function of a plugin is guaranteed to only be called once for the instance, when reloading a new instance of the plugin will be created. |
|||
|
|||
### Unloading |
|||
|
|||
Plugins are unloaded in multiple scenarios (shutdown, before a reload, or during an unload), and when this happens the `Plugin.unload` function is called. This function is passed one argument containing a dictionary, which (if the plugin wants) can be filled with information that a future iteration (in the case we're reloading) of the plugin can use to maintain state. Plugins may want to call or save data before being unloaded, and in this case they can override the unload function: |
|||
|
|||
```python |
|||
class ExamplePlugin(Plugin): |
|||
def unload(self, ctx): |
|||
ctx['data'] = self.data |
|||
super(ExamplePlugin, self).unload(ctx) |
|||
``` |
|||
|
|||
During the unload sequence all greenlets which the plugin owns (e.g. greenlets for command or listener callbacks, any spawned with `Plugin.spawn`) are terminated. In the case where command callbacks should continue execution past the unload point (e.g. in the case where a plugin reloads itself), you should pass `oob=True` to the `Plugin.command` decorator. |
|||
@ -1,3 +1,20 @@ |
|||
#!/bin/bash |
|||
echo "Building Autogenerated API Docs" |
|||
pushd .. |
|||
python -m biblio.cli ../disco/.biblio.yaml |
|||
popd |
|||
|
|||
echo "Running Gitbook Build" |
|||
gitbook build |
|||
rsync -avzP _book/* meph:/var/www/disco/ |
|||
|
|||
if [ ! -z "${GH_TOKEN:-}" ]; then |
|||
echo "Deploying to Github Pages" |
|||
pushd _book/ |
|||
git init |
|||
git config user.name "AutoDoc" |
|||
git config user.email "<>" |
|||
git add . |
|||
git commit -m "Generated Documentation" |
|||
git push --force --quiet "https://${GH_TOKEN}@github.com/b1naryth1ef/disco" master:gh-pages |
|||
popd |
|||
fi |
|||
|
|||
@ -1,27 +1,27 @@ |
|||
# Installation and Setup |
|||
|
|||
The easiest way to install the base version of Disco is through Python's [pip](https://pip.pypa.io/en/stable/) utility. To simply install the most minimal version of Disco, simply run: |
|||
|
|||
{% hint style='tip' %} |
|||
If you are a new Python developer, or are unsure what pip even is, try starting [here](https://packaging.python.org/installing/). |
|||
{% endhint %} |
|||
|
|||
The easiest way to install the base version of Disco is through Python's [pip](https://pip.pypa.io/en/stable/) utility. To simply install the most minimal version of Disco, simply run: |
|||
|
|||
```sh |
|||
pip install disco-py |
|||
``` |
|||
|
|||
## Optional Dependencies |
|||
|
|||
Disco also has a set of optional dependencies which add various levels of functionality or support when installed. These can all be installed in a similar fashion to Disco, by simply running: |
|||
Disco provides a set of optional dependencies which add various bits of functionality or performance changes when installed. These can all be installed in a similar fashion to Disco; |
|||
|
|||
```sh |
|||
pip install DEPENDENCY_NAME |
|||
pip install disco[performance] |
|||
``` |
|||
|
|||
| Name | Explanation | |
|||
|---------|------------------| |
|||
| requests[security] | modern/proper SSL implementation, this helps silence some annoying warning messages | |
|||
| ujson | faster json parser, can be used to improve performance | |
|||
| erlpack | ETF parser, only supports Python 2.x but will greatly improve Gateway performance and bandwidth usage | |
|||
| gipc | IPC library for Gevent which adds support for automatic sharding | |
|||
| youtube-dl | adds support for downloading and playing songs from a plethora (including Youtube) of sources | |
|||
| Name | Explanation | Versions | |
|||
|------|-------------|----------| |
|||
| voice | Adds functionality required to connect and use voice | Both | |
|||
| music | Adds the ability to stream and play music from various third party sites | Both | |
|||
| performance | Adds a faster JSON parser (ujson) and an ETF encoding parser | 2.x Only | |
|||
| sharding | Adds a library which is required to enable auto-sharding | 2.x Only | |
|||
| docs | Adds a library required to build this documentation | Both | |
|||
|
|||
Loading…
Reference in new issue