`configuration`#

A generalized application configuration utility.

Features include:

lazy eval
merges configuration files
parameter type validation, with custom validation
parameter aliases

Easily extensible to other source formats, e.g. json and ini

Classes#

`ParameterFlag`	Generic enumeration.
`RawParameter`
`EnvRawParameter`
`ArgParseRawParameter`
`YamlRawParameter`
`DefaultValueRawParameter`	Wraps a default value as a RawParameter, for usage in ParameterLoader.
`LoadedParameter`	Represents a Parameter that has been loaded with configuration value.
`PrimitiveLoadedParameter`	LoadedParameter type that holds a single python primitive value.
`MapLoadedParameter`	LoadedParameter type that holds a map (i.e. dict) of LoadedParameters.
`SequenceLoadedParameter`	LoadedParameter type that holds a sequence (i.e. list) of LoadedParameters.
`ObjectLoadedParameter`	LoadedParameter type that holds a mapping (i.e. object) of LoadedParameters.
`ConfigurationObject`	Dummy class to mark whether a Python object has config parameters within.
`Parameter`	The Parameter class represents an unloaded configuration parameter, holding type, default
`PrimitiveParameter`	Parameter type for a Configuration class that holds a single python primitive value.
`MapParameter`	Parameter type for a Configuration class that holds a map (i.e. dict) of Parameters.
`SequenceParameter`	Parameter type for a Configuration class that holds a sequence (i.e. list) of Parameters.
`ObjectParameter`	Parameter type for a Configuration class that holds an object with Parameter fields.
`ParameterLoader`	ParameterLoader class contains the top level logic needed to load a parameter from start to
`ConfigurationType`	metaclass for Configuration
`Configuration`

Functions#

`pretty_list`(iterable[, padding])
`pretty_map`(dictionary[, padding])
`expand_environment_variables`(unexpanded)
`raise_errors`(errors)
`custom_expandvars`(→ str)	Expand variables in a string.
`unique_sequence_map`(*, unique_key)	Used to validate properties on `Configuration` subclasses defined as a

Attributes#

`EMPTY_MAP`
`CONDARC_FILENAMES`
`YAML_EXTENSIONS`
`_RE_CUSTOM_EXPANDVARS`

EMPTY_MAP#

pretty_list(iterable, padding=' ')#

pretty_map(dictionary, padding=' ')#

expand_environment_variables(unexpanded)#

exception ConfigurationError(message, caused_by=None, **kwargs)#

Bases: conda.CondaError

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

exception ConfigurationLoadError(path, message_addition='', **kwargs)#

Bases: ConfigurationError

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

exception ValidationError(parameter_name, parameter_value, source, msg=None, **kwargs)#

Bases: ConfigurationError

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

exception MultipleKeysError(source, keys, preferred_key)#

Bases: ValidationError

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

exception InvalidTypeError(parameter_name, parameter_value, source, wrong_type, valid_types, msg=None)#

Bases: ValidationError

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

exception CustomValidationError(parameter_name, parameter_value, source, custom_message)#

Bases: ValidationError

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

exception MultiValidationError(errors, *args, **kwargs)#

Bases: conda.CondaMultiError, ConfigurationError

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

raise_errors(errors)#

class ParameterFlag#

Bases: enum.Enum

Generic enumeration.

Derive from this class to define new enumerations.

final = 'final'#

top = 'top'#

bottom = 'bottom'#

__str__()#: Return str(self).

classmethod from_name(name)#

classmethod from_value(value)#

classmethod from_string(string)#

class RawParameter(source, key, raw_value)#

__repr__()#: Return repr(self).

abstract value(parameter_obj)#

abstract keyflag()#

abstract valueflags(parameter_obj)#

classmethod make_raw_parameters(source, from_map)#

class EnvRawParameter(source, key, raw_value)#

Bases: RawParameter

property __important_split_value#

source = 'envvars'#

value(parameter_obj)#

keyflag()#

valueflags(parameter_obj)#

classmethod make_raw_parameters(appname)#

class ArgParseRawParameter(source, key, raw_value)#

Bases: RawParameter

source = 'cmd_line'#

value(parameter_obj)#

keyflag()#

valueflags(parameter_obj)#

classmethod make_raw_parameters(args_from_argparse)#

