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)[source]¶ 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
-
class
cfg_loader.schema.base.
ExtraFieldsSchema
(only=None, exclude=(), prefix='', many=False, context=None, load_only=(), dump_only=(), partial=False)[source]¶ Schema class that preserves fields provided in input data but that were omitted in schema fields
-
class
cfg_loader.schema.base.
UnwrapNestedSchema
(only=None, exclude=(), prefix='', many=False, context=None, load_only=(), dump_only=(), partial=False)[source]¶ Schema class that can unwrap nested fields
-
class
cfg_loader.schema.base.
ConfigSchema
(*args, substitution_mapping=None, **kwargs)[source]¶ Main schema class for declaring a configuration schema
It inherits every feature from
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)[source]¶ Base config loader using a marshmallow schema to validate and process input data
Parameters: schema – Marshmallow schema used to deserialize configuration input data
-
class
cfg_loader.loader.
YamlConfigLoader
(*args, config_file_env_var='CONFIG_FILE', **kwargs)[source]¶ 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
Interpolator¶
-
class
cfg_loader.interpolator.
Interpolator
(substitution_mapping=None, substitution_template=<class 'cfg_loader.interpolator.SubstitutionTemplate'>)[source]¶ 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
-
class
cfg_loader.interpolator.
SubstitutionTemplate
(template)[source]¶ 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
Fields¶
Exceptions¶
-
class
cfg_loader.exceptions.
ConfigLoaderError
[source]¶ Bases:
Exception
Base class for all application related errors.
-
class
cfg_loader.exceptions.
ConfigFileMissingError
[source]¶ Bases:
cfg_loader.exceptions.ConfigLoaderError
Error raised when not specifying a config file
-
class
cfg_loader.exceptions.
ConfigFileNotFoundError
[source]¶ Bases:
cfg_loader.exceptions.ConfigLoaderError
Error raised when an invalid config file path is provided
-
class
cfg_loader.exceptions.
LoadingError
[source]¶ Bases:
cfg_loader.exceptions.ConfigLoaderError
Error raised when loading the configuration file
-
class
cfg_loader.exceptions.
ValidationError
[source]¶ Bases:
cfg_loader.exceptions.ConfigLoaderError
Error raised when marshmallow raise a validation error at deserialization
-
class
cfg_loader.exceptions.
UnsetRequiredSubstitution
[source]¶ Bases:
cfg_loader.exceptions.LoadingError
Error raised when a substitution environment variable is required but unset
-
class
cfg_loader.exceptions.
InvalidSubstitution
[source]¶ Bases:
cfg_loader.exceptions.LoadingError
Error raised when an invalid substitution is detected