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.


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.


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.

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.


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

Must be implemented in subclasses.


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.

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)
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)

The [core] configuration section

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

The config section used for configuring the bot itself.


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.


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


The method to use to authenticate with the server.

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


The password to use to authenticate with the server.


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.


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

May not apply, depending on auth_method.


Bind the connection to a specific IP


The path of the CA certs pem file


List of channels for the bot to join when it connects


The filename for Sopel’s database.


The default format to use for time in messages.


The default timezone to use for time in messages.


A whitelist of the only modules you want to enable.


A list of modules which should not be loaded.


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


The prefix to use in help


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.


The server to connect to.


A list of hostmasks which Sopel should ignore.

Regular expression syntax is used


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


Directory in which to place logs.


The channel to send logging messages to.


The lowest severity of logs to display.


User modes to be set on connection.


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


The nickname for the bot


A list of nicks which Sopel should ignore.

Regular expression syntax is used.


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.


The IRC name of the owner of the bot.


The services account name of the owner of the bot.

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


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.


The port to connect on.


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.


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


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.


The amount of time acceptable between pings before timing out.


Whether to use a SSL secured connection.


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


Whether to require a trusted SSL certificate for SSL connections.