class YamlRawParameter(source, key, raw_value, key_comment)#

Bases: RawParameter

value(parameter_obj)#

keyflag()#

valueflags(parameter_obj)#

static _get_yaml_key_comment(commented_dict, key)#

classmethod _get_yaml_list_comments(value)#

static _get_yaml_list_comment_item(item)#

static _get_yaml_map_comments(value)#

classmethod make_raw_parameters(source, from_map)#

classmethod make_raw_parameters_from_file(filepath)#

class DefaultValueRawParameter(source, key, raw_value)#

Bases: RawParameter

Wraps a default value as a RawParameter, for usage in ParameterLoader.

value(parameter_obj)#

keyflag()#

valueflags(parameter_obj)#

class LoadedParameter(name, value, key_flag, value_flags, validation=None)#

Represents a Parameter that has been loaded with configuration value.

Parameters:

name (str) -- name of the loaded parameter
value (LoadedParameter or primitive) -- the value of the loaded parameter
key_flag (ParameterFlag or None) -- priority flag for the parameter itself
value_flags (Any or None) -- priority flags for the parameter values
validation (callable) -- Given a parameter value as input, return a boolean indicating validity, or alternately return a string describing an invalid value.

_type#

_element_type#

__eq__(other)#: Return self==value.

__hash__()#: Return hash(self).

collect_errors(instance, typed_value, source='<<merged>>')#

Validate a LoadedParameter typed value.

Parameters:

instance (Configuration) -- the instance object used to create the LoadedParameter.
typed_value (Any) -- typed value to validate.
source (str) -- string description for the source of the typed_value.

expand()#

Recursively expands any environment values in the Loaded Parameter.

Returns: LoadedParameter

abstract merge(matches)#

Recursively merges matches into one LoadedParameter.

Parameters:: matches (List<LoadedParameter>) -- list of matches of this parameter.

Returns: LoadedParameter

typify(source)#

Recursively types a LoadedParameter.

Parameters:: source (str) -- string describing the source of the LoadedParameter.

Returns: a primitive, sequence, or map representing the typed value.

static _typify_data_structure(value, source, type_hint=None)#

static _match_key_is_important(loaded_parameter)#

static _first_important_matches(matches)#

class PrimitiveLoadedParameter(name, element_type, value, key_flag, value_flags, validation=None)#

Bases: LoadedParameter

LoadedParameter type that holds a single python primitive value.

The python primitive types are str, int, float, complex, bool, and NoneType. In addition, python 2 has long and unicode types.

Parameters:

element_type (type or tuple[type]) -- Type-validation of parameter's value.
value (primitive value) -- primitive python value.

__eq__(other)#: Return self==value.

__hash__()#: Return hash(self).

merge(matches)#

Recursively merges matches into one LoadedParameter.

Parameters:: matches (List<LoadedParameter>) -- list of matches of this parameter.

Returns: LoadedParameter

class MapLoadedParameter(name, value, element_type, key_flag, value_flags, validation=None)#

Bases: LoadedParameter

LoadedParameter type that holds a map (i.e. dict) of LoadedParameters.

Parameters:

value (Mapping) -- Map of string keys to LoadedParameter values.
element_type (Parameter) -- The Parameter type that is held in value.
value_flags (Mapping) -- Map of priority value flags.

_type#

collect_errors(instance, typed_value, source='<<merged>>')#

Validate a LoadedParameter typed value.

Parameters:

instance (Configuration) -- the instance object used to create the LoadedParameter.
typed_value (Any) -- typed value to validate.
source (str) -- string description for the source of the typed_value.

merge(parameters: Sequence[MapLoadedParameter]) → MapLoadedParameter#

Recursively merges matches into one LoadedParameter.

Parameters:: matches (List<LoadedParameter>) -- list of matches of this parameter.

Returns: LoadedParameter

class SequenceLoadedParameter(name, value, element_type, key_flag, value_flags, validation=None)#

Bases: LoadedParameter

LoadedParameter type that holds a sequence (i.e. list) of LoadedParameters.

Parameters:

value (Sequence) -- Sequence of LoadedParameter values.
element_type (Parameter) -- The Parameter type that is held in the sequence.
value_flags (Sequence) -- Sequence of priority value_flags.

_type#

collect_errors(instance, typed_value, source='<<merged>>')#

