Configuration functionality#

The description of config below is a quick guide to the basic structure of configuration settings in Sopel. Consult the config.types module for more specific information about the available kinds of options, and config.core_section for examples of how the different setting types are practically used.

sopel.config#

Sopel’s configuration module.

The Config object provides an interface to access Sopel’s configuration file. It exposes the configuration’s sections through its attributes as objects, which in turn expose their directives through their attributes.

For example, this is how to access core.nick on a Config object:

>>> from sopel import config
>>> settings = config.Config('/sopel/config.cfg')
>>> settings.core.nick
'Sopel'

The configuration file being:

[core]
nick = Sopel
host = irc.libera.chat
use_ssl = true
port = 6697
owner = dgw
channels =
    "#sopel"

A section can be represented by a subclass of StaticSection; for example a [spam] section with eggs and bacon can be defined like this:

from sopel import config

class SpamSection(config.types.StaticSection):
    eggs = config.types.ListAttribute('eggs')
    bacon = config.types.ValidatedAttribute('bacon')

The [core] section itself is represented by the CoreSection class, which is a subclass of StaticSection. It is automatically added when the Config object is instantiated; it uses Config.define_section() for that purpose.

New in version 6.0.0.

class sopel.config.Config(filename, validate=True)#

The bot’s configuration.

Parameters:

filename (str) – the configuration file to load and use to populate this Config instance
validate (bool) – if True, validate values in the [core] section when it is loaded (optional; True by default)

The configuration object will load sections (see ConfigSection) from the file at filename during initialization. Calling save() writes any runtime changes to the loaded settings back to the same file.

Only the [core] section (see CoreSection) is added and made available by default; it is the only section required for Sopel to run. All other sections must be defined later, by the code that needs them, using define_section().

class ConfigSection(name, items, parent)#

Represents a section of the config file.

Parameters:

name (str) – name of this section
items (iterable of two-item tuples) – key-value pairs
parent (Config) – this section’s containing object

Contains all keys in the section as attributes.

add_section(name)#

Add a new, empty section to the config file.

Parameters:: name (str) – name of the new section
Returns:: None if successful; False if a section named name already exists

Note

Plugin authors very rarely want or need to use this method.

You will almost always want to define (and optionally validate values within) a section with specific attributes using define_section() and a child class of StaticSection.

Important

The section’s name SHOULD follow snake_case naming rules:

use only lowercase letters, digits, and underscore (_)
SHOULD NOT start with a digit

Deviations from snake_case can break the following operations:

accessing the section from Python code using the Config object’s attributes
overriding the section’s values using environment variables

basename#

The config’s base filename, i.e. the filename without the extension.

If the filename is libera.config.cfg, then the basename will be libera.config.

The config’s basename is useful as a component of log file names, for example.

define_section(name, cls_, validate=True)#

Define the available settings in a section.

Parameters:

name (str) – name of the new section
cls_ (subclass of StaticSection) – class defining the settings within the section
validate (bool) – whether to validate the section’s values (optional; defaults to True)

Raises:

ValueError – if the section name has been defined already with a different cls_

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

Important

The section’s name SHOULD follow snake_case naming rules:

use only lowercase letters, digits, and underscore (_)
SHOULD NOT start with a digit

Deviations from snake_case can break the following operations:

accessing the section from Python code using the Config object’s attributes
overriding the section’s values using environment variables

filename#: The config object’s associated file.

get#: Shortcut to parser.get.

get_defined_sections()#

Retrieve all defined static sections of this configuration.

Returns:: all instances of StaticSection defined for this configuration file
Return type:: list

When a plugin defines a section (using define_section()), it associates a StaticSection for the section. This method allows to retrieve these instances of StaticSection, and only these.

New in version 7.1.

property homedir#

The config file’s home directory.

If the core.homedir setting is available, that value is used. Otherwise, the default homedir is the directory portion of the Config’s filename.

option(question, default=False)#

Ask the user a “y/n” question.

Parameters:

question (str) – the question to ask the user
default (bool) – True to show [y] as the default choice; False to show [n] (optional; defaults to False)

Returns:

the Boolean value corresponding to the user’s choice

Return type:

bool

This will show a “y/n” prompt in the user’s terminal, and return True or False based on the response. question should be phrased as a question, but without a question mark at the end.

parser#: The configuration parser object that does the heavy lifting.

See also

Python’s built-in configparser module and its RawConfigParser class.

save()#: Write all changes to the config file.

Note

Saving the config file will remove any comments that might have existed, as Python’s configparser ignores them when parsing.

This will become less and less important as we continue to improve Sopel’s tools for making automated changes to config files and eliminate most users’ need to ever manually edit the text, but it’s still worth keeping in mind.

exception sopel.config.ConfigurationError(value)#

Exception type for configuration errors.

Parameters:: value (str) – a description of the error that has occurred

exception sopel.config.ConfigurationNotFound(filename)#

Exception type for use when the configuration file cannot be found.

Parameters:: filename (str) – file path that could not be found

filename#: Path to the configuration file that could not be found.