config_resolver.core module

Core functionality of config_resolver

class config_resolver.core.ConfigID(group, app)

Bases: tuple

app

Alias for field number 1

group

Alias for field number 0

class config_resolver.core.FileReadability(is_readable, filename, reason, version)

Bases: tuple

filename

Alias for field number 1

is_readable

Alias for field number 0

reason

Alias for field number 2

version

Alias for field number 3

class config_resolver.core.LookupMetadata(active_path, loaded_files, config_id, prefix_filter)

Bases: tuple

active_path

Alias for field number 0

config_id

Alias for field number 2

loaded_files

Alias for field number 1

prefix_filter

Alias for field number 3

class config_resolver.core.LookupResult(config, meta)

Bases: tuple

config

Alias for field number 0

meta

Alias for field number 1

config_resolver.core.effective_filename(config_id, config_filename)

Returns the filename which is effectively used by the application. If overridden by an environment variable, it will return that filename.

config_id is used to determine the name of the variable. If that does not return a value, config_filename will be returned instead.

config_resolver.core.effective_path(config_id, search_path='')

Returns a list of paths to search for config files in reverse order of precedence. In other words: the last path element will override the settings from the first one.

The value in config_id determines the sub-folder structure.

If search_path is specified, that value should have the OS specific path-separator (: or ;). This will override the default path. Subsequently the value of the environment variable <GROUP_NAME>_<APP_NAME>_PATH will be inspected. If this value is set, it will be used instead of anything found previously unless the value is prefixed with a + sign. In that case it will be appended to the end of the list.

config_resolver.core.env_name(config_id)

Return the name of the environment variable which contains the file-name to load.

config_resolver.core.find_files(config_id, search_path=None, filename=None)

Looks for files in default locations. Returns an iterator of filenames.

Parameters:

• config_id – A “ConfigID” object used to identify the config folder.
• search_path – A list of paths to search for files.
• filename – The name of the file we search for.

config_resolver.core.from_string(data, handler=None)

Load a config from the string value in data. handler can be used to specify a custom parser/handler.

config_resolver.core.get_config(group_name, app_name, lookup_options=None, handler=None)

Factory function to retrieve new config instances.

group_name and app_name are used to determine the folder locations. We always assume a structure like <group_name>/<app_name>/<filename>.<extension>.

lookup_options is a dictionary with the following optional keys:

search_path (default=``[]``)

A list of folders that should be searched for config files. The order here is relevant. The folders will be searched in order, and each file which is found will be loaded by the handler.

filename (default=``’app.ini’``)

The basename of the file which should be loaded (f.ex.: db.ini)

require_load (default=``False``)

A boolean value which determines what happens if no file was loaded. If this is set to True the call to get_config will raise an exception if no file was found. Otherwise it will simply log a warning.

version (default=``None``)

This can be a string in the form <major>.<minor>. If specified, the lookup process will request a version number from the handler for each file found. The version in the file will be compared with this value. If the minor-number differs, the file will be loaded, but a warning will be logged. If the major number differs, the file will be skipped and an error will be logged. If the value is left unset, no version checking will be performed.

How the version has to be stored in the config file depends on the handler.

secure (default=``False``)

If set to True, files which are world-readable will be ignored. The idea here is nicked from the way SSH handles files with sensitive data. It forces you to have secure file-access rights because the file will be skipped if the rights are too open.

config_resolver.core.get_xdg_dirs(config_id)

Returns a list of paths specified by the XDG_CONFIG_DIRS environment variable or the appropriate default. See The Freedesktop XDG standard for details.

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

The value in config_id is used to determine the sub-folder structure.

config_resolver.core.get_xdg_home(config_id)

Returns the value specified in the XDG_CONFIG_HOME environment variable or the appropriate default. See The Freedesktop XDG standard for details.

config_resolver.core.is_readable(config_id, filename, version=None, secure=False, handler=None)

Check if filename can be read. Will return boolean which is True if the file can be read, False otherwise.

Parameters:

• filename – The exact filename which should be checked.
• version – The expected version, that should be found in the file.
• secure – Whether we should avoid loading insecure files or not.
• handler – The handler to be used to open and parse the file.

config_resolver.core.prefixed_logger

Returns a log instance and prefix filter for a given group- & app-name pair.

The call to this function is cached to ensure we only have one instance in memory.