`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`	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: str | None, caused_by: Any | None = 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(*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)#

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: collections.abc.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: collections.abc.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.

to_json()#: Return a serializable object with defaults filled in

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

property _parameter_loaders: dict[str, ParameterLoader]#

__call__(*args, **kwargs)#: Call self as a function.

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)#

classmethod _set_parameter_names_and_aliases()#: Build parameter_names_and_aliases from the class's parameter loaders.

static _expand_search_path(search_path: conda.common.path.PathsType, **kwargs) → collections.abc.Iterable[pathlib.Path]#

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

_set_search_path(search_path: conda.common.path.PathsType, **kwargs)#

_set_env_vars(app_name=None)#

_set_argparse_args(argparse_args)#

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

name_for_alias(alias: str, ignore_private: bool = True) → str | None#

Find the canonical parameter name for a given alias.

This method searches through all configuration parameters to find the canonical parameter name that corresponds to the given alias. It's useful for resolving parameter aliases to their primary names in configuration contexts.

Parameters:

alias (str) -- The parameter alias to look up.
ignore_private (bool, optional) -- If True (default), exclude private parameters (those starting with underscore) from the search. If False, include all parameters regardless of privacy.

Returns:

The canonical parameter name if the alias is found, otherwise None.

Return type:

str | None

Example

>>> config = Configuration()
>>> config.name_for_alias("channel_priority")
'channel_priority'
>>> config.name_for_alias("unknown_alias")
None

_get_parameter_loader(parameter_name)#: Get parameter loader with fallback for missing parameters.

_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(aliases: bool = False)#

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.