API

This part of the documentation covers all the interfaces of Conf-Loader.

Schema

class cfg_loader.schema.base.InterpolatingSchema(*args, substitution_mapping=None, **kwargs)

Schema class that interpolate environ variables from input data

It implements environment variable substitution following specification from docker-compose (c.f. https://docs.docker.com/compose/compose-file/#variable-substitution)

Parameters:substitution_mapping – Mapping containing values to substitute

load(data, many=None, partial=None)

Deserialize a data structure to an object defined by this Schema’s fields

Parameters:

• data (dict) – Data object to load from
• many (bool) – Whether to deserialize data as a collection
• partial (bool | tuple) – whether to ignore missing fields

Returns:

Deserialized data

class cfg_loader.schema.base.ExtraFieldsSchema(only=None, exclude=(), prefix='', many=False, context=None, load_only=(), dump_only=(), partial=False)

Schema class that preserves fields provided in input data but that were omitted in schema fields

add_extra_fields(data, original_data)

Add field from input data that were not listed as a schema fields

Parameters:

• data (dict) – Data to complete
• extra_data (dict) – Extra data to insert

class cfg_loader.schema.base.UnwrapNestedSchema(only=None, exclude=(), prefix='', many=False, context=None, load_only=(), dump_only=(), partial=False)

Schema class that can unwrap nested fields

class cfg_loader.schema.base.ConfigSchema(*args, substitution_mapping=None, **kwargs)

Main schema class for declaring a configuration schema

It inherits every feature from

• InterpolatingSchema
• ExtraFieldsSchema
• UnwrapNestedSchema

Example

>>> from cfg_loader import ConfigSchema, BaseConfigLoader
>>> from marshmallow import fields

>>> class MyConfigSchema(ConfigSchema):
...     setting1 = fields.Str()
...     setting2 = fields.Int(required=True)
...     setting3 = fields.Float(missing=13.2)

>>> substitution_mapping = {'VARIABLE': 'substitution'}
>>> my_config_loader = BaseConfigLoader(MyConfigSchema,
...                                     substitution_mapping)

>>> schema = MyConfigSchema(substitution_mapping=substitution_mapping)
>>> config = schema.load({
...    'setting1': '${VARIABLE}',
...    'setting2': '${UNSET_VARIABLE:-1}',
... })

>>> config == {
...     'setting1': 'substitution',
...     'setting2': 1,
...     'setting3': 13.2,
... }
True

Loader

class cfg_loader.loader.BaseConfigLoader(config_schema, substitution_mapping=None)

Base config loader using a marshmallow schema to validate and process input data

Parameters:schema – Marshmallow schema used to deserialize configuration input data

load(data, substitution_mapping=None)

Load configuration from an object

Parameters:input (object) – Data to load configuration from (must be deserializable by schema)

class cfg_loader.loader.YamlConfigLoader(*args, config_file_env_var='CONFIG_FILE', default_config_path=None, **kwargs)

Config loader that reads config from .yaml file

Parameters:

• config_file_env_var (str) – Environment variable to read config file path from if not provided when loading
• default_config_path (str) – Used if neither path is provided at loading nor environment variable

check_file(config_file)

Check file validity

Parameters:config_file (str) – Path to the .yaml configuration file

load(config_file=None, substitution_mapping=None)

Load configuration from .yaml file

Parameters:config_file (str) – Path to the .yaml configuration file

Interpolator

class cfg_loader.interpolator.Interpolator(substitution_mapping=None, substitution_template=<class 'cfg_loader.interpolator.SubstitutionTemplate'>)

Class used to substitute environment variables in complex object

Parameters:substitution_mapping (dict) – Mapping with values to substitute

Example

>>> interpolator = Interpolator(substitution_mapping={'VARIABLE': 'value'})

>>> interpolator.interpolate('${VARIABLE} in complex string')
'value in complex string'

>>> result = interpolator.interpolate_recursive({'key1': '${VARIABLE}', 'key2': ['element', '${EXTRA-default}']})
>>> result == {'key1': 'value', 'key2': ['element', 'default']}
True

interpolate(string)

Substitute environment variable in a string

interpolate_recursive(obj)

Substitute environment variable in an object

class cfg_loader.interpolator.SubstitutionTemplate(template)

Class used to substitute environment variables in a string

It implements specification from docker-compose environ variable substitution (c.f. https://docs.docker.com/compose/compose-file/#variable-substitution)

Examples with basic substitution

>>> template = SubstitutionTemplate('${VARIABLE}')
>>> template.substitute({'VARIABLE': 'value'})
'value'
>>> template.substitute({'VARIABLE': ''})
''
>>> template.substitute({})
Traceback (most recent call last):
...
KeyError: 'VARIABLE'

Examples with substitution if variable is empty or unset (separator: “:-“)

>>> template = SubstitutionTemplate('${VARIABLE:-default}')
>>> template.substitute({'VARIABLE': 'value'})
'value'
>>> template.substitute({'VARIABLE': ''})
'default'
>>> template.substitute({})
'default'

Examples with substitution if variable is empty (separator: “-“):

>>> template = SubstitutionTemplate('${VARIABLE-default}')
>>> template.substitute({'VARIABLE': 'value'})
'value'
>>> template.substitute({'VARIABLE': ''})
''
>>> template.substitute({})
'default'

Examples with error raised if variable is unset (separator: “?”)

>>> template = SubstitutionTemplate('${VARIABLE?err}')
>>> template.substitute({'VARIABLE': 'value'})
'value'
>>> template.substitute({'VARIABLE': ''})
''
>>> template.substitute({})
Traceback (most recent call last):
...
cfg_loader.exceptions.UnsetRequiredSubstitution: err

Examples with error raised if variable is empty or unset (separator: “:?”)

>>> template = SubstitutionTemplate('${VARIABLE:?err}')
>>> template.substitute({'VARIABLE': 'value'})
'value'
>>> template.substitute({'VARIABLE': ''})
Traceback (most recent call last):
...
cfg_loader.exceptions.UnsetRequiredSubstitution: err
>>> template.substitute({})
Traceback (most recent call last):
...
cfg_loader.exceptions.UnsetRequiredSubstitution: err

substitute(mapping)

Substitute values indexed by mapping into template

Parameters:mapping (dict) – Mapping containing values to substitute

Fields

class cfg_loader.fields.Path(*args, **kwargs)

A validated path field. Validation occurs during both serialization and deserialization.

Parameters:

• args – The same positional arguments that String receives.
• kwargs – The same keyword arguments that String receives.

class cfg_loader.fields.UnwrapNested(*args, prefix='', **kwargs)

Nested fields class that will unwrapped at deserialization

Useful when used with UnwrapSchema

Parameters:prefix (str) – Optional prefix to add to every key when unwrapping a field

Exceptions

class cfg_loader.exceptions.ConfigLoaderError

Bases: Exception

Base class for all application related errors.

class cfg_loader.exceptions.ConfigFileMissingError

Bases: cfg_loader.exceptions.ConfigLoaderError

Error raised when not specifying a config file

class cfg_loader.exceptions.ConfigFileNotFoundError

Bases: cfg_loader.exceptions.ConfigLoaderError

Error raised when an invalid config file path is provided

class cfg_loader.exceptions.LoadingError

Bases: cfg_loader.exceptions.ConfigLoaderError

Error raised when loading the configuration file

class cfg_loader.exceptions.ValidationError

Bases: cfg_loader.exceptions.ConfigLoaderError

Error raised when marshmallow raise a validation error at deserialization

class cfg_loader.exceptions.UnsetRequiredSubstitution

Bases: cfg_loader.exceptions.LoadingError

Error raised when a substitution environment variable is required but unset

class cfg_loader.exceptions.InvalidSubstitution

Bases: cfg_loader.exceptions.LoadingError

Error raised when an invalid substitution is detected