API Reference

Reading configuration

confidence.load_name(*names, load_order=DEFAULT_LOAD_ORDER, extension='yaml', missing=Missing.SILENT)

Read a Configuration instance by name, trying to read from files in increasing significance. The default load order is system, user, application, environment.

Multiple names are combined with multiple loaders using names as the ‘inner loop / selector’, loading /etc/name1.yaml and /etc/name2.yaml before ./name1.yaml and ./name2.yaml.

Parameters:

• names (str) – application or configuration set names, in increasing significance

• load_order (Iterable[Union[str, Callable[[str, str], Configuration]]]) – ordered list of name templates or callable s, in increasing order of significance

• extension (str) – file extension to be used

• missing (Any) – policy to be used when a configured key is missing, either as a Missing instance or a default value

Returns:

a Configuration instances providing values loaded from names in load_order ordering

Return type:

Configuration

confidence.loadf(*fnames, default=NoDefault, missing=Missing.SILENT)

Read a Configuration instance from named files.

Parameters:

• fnames (Union[str, PathLike]) – name of the files to open()

• default (Any) – dict or Configuration to use when a file does not exist (default is to raise a FileNotFoundError)

• missing (Any) – policy to be used when a configured key is missing, either as a Missing instance or a default value

Returns:

a Configuration instance providing values from fnames

Return type:

Configuration

confidence.loads(*strings, missing=Missing.SILENT)

Read a Configuration instance from strings.

Parameters:

• strings (str) – configuration contents

• missing (Any) – policy to be used when a configured key is missing, either as a Missing instance or a default value

Returns:

a Configuration instance providing values from strings

Return type:

Configuration

confidence.load(*fps, missing=Missing.SILENT)

Read a Configuration instance from file-like objects.

Parameters:

• fps (IO) – file-like objects (supporting .read())

• missing (Any) – policy to be used when a configured key is missing, either as a Missing instance or a default value

Returns:

a Configuration instance providing values from fps

Return type:

Configuration

confidence.dumpf(value, fname, encoding='utf-8')

Serialize the configuration in value to a YAML-formatted file.

Parameters:

• value (Any) – the value (like a Configuration object) to dump

• fname (Union[str, PathLike]) – name or path of the file to write to

• encoding (str) – encoding to use

Return type:

None

confidence.dumps(value)

Serialize the configuration in value as a YAML-formatted string.

Parameters:

value (Any) – the value (like a Configuration object) to dump

Returns:

configuration, serialized as a str in YAML format

Return type:

str

confidence.dump(value, fp, encoding='utf-8')

Serialize the configuration in value to YAML format, writing it to fp.

Parameters:

• value (Any) – the value (like a Configuration object) to dump

• fp (IO) – a file-like object to write to

• encoding (str) – encoding to use

Return type:

None

The Configuration object

class confidence.Configuration

A collection of configured values, retrievable as either dict-like items or attributes.

__init__(*sources, missing=Missing.SILENT)

Create a new Configuration, based on one or multiple source mappings.

Parameters:

• sources (Mapping[str, Any]) – source mappings to base this Configuration on, ordered from least to most significant

• missing (Any) – policy to be used when a configured key is missing, either as a Missing instance or a default value

get(path, default=NoDefault, *, as_type=None, resolve_references=True)

Gets a value for the specified path.

Parameters:

• path (str) – the configuration key to fetch a value for, steps separated by a dot (.)

• default (Any) – a value to return if no value is found for the supplied path (None is allowed)

• as_type (Optional[Callable]) – an optional callable to apply to the value found for the supplied path (possibly raising exceptions of its own if the value can not be coerced to the expected type)

• resolve_references (bool) – whether to resolve references in values

Returns:

the value associated with the supplied configuration key, if available, or a supplied default value if the key was not found

Raises:

• NotConfiguredError – when no value was found for path and default was not provided

• ConfiguredReferenceError – when a reference could not be resolved

Return type:

Any

Controlling precedence / load order

confidence.loaders(*specifiers)

Generates loaders in the specified order.

Arguments can be Locality instances, producing the loader(s) available for that locality, str instances (used as file path templates) or callable s. These can be mixed:

# define a load order using predefined user-local locations,
# an explicit path, a template and a user-defined function
load_order = loaders(Locality.user,
                     '/etc/defaults/hard-coded.yaml',
                     '/path/to/{name}.{extension}',
                     my_loader)

# load configuration for name 'my-application' using the load order
# defined above
config = load_name('my-application', load_order=load_order)

Parameters:

specifiers (Union[Locality, str, Callable[[str, str], Configuration]]) – loader specifiers, see description

Yields:

configuration loaders in the specified order

Return type:

Iterable[Union[str, Callable[[str, str], Configuration]]]

class confidence.Locality

Enumeration of localities defined by confidence, ranging from system-wide locations for configurations (e.g. /etc/name.yaml) to environment variables.

SYSTEM = 0

system-wide configuration locations

USER = 1

user-local configuration locations

APPLICATION = 2

application-local configuration locations (dependent on the current working directory)

ENVIRONMENT = 3

configuration from environment variables