Working with configuration files

This section gives you a quick overview of Confloader library usage.

Loading configuration files

Configuration files can be loaded from files or file descrptors and objects that support file-descriptor-like API (e.g., StringIO). To load a configuration file, you can use the from_file() method on the confloader.ConfDict class:

from confloader import ConfDict

conf = ConfDict.from_file('config.ini')

If the configuration file is blank, missing, contains no section, or has options that are dangling outside sections, or otherwise malformed, you will get a ConfigurationError exception. This exception is available as an attribute on the ConfDict class as convenience:

try:
    conf = ConfDict.from_file('nonexistent.ini')
except ConfDict.ConfigError:
    print('Oh noes!')

Application may specify its own defaults when loading configuration files. This is done by using the defaults argument which must be a dictionary:

conf = ConfDict.from_file('config.ini', defaults={
    'myoption1': 12,
    'myoption2': no
})

If, for some reason, you don’t like type conversions, you can omit type conversion by passing the skip_clean flag:

conf = ConfDict.from_file('config.ini', skip_clean=True)

List extension can be suppressed by using noextend parameter:

conf = ConfDict.from_file('config.ini', noextend=True)

Adding options from configuration files at runtime

The confiuration object, once instantiated, can be further manipulated by calling the import_from_file method on the ConfigDict objects. For example:

conf = ConfDict.from_file('config.ini')
conf.import_from_file('fragment.ini')

This method has two modes. The first mode is the include mode, which overwrites existing options using the options from the specified file. The other mode is the defaults mode which only fills in the blank while leaving existing options intact. The defaults mode is enabled by supplying as_defaults=True argument.

By default, calling import_from_file on a non-existent configuration file will raise the ConfigError exception. This exception can be suppressed by passing the ignore_missing=True argument.

Accessing options

Options are accessed via keys that are a combination of the section name and option name.

[foo]

bar = 1

The bar option from the above example is accessed as config['foo.bar'].

There is a special section named [global]. Options that appear in this section are unprefixed.

[global]

foo = yes

The foo option from the above example is acessed as conf['foo'].