9. Configuration

9.1. Plugin configuration through the built-in !config command

Errbot can keep a simple python object for the configuration of your plugin. This avoids the need for admins to configure settings in some kind of configuration file, instead allowing configuration to happen directly through chat commands.

In order to enable this feature, you need to provide a configuration template (ie. a config example) by overriding the get_configuration_template() method. For example, a plugin might request a dictionary with 2 entries:

from errbot import BotPlugin

class PluginExample(BotPlugin):
    def get_configuration_template(self):
        return {'ID_TOKEN': '00112233445566778899aabbccddeeff',
                'USERNAME':'changeme'}

With this in place, an admin will be able to request the default configuration template with !plugin config PluginExample. He or she could then give the command !plugin config PluginExample {‘ID_TOKEN’ : ‘00112233445566778899aabbccddeeff’, ‘USERNAME’:’changeme’} to enable that configuration.

It will also be possible to recall the configuration template, as well as the config that is actually set, by issuing !plugin config PluginExample again.

Within your code, the config that is set will be in self.config:

@botcmd
def mycommand(self, mess, args):
    # oh I need my TOKEN !
    token = self.config['ID_TOKEN']

Warning

If there is no configuration set yet, self.config will be None.

9.2. Supplying partial configuration

Sometimes you want to allow users to only supply a part of the configuration they wish to override from the template instead of having to copy-paste and modify the complete entry.

This can be achieved by overriding configure():

from itertools import chain

CONFIG_TEMPLATE = {'ID_TOKEN': '00112233445566778899aabbccddeeff',
                   'USERNAME':'changeme'}

def configure(self, configuration):
    if configuration is not None and configuration != {}:
        config = dict(chain(CONFIG_TEMPLATE.items(),
                            configuration.items()))
    else:
        config = CONFIG_TEMPLATE
    super(PluginExample, self).configure(config)

What this achieves is that it creates a Python dictionary object which contains all the values from our CONFIG_TEMPLATE and then updates that dictionary with the configuration received when calling the !config command. !config must be passed a dictionary for this to work.

If you wish to reset the configuration to its defaults all you need to do is pass an empty dictionary to !config.

You’ll now also need to override get_configuration_template() and return the CONFIG_TEMPLATE in that function:

def get_configuration_template(self):
    return CONFIG_TEMPLATE

9.3. Using custom configuration checks

By default, Errbot will check the supplied configuration against the configuration template, and raise an error if the structure of the two doesn’t match.

You need to override the check_configuration() method if you wish do some other form of configuration validation. This method will be called automatically when an admin configures your plugin with the !config command.

Warning

If there is no configuration set yet, it will pass None as parameter. Be mindful of this situation.

Using the partial configuration trick as shown above requires you to override check_configuration(), so at a minimum you’ll need this:

def check_configuration(self, configuration):
    pass

We suggest that you at least do some validation instead of nothing but that is up to you.