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
Create a collection of name/value pairs. |
|
Wraps a default value as a RawParameter, for usage in ParameterLoader. |
|
LoadedParameter type that holds a single python primitive value. |
|
LoadedParameter type that holds a map (i.e. dict) of LoadedParameters. |
|
LoadedParameter type that holds a sequence (i.e. list) of LoadedParameters. |
|
LoadedParameter type that holds a mapping (i.e. object) of LoadedParameters. |
|
Dummy class to mark whether a Python object has config parameters within. |
|
Parameter type for a Configuration class that holds a single python primitive value. |
|
Parameter type for a Configuration class that holds a map (i.e. dict) of Parameters. |
|
Parameter type for a Configuration class that holds a sequence (i.e. list) of Parameters. |
|
Parameter type for a Configuration class that holds an object with Parameter fields. |
|
ParameterLoader class contains the top level logic needed to load a parameter from start to |
|
metaclass for Configuration |
|
Functions
|
|
|
|
|
|
|
|
|
|
|
Expand variables in a string. |
Attributes
- 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()