Dev Config

Sibyl uses the sibyl.lib.config.Config class to manage config options. At its core, it uses python's ConfigParser.SafeConfigParser to read the file and then executes additional parsing and validation functions as needed. Users can manage their config file with the config chat command.

Overview

Loading options from the config file looks like this during bot startup:

1. Load config once to get the values of the protocols and cmd_dir options
2. Register new config options from protocols and plugins via @botconf
3. Load the config file again to get user-defined values
4. Check for critical errors (e.g. duplicates, missing options with req set)

And this is what actually happens inside the Config object when loading the config file:

1. Use ConfigParser.SafeConfigParser to get a dict respresentation of the options and values
2. Check black and white listing
3. Execute parse functions (all values start as str, but maybe we want them to be e.g. int)
4. Execute valid functions (e.g. check if a file exists)
5. Execute post functions (perform checks that depend on other config options)
6. Return critical errors

Adding Config Options

Plug-ins and protocols should add options using the @botconf decorator. Although the Config class does have an add_opt() method, it generally should not be called while the bot is running. As noted in the linked article, @botconf functions can specify several different options and functions to control how config options are loaded.

Methods

The log method will commonly be used by plug-ins inside parse, valid, and post functions. The first group may be used by plug-ins, although this is unlikely since their functionality is mostly captured by the existing general.config chat command. The second group of functions should generally not be called by plugins.

default_opt(opt)      # reset an option to its default value
log(lvl,msg)          # queue/log a message to the bot's log file
reload_opt(opt)       # reload the specified option from the config file
set_opt(opt,val)      # update the value of an option in the bot
save_opt(opt,val,msg) # as set_opt(), but also change the value in the config file

add_opt(opt,ns)       # add a config option for controlling something in the bot
add_opts(opts,ns)     # add several config options
clear_log()           # clear the Config's internal log queue
get_default()         # return the default values for all registered options
process_log()         # log queued messages to Sibyl's log
reload(opt,log)       # load config options and catch errors
write_default_conf()  # write a config file with all default values
__bwfilter(opts)      # check opts against their white and black lists
__init__()            # initialise the object
__is_opt_line(line)   # check if a line in the config file is part of an option
__parse(opts)         # run all parse functions on the given dict
__post(opts)          # run all post functions on the given dict
__read()              # read values via ConfigParser.SafeConfigParser
__update(opt)         # helper function for reload() to run hooks
__validate(opts)      # run all valid functions on the given dict

Parse Methods

These are used to translate option values from str to something else. These functions raise an exception if parsing fails. The first group will likely be helpful to developers. The second group are used for specific built-in config options and will generally not be useful in other contexts.

parse_bool(opt,val)       # return a bool (from 'True' or 'False')
prase_float(opt,val)      # return a float
parse_int(opt,val)        # return an int
parse_log(opt,val)        # parse logging module levels (e.g. 'info' = logging.INFO)
parse_pass(opt,val)       # return a sibyl.lib.password.Password

parse_admin(opt,val)      # return a list of protocols specified as "admin"
parse_plugins(opt,val)    # return a list of plugins (used by 'enable' and 'disable')
parse_protocols(opt,val)  # return a dict of protocol names and Protocol classes
parse_rename(opt,val)     # return a dict of renamed chat commands
parse_rooms(opt,val)      # return a dict of rooms to join
parse_bw(opt,val)         # return a list of black/white entries

Validate Methods

These are used to make certain the value from the parse function makes sense. These functions return True or False depending on the result of the validation. They must not raise exceptions. The first group will likely be helpful to developers. The second group are used for specific built-in config options and will generally not be useful in other contexts.

valid_dir(s)        # return True if the directory exists
valid_ip(s)         # return True if the string is a valid IP address
valid_nump(num)     # return True if the number is >= 0
valid_rfile(s)      # return True if we can read the file
valid_wfile(s)      # return True if we can write to the file

valid_admin(protos) # return True if every protocol is loaded via the "protocols" opt

FakeSecHead Class

This class is used to modify the behvior of python's ConfigParser module. Normally, every config option must be in a section e.g. [Global]. To ignore section headers, Sibyl treats the entire config file as if it was under a single section header called [dummy] using the FakeSecHead class. Behavior implemented using this StackOverflow answer.