This section gives you a quick overview of Confloader library usage.
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)
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.
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']
.