config_resolver API

config_resolver provides a Config class, which looks up common locations for config files and loads them if found. It provides a framework independed way of handling configuration files. Additional care has been taken to allow the end-user of the application to override this lookup process.

class config_resolver.Config(group_name, app_name, search_path=None, filename='app.ini', require_load=False, version=None, **kwargs)
  • group_name – an application group (f. ex.: your company name)
  • app_name – an application identifier (f.ex.: the application module name)
  • search_path – if specified, set the config search path to the given value. The path can use OS specific separators (f.ex.: : on posix, ; on windows) to specify multiple folders. These folders will be searched in the specified order. The config files will be loaded incrementally. This means that the each subsequent config file will extend/override existing values. This means that the last file will take precedence.
  • filename – if specified, this can be used to override the configuration filename.
  • require_load – If this is set to True, creation of the config instance will raise an OSError if not a single file could be loaded.
  • version – If specified (f.ex.: version='2.0'), this will create a versioned config instance. A versioned instance may raise a IncompatibleVersion exception if the major version differs from the one found in the config file. If left to the default, no version checking is performed. Version numbers are parsed using distutils.version.StrictVersion

Check if filename can be read. Will return a 2-tuple containing a boolean if the file can be read, and a string containing the cause (empty if the file is readable).

This mainly exists to make it possible to override this with different rules.

get(section, option, **kwargs)

Overrides configparser.ConfigParser.get().

In addition to section and option, this call takes an optional default value. This behaviour works in addition to the configparser.ConfigParser default mechanism. Note that a default value from ConfigParser takes precedence.

The reason this additional functionality is added, is because the defaults of configparser.ConfigParser are not dependent on sections. If you specify a default for the option test, then this value will be returned for both section1.test and for section2.test. Using the default on the get call gives you more fine-grained control over this.

Also note, that if a default value was used, it will be logged with level logging.DEBUG.


Returns a list of paths specified by the XDG_CONFIG_DIRS environment variable or the appropriate default.

The list is sorted by precedence, with the most important item coming last (required by the existing config_resolver logic).


Returns the value specified in the XDG_CONFIG_HOME environment variable or the appropriate default.

load(reload=False, require_load=False)

Searches for an appropriate config file. If found, loads the file into the current instance. This method can also be used to reload a configuration. Note that you may want to set reload to True to clear the configuration before loading in that case. Without doing that, values will remain available even if they have been removed from the config files.

  • reload – if set to True, the existing values are cleared before reloading.
  • require_load – If set to True this will raise a IOError if no config file has been found to load.
read(*args, **kwargs)


In addition to the default read method, this does version checking if this instance has been created with a version number. It uses distutils.version.StrictVersion for version parsing.

class config_resolver.ConfigResolverBase(defaults=None, dict_type=<class 'collections.OrderedDict'>, allow_no_value=False)

A default “base” object simplifying Python 2 and Python 3 compatibility.

exception config_resolver.IncompatibleVersion

This exception is raised if a config file is loaded which has a different major version number than expected by the application.

exception config_resolver.NoVersionError

This exception is raised if the application expects a version number to be present in the config file but does not find one.

class config_resolver.PrefixFilter(prefix, separator=' ')

A logging filter which prefixes each message with a given text.

  • prefix – The log prefix.
  • separator – A string to put between the prefix and the original log message.
class config_resolver.SecuredConfig(group_name, app_name, search_path=None, filename='app.ini', require_load=False, version=None, **kwargs)

A subclass of Config which will refuse to load config files which are read able by other users than the owner.


Overrides Config.check_file()