Configuration functionality

The config object provides a simplified to access Sopel’s configuration file. The sections of the file are attributes of the object, and the keys in the section are attributes of that. So, for example, the eggs attribute in the [spam] section can be accessed from config.spam.eggs.

Section definitions (see “Section configuration sections” below) can be added to the config object with define_section. When this is done, only the defined keys will be available. A section can not be given more than one definition. The [core] section is defined with CoreSection when the object is initialized.

New in version 6.0.0.

class sopel.config.Config(filename, validate=True)
class ConfigSection(name, items, parent)

Represents a section of the config file.

Contains all keys in thesection as attributes.

get_list(name)
Config.add_section(name)

Add a section to the config file.

Returns False if already exists.

Config.define_section(name, cls_, validate=True)

Define the available settings in a section.

cls_ must be a subclass of StaticSection. If the section has already been defined with a different class, ValueError is raised.

If validate is True, the section’s values will be validated, and an exception raised if they are invalid. This is desirable in a module’s setup function, for example, but might not be in the configure function.

Config.homedir

An alias to config.core.homedir

Config.option(question, default=False)

Ask “y/n” and return the corresponding boolean answer.

Show user in terminal a “y/n” prompt, and return true or false based on the response. If default is passed as true, the default will be shown as [y], else it will be [n]. question should be phrased as a question, but without a question mark at the end.

Config.save()

Save all changes to the config file.

exception sopel.config.ConfigurationError(value)

Exception type for configuration errors

Types for creating section definitions.

A section definition consists of a subclass of StaticSection, on which any number of subclasses of BaseValidated (a few common ones of which are available in this module) are assigned as attributes. These descriptors define how to read values from, and write values to, the config file.

As an example, if one wanted to define the [spam] section as having an eggs option, which contains a list of values, they could do this:

>>> class SpamSection(StaticSection):
...     eggs = ListAttribute('eggs')
...
>>> SpamSection(config, 'spam')
>>> print(config.spam.eggs)
[]
>>> config.spam.eggs = ['goose', 'turkey', 'duck', 'chicken', 'quail']
>>> print(config.spam.eggs)
['goose', 'turkey', 'duck', 'chicken', 'quail']
>>> config.spam.eggs = 'herring'
Traceback (most recent call last):
    ...
ValueError: ListAttribute value must be a list.
class sopel.config.types.BaseValidated(name, default=None)

The base type for a descriptor in a StaticSection.

configure(prompt, default, parent, section_name)

With the prompt and default, parse and return a value from terminal.

parse(value)

Take a string from the file, and return the appropriate object.

Must be implemented in subclasses.

serialize(value)

Take some object, and return the string to be saved to the file.

Must be implemented in subclasses.

class sopel.config.types.ChoiceAttribute(name, choices, default=None)

A config attribute which must be one of a set group of options.

Currently, the choices can only be strings.

parse(value)
serialize(value)
class sopel.config.types.FilenameAttribute(name, relative=True, directory=False, default=None)

A config attribute which must be a file or directory.

configure(prompt, default, parent, section_name)

With the prompt and default, parse and return a value from terminal.

parse(main_config, this_section, value)
serialize(main_config, this_section, value)
class sopel.config.types.ListAttribute(name, strip=True, default=None)

A config attribute containing a list of string values.

Values are saved to the file as a comma-separated list. It does not currently support commas within items in the list. By default, the spaces before and after each item are stripped; you can override this by passing strip=False.

configure(prompt, default, parent, section_name)
parse(value)
serialize(value)
class sopel.config.types.NO_DEFAULT

A special value to indicate that there should be no default.

class sopel.config.types.StaticSection(config, section_name, validate=True)

A configuration section with parsed and validated settings.

This class is intended to be subclassed with added ValidatedAttributes.

configure_setting(name, prompt, default=<class 'sopel.config.types.NO_DEFAULT'>)

Return a validated value for this attribute from the terminal.

prompt will be the docstring of the attribute if not given.

If default is passed, it will be used if no value is given by the user. If it is not passed, the current value of the setting, or the default value if it’s unset, will be used. Note that if default is passed, the current value of the setting will be ignored, even if it is not the attribute’s default.

class sopel.config.types.ValidatedAttribute(name, parse=None, serialize=None, default=None)
configure(prompt, default, parent, section_name)
parse(value)
serialize(value)

The [core] configuration section

class sopel.config.core_section.CoreSection(config, section_name, validate=True)

The config section used for configuring the bot itself.

admin_accounts

The list of accounts (other than the owner’s) who can administer the bot.

This should not be set for networks that do not support IRCv3 account capabilities.

admins

The list of people (other than the owner) who can administer the bot

auth_method

The method to use to authenticate with the server.

Can be nickserv, authserv, Q, sasl, or server.

auth_password

The password to use to authenticate with the server.

auth_target

The user to use for nickserv authentication, or the SASL mechanism.

May not apply, depending on auth_method. Defaults to NickServ for nickserv auth, and PLAIN for SASL auth.

auth_username

The username/account to use to authenticate with the server.

May not apply, depending on auth_method.

bind_host

Bind the connection to a specific IP

ca_certs

The path of the CA certs pem file

channels

List of channels for the bot to join when it connects

db_filename

The filename for Sopel’s database.

default_time_format

The default format to use for time in messages.

default_timezone

The default timezone to use for time in messages.

enable

A whitelist of the only modules you want to enable.

exclude

A list of modules which should not be loaded.

extra

A list of other directories you’d like to include modules from.

help_prefix

The prefix to use in help

homedir

The directory in which various files are stored at runtime.

By default, this is the same directory as the config. It can not be changed at runtime.

host

The server to connect to.

host_blocks

A list of hostmasks which Sopel should ignore.

Regular expression syntax is used

log_raw

Whether a log of raw lines as sent and recieved should be kept.

logdir

Directory in which to place logs.

logging_channel

The channel to send logging messages to.

logging_level

The lowest severity of logs to display.

modes

User modes to be set on connection.

name

The “real name” of your bot for WHOIS responses.

nick

The nickname for the bot

nick_blocks

A list of nicks which Sopel should ignore.

Regular expression syntax is used.

not_configured

For package maintainers. Not used in normal configurations.

This allows software packages to install a default config file, with this set to true, so that the bot will not run until it has been properly configured.

owner

The IRC name of the owner of the bot.

owner_account

The services account name of the owner of the bot.

This should only be set on networks which support IRCv3 account capabilities.

pid_dir

The directory in which to put the file Sopel uses to track its process ID.

You probably do not need to change this unless you’re managing Sopel with systemd or similar.

port

The port to connect on.

prefix

The prefix to add to the beginning of commands.

It is a regular expression (so the default, \., means commands start with a period), though using capturing groups will create problems.

reply_errors

Whether to message the sender of a message that triggered an error with the exception.

throttle_join

Slow down the initial join of channels to prevent getting kicked.

Sopel will only join this many channels at a time, sleeping for a second between each batch. This is unnecessary on most networks.

timeout

The amount of time acceptable between pings before timing out.

use_ssl

Whether to use a SSL secured connection.

user

The “user” for your bot (the part before the @ in the hostname).

verify_ssl

Whether to require a trusted SSL certificate for SSL connections.