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)¶ Parameters: - 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 anOSError
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 will only load config files which have the same major version. On mismatch an error is logged and the file is skipped. If the minor version differs the file will be loaded, but issue a warning log. Version numbers are parsed usingdistutils.version.StrictVersion
-
check_file
(filename)¶ Check if
filename
can be read. Will return boolean which is True if the file can be read, False otherwise.
-
get
(section, option, **kwargs)¶ Overrides
configparser.ConfigParser.get()
.In addition to
section
andoption
, this call takes an optionaldefault
value. This behaviour works in addition to theconfigparser.ConfigParser
default mechanism. Note that a default value fromConfigParser
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 optiontest
, then this value will be returned for bothsection1.test
and forsection2.test
. Using the default on theget
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
.Parameters: - section – The config file section.
- option – The option name.
- kwargs – These keyword args are passed through to
configparser.ConfigParser.get()
.
-
get_xdg_dirs
()¶ 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).
-
get_xdg_home
()¶ 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
toTrue
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.Parameters: - reload – if set to
True
, the existing values are cleared before reloading. - require_load – If set to
True
this will raise aIOError
if no config file has been found to load.
- reload – if set to
-
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.
Parameters: - 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.-
check_file
(filename)¶ Overrides
Config.check_file()
-