Validate a LoadedParameter typed value.

Parameters:

instance (Configuration) -- the instance object used to create the LoadedParameter.
typed_value (Any) -- typed value to validate.
source (str) -- string description for the source of the typed_value.

merge(matches)#

Recursively merges matches into one LoadedParameter.

Parameters:: matches (List<LoadedParameter>) -- list of matches of this parameter.

Returns: LoadedParameter

class ObjectLoadedParameter(name, value, element_type, key_flag, value_flags, validation=None)#

Bases: LoadedParameter

LoadedParameter type that holds a mapping (i.e. object) of LoadedParameters.

Parameters:

value (Sequence) -- Object with LoadedParameter fields.
element_type (object) -- The Parameter type that is held in the sequence.
value_flags (Sequence) -- Sequence of priority value_flags.

_type#

collect_errors(instance, typed_value, source='<<merged>>')#

Validate a LoadedParameter typed value.

Parameters:

instance (Configuration) -- the instance object used to create the LoadedParameter.
typed_value (Any) -- typed value to validate.
source (str) -- string description for the source of the typed_value.

merge(parameters: Sequence[ObjectLoadedParameter]) → ObjectLoadedParameter#

Recursively merges matches into one LoadedParameter.

Parameters:: matches (List<LoadedParameter>) -- list of matches of this parameter.

Returns: LoadedParameter

class ConfigurationObject#: Dummy class to mark whether a Python object has config parameters within.

class Parameter(default, validation=None)#

The Parameter class represents an unloaded configuration parameter, holding type, default and validation information until the parameter is loaded with a configuration.

Parameters:

default (Any) -- the typed, python representation default value given if the Parameter is not found in a Configuration.
validation (callable) -- Given a parameter value as input, return a boolean indicating validity, or alternately return a string describing an invalid value.

property default#: Returns a DefaultValueRawParameter that wraps the actual default value.

_type#

_element_type#

get_all_matches(name, names, instance)#

Finds all matches of a Parameter in a Configuration instance

Parameters:

name (str) -- canonical name of the parameter to search for
names (tuple(str)) -- alternative aliases of the parameter
instance (Configuration) -- instance of the configuration to search within

Returns (List(RawParameter)): matches of the parameter found in the configuration.

abstract load(name, match)#

Loads a Parameter with the value in a RawParameter.

Parameters:

name (str) -- name of the parameter to pass through
match (RawParameter) -- the value of the RawParameter match

Returns a LoadedParameter

typify(name, source, value)#

class PrimitiveParameter(default, element_type=None, validation=None)#

Bases: Parameter

Parameter type for a Configuration class that holds a single python primitive value.

The python primitive types are str, int, float, complex, bool, and NoneType. In addition, python 2 has long and unicode types.

Parameters:

default (primitive value) -- default value if the Parameter is not found.
element_type (type or tuple[type]) -- Type-validation of parameter's value. If None, type(default) is used.

load(name, match)#

Loads a Parameter with the value in a RawParameter.

Parameters:

name (str) -- name of the parameter to pass through
match (RawParameter) -- the value of the RawParameter match

Returns a LoadedParameter

class MapParameter(element_type, default=frozendict(), validation=None)#

Bases: Parameter

Parameter type for a Configuration class that holds a map (i.e. dict) of Parameters.

Parameters:

element_type (Parameter) -- The Parameter type held in the MapParameter.
default (Mapping) -- The parameter's default value. If None, will be an empty dict.

_type#

get_all_matches(name, names, instance)#

Finds all matches of a Parameter in a Configuration instance

Parameters:

name (str) -- canonical name of the parameter to search for
names (tuple(str)) -- alternative aliases of the parameter
instance (Configuration) -- instance of the configuration to search within

Returns (List(RawParameter)): matches of the parameter found in the configuration.

load(name, match)#

Loads a Parameter with the value in a RawParameter.

Parameters:

name (str) -- name of the parameter to pass through
match (RawParameter) -- the value of the RawParameter match

Returns a LoadedParameter

class SequenceParameter(element_type, default=(), validation=None, string_delimiter=',')#

Bases: Parameter

Parameter type for a Configuration class that holds a sequence (i.e. list) of Parameters.

Parameters:

element_type (Parameter) -- The Parameter type that is held in the sequence.
default (Sequence) -- default value, empty tuple if not given.
string_delimiter (str) -- separation string used to parse string into sequence.

_type#

get_all_matches(name, names, instance)#

Finds all matches of a Parameter in a Configuration instance

Parameters:

name (str) -- canonical name of the parameter to search for
names (tuple(str)) -- alternative aliases of the parameter
instance (Configuration) -- instance of the configuration to search within

Returns (List(RawParameter)): matches of the parameter found in the configuration.

load(name, match)#

Loads a Parameter with the value in a RawParameter.

Parameters:

name (str) -- name of the parameter to pass through
match (RawParameter) -- the value of the RawParameter match

Returns a LoadedParameter

class ObjectParameter(element_type, default=ConfigurationObject(), validation=None)#

Bases: Parameter

Parameter type for a Configuration class that holds an object with Parameter fields.

Parameters:

element_type (object) -- The object type with parameter fields held in ObjectParameter.
default (Sequence) -- default value, empty tuple if not given.

_type#

get_all_matches(name, names, instance)#

Finds all matches of a Parameter in a Configuration instance

Parameters:

name (str) -- canonical name of the parameter to search for
names (tuple(str)) -- alternative aliases of the parameter
instance (Configuration) -- instance of the configuration to search within

Returns (List(RawParameter)): matches of the parameter found in the configuration.

load(name, match)#

Loads a Parameter with the value in a RawParameter.

Parameters:

name (str) -- name of the parameter to pass through
match (RawParameter) -- the value of the RawParameter match

Returns a LoadedParameter

class ParameterLoader(parameter_type, aliases=(), expandvars=False)#

ParameterLoader class contains the top level logic needed to load a parameter from start to finish.

Parameters:

parameter_type (Parameter) -- the type of Parameter that is stored in the loader.
aliases (tuple(str)) -- alternative aliases for the Parameter
expandvars (bool) -- whether or not to recursively expand environmental variables.

property name#

property names#

_set_name(name)#

__get__(instance, instance_type)#

_raw_parameters_from_single_source(raw_parameters)#

static raw_parameters_from_single_source(name, names, raw_parameters)#

class ConfigurationType(name, bases, attr)#

Bases: type

metaclass for Configuration

CONDARC_FILENAMES = ('.condarc', 'condarc')#

YAML_EXTENSIONS = ('.yml', '.yaml')#

_RE_CUSTOM_EXPANDVARS#

custom_expandvars(template: str, mapping: collections.abc.Mapping[str, Any] = {}, /, **kwargs) → str#

Expand variables in a string.

Inspired by string.Template and modified to mirror os.path.expandvars functionality allowing custom variables without mutating os.environ.

Expands POSIX and Windows CMD environment variables as follows:

$VARIABLE → value of VARIABLE
${VARIABLE} → value of VARIABLE
%VARIABLE% → value of VARIABLE

Invalid substitutions are left as-is:

$MISSING → $MISSING
${MISSING} → ${MISSING}
%MISSING% → %MISSING%
$$ → $$
%% → %%
$ → $
% → %

class Configuration(search_path=(), app_name=None, argparse_args=None, **kwargs)#

static _expand_search_path(search_path: Iterable[pathlib.Path | str], **kwargs) → Iterable[pathlib.Path]#

classmethod _load_search_path(search_path: Iterable[pathlib.Path]) → Iterable[tuple[pathlib.Path, dict]]#

_set_search_path(search_path: Iterable[pathlib.Path | str], **kwargs)#

_set_env_vars(app_name=None)#

_set_argparse_args(argparse_args)#

_set_raw_data(raw_data: collections.abc.Mapping[Hashable, dict])#

_reset_cache()#

register_reset_callaback(callback)#

check_source(source)#

validate_all()#

static _collect_validation_error(func, *args, **kwargs)#

validate_configuration()#

post_build_validation()#

collect_all()#

describe_parameter(parameter_name)#

list_parameters()#

typify_parameter(parameter_name, value, source)#

abstract get_descriptions()#

unique_sequence_map(*, unique_key: str)#: Used to validate properties on Configuration subclasses defined as a SequenceParameter(MapParameter()) where the map contains a single key that should be regarded as unique. This decorator will handle removing duplicates and merging to a single sequence.