API documentation

class confloader.ConfDict(*args, **kwargs)

Dictionary subclass that is used to hold the parsed configuration options.

ConfDict is instantiated the same way as dicts. For this reason, the paths to configuation files and similar are not passed to the constructor. Instead, you should use the from_file() classmethod.

Because this class is a dictionary, you can use the standard dict API to access and modify the keys. There is a minor difference when accessing key values, though. When using the subscript notation, ConfigurationFormatError is raised instead of KeyError when the key is missing.

exception ConfigurationError

Raised when application is not configured correctly.

exception ConfDict.ConfigurationFormatError(keyerr)

Raised when configuration file is malformed.

ConfDict.configure(path, skip_clean=False, noextend=False)

Configure the ConfDict instance for processing.

The path is a path to the configuration file. skip_clean parameter is a boolean flag that suppresses type conversion during parsing. noextend flag suppresses list extension.

classmethod ConfDict.from_file(path, skip_clean=False, noextend=False, defaults={})

Load the values from the specified file. The skip_clean flag is used to suppress type conversion. noextend flag suppresses list extension.

You may also specify default options using the defaults argument. This argument should be a dict. Values specified in this dict are overridden by the values present in the configuration file.

ConfDict.get_option(section, name, default=None)

Returns a single configuration option that matches the given section and option names. Optional default value can be specified using the default parameter, and this value is returned when the option is not found.

As with get_section() method, this method operates on the parsed configuration file rather than dictionary data.

ConfDict.get_section(name)

Returns an iterable containing options for a given section. This method does not return the dict values, but instead uses the underlying parser object to retrieve the values from the parsed configuration file.

ConfDict.import_from_file(path, as_defaults=False, ignore_missing=False)

Imports additional options from specified file. The as_default flag can be used to cause the options to only be imported if they are not already present. The ignore_missing suppresses the ConfigurationError exception when the specified file is missing.

ConfDict.load()

Parses and loads the configuration data. This method will trigger a sequence of operations:

  • initialize the parser, and load and parse the configuration file
  • check the configuration file
  • perform preprocessing (check for references to other files)
  • process the sections
  • process any includes or extensions

Any problems with the referenced defaults and includes will propagate to this call.

Note

Using this method for reloading the configuration is not recommended. Instead, create a new instance using the from_file() method.

ConfDict.sections

Returns an iterable containing the names of sections. This method uses the underlying parser object and does not work with the dict values.

ConfDict.setdefaults(other)

This method is a counterpart of the update() method and works like setdefault(). The other argument is a dict or dict-like object, whose key-value pairs are added to the ConfDict object if the key does not exist already.

exception confloader.ConfigurationError

Raised when application is not configured correctly.

exception confloader.ConfigurationFormatError(keyerr)

Raised when configuration file is malformed.

confloader.extend_key(d, key, val)

Extends a dictionary key with a specified iterable. If the key does not exist, it is assigned a list before extending. If the key exists, but maps to a non-list value, the key value is convereted to a list before being extended.

confloader.get_compound_key(section, key)

Return the key that will be used to look up configuration options. Except for the global keys, the compoint key is in <section>.<option> format.

confloader.get_config_path(default=None)

Attempt to obtain and return a path to configuration file specified by --conf command line argument, and fall back on specified default path. Default value is None.

confloader.make_list(val)

If the value is not a list, it is converted to a list. Iterables like tuple and list itself are converted to lists, whereas strings, integers, and other values are converted to a list whose sole item is the original value.

confloader.parse_key(section, key)

Given section name and option name (key), return a compound key and a flag that is True if the option marks an extension.

confloader.parse_size(size)

Parses size with B, KB, MB, or GB suffix and returns in size bytes. The suffix is not metric but based on powers of 1024. The suffix is also case-insensitive.

confloader.parse_value(val)

Detect value type and coerce to appropriate Python type. The input must be a string and the value’s type is derived based on it’s formatting. The following types are supported:

  • boolean (‘yes’, ‘no’, ‘true’, ‘false’, case-insensitive)
  • None (‘null’, ‘none’, case-insensitive)
  • integer (any number of digits, optionally prefixed with minus sign)
  • float (digits with floating point, optionally prefix with minus sign)
  • byte sizes (same as float, but with KB, MB, or GB suffix)
  • lists (any value that sarts with a newline)

Other values are returned as is.