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

Create a collection of name/value pairs.

RawParameter

EnvRawParameter

ArgParseRawParameter

YamlRawParameter

DefaultValueRawParameter

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

LoadedParameter

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

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)

load_file_configs(→ dict[pathlib.Path, dict])

custom_expandvars(→ str)

Expand variables in a string.

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.

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

Bases: ConfigurationError

Common base class for all non-exit exceptions.

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

Bases: ConfigurationError

Common base class for all non-exit exceptions.

exception MultipleKeysError(source, keys, preferred_key)

Bases: ValidationError

Common base class for all non-exit exceptions.

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

Bases: ValidationError

Common base class for all non-exit exceptions.

exception CustomValidationError(parameter_name, parameter_value, source, custom_message)

Bases: ValidationError

Common base class for all non-exit exceptions.

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

Bases: conda.CondaMultiError, ConfigurationError

Common base class for all non-exit exceptions.

raise_errors(errors)
class ParameterFlag(*args, **kwds)

Bases: enum.Enum

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

  • attribute access:

>>> Color.RED
<Color.RED: 1>
  • value lookup:

>>> Color(1)
<Color.RED: 1>
  • name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3
>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes -- see the documentation for details.

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)
load_file_configs(search_path: Iterable[Path | str], **kwargs) dict[pathlib.Path, dict]
class LoadedParameter(name, value, key_flag, value_flags, validation=None)
_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.

__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.

_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.

_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.

_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)
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.

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.

_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.

_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.

_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.

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[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[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()