:py:mod:`configuration` ======================= .. py:module:: conda.common.configuration .. autoapi-nested-parse:: 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 ------- .. autoapisummary:: conda.common.configuration.ParameterFlag conda.common.configuration.RawParameter conda.common.configuration.EnvRawParameter conda.common.configuration.ArgParseRawParameter conda.common.configuration.YamlRawParameter conda.common.configuration.DefaultValueRawParameter conda.common.configuration.LoadedParameter conda.common.configuration.PrimitiveLoadedParameter conda.common.configuration.MapLoadedParameter conda.common.configuration.SequenceLoadedParameter conda.common.configuration.ObjectLoadedParameter conda.common.configuration.ConfigurationObject conda.common.configuration.Parameter conda.common.configuration.PrimitiveParameter conda.common.configuration.MapParameter conda.common.configuration.SequenceParameter conda.common.configuration.ObjectParameter conda.common.configuration.ParameterLoader conda.common.configuration.ConfigurationType conda.common.configuration.Configuration Functions --------- .. autoapisummary:: conda.common.configuration.pretty_list conda.common.configuration.pretty_map conda.common.configuration.expand_environment_variables conda.common.configuration.raise_errors conda.common.configuration.custom_expandvars conda.common.configuration.unique_sequence_map Attributes ---------- .. autoapisummary:: conda.common.configuration.EMPTY_MAP conda.common.configuration.CONDARC_FILENAMES conda.common.configuration.YAML_EXTENSIONS conda.common.configuration._RE_CUSTOM_EXPANDVARS .. py:data:: EMPTY_MAP .. py:function:: pretty_list(iterable, padding=' ') .. py:function:: pretty_map(dictionary, padding=' ') .. py:function:: expand_environment_variables(unexpanded) .. py:exception:: ConfigurationError(message: str | None, caused_by: Optional[Any] = None, **kwargs) Bases: :py:obj:`conda.CondaError` Common base class for all non-exit exceptions. Initialize self. See help(type(self)) for accurate signature. .. py:exception:: ConfigurationLoadError(path, message_addition='', **kwargs) Bases: :py:obj:`ConfigurationError` Common base class for all non-exit exceptions. Initialize self. See help(type(self)) for accurate signature. .. py:exception:: ValidationError(parameter_name, parameter_value, source, msg=None, **kwargs) Bases: :py:obj:`ConfigurationError` Common base class for all non-exit exceptions. Initialize self. See help(type(self)) for accurate signature. .. py:exception:: MultipleKeysError(source, keys, preferred_key) Bases: :py:obj:`ValidationError` Common base class for all non-exit exceptions. Initialize self. See help(type(self)) for accurate signature. .. py:exception:: InvalidTypeError(parameter_name, parameter_value, source, wrong_type, valid_types, msg=None) Bases: :py:obj:`ValidationError` Common base class for all non-exit exceptions. Initialize self. See help(type(self)) for accurate signature. .. py:exception:: CustomValidationError(parameter_name, parameter_value, source, custom_message) Bases: :py:obj:`ValidationError` Common base class for all non-exit exceptions. Initialize self. See help(type(self)) for accurate signature. .. py:exception:: MultiValidationError(errors, *args, **kwargs) Bases: :py:obj:`conda.CondaMultiError`, :py:obj:`ConfigurationError` Common base class for all non-exit exceptions. Initialize self. See help(type(self)) for accurate signature. .. py:function:: raise_errors(errors) .. py:class:: ParameterFlag(*args, **kwds) Bases: :py:obj:`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 - value lookup: >>> Color(1) - name lookup: >>> Color['RED'] Enumerations can be iterated over, and know how many members they have: >>> len(Color) 3 >>> list(Color) [, , ] Methods can be added to enumerations, and members can have their own attributes -- see the documentation for details. .. py:attribute:: final :value: 'final' .. py:attribute:: top :value: 'top' .. py:attribute:: bottom :value: 'bottom' .. py:method:: __str__() Return str(self). .. py:method:: from_name(name) :classmethod: .. py:method:: from_value(value) :classmethod: .. py:method:: from_string(string) :classmethod: .. py:class:: RawParameter(source, key, raw_value) .. py:method:: __repr__() Return repr(self). .. py:method:: value(parameter_obj) :abstractmethod: .. py:method:: keyflag() :abstractmethod: .. py:method:: valueflags(parameter_obj) :abstractmethod: .. py:method:: make_raw_parameters(source, from_map) :classmethod: .. py:class:: EnvRawParameter(source, key, raw_value) Bases: :py:obj:`RawParameter` .. py:property:: __important_split_value .. py:attribute:: source :value: 'envvars' .. py:method:: value(parameter_obj) .. py:method:: keyflag() .. py:method:: valueflags(parameter_obj) .. py:method:: make_raw_parameters(appname) :classmethod: .. py:class:: ArgParseRawParameter(source, key, raw_value) Bases: :py:obj:`RawParameter` .. py:attribute:: source :value: 'cmd_line' .. py:method:: value(parameter_obj) .. py:method:: keyflag() .. py:method:: valueflags(parameter_obj) .. py:method:: make_raw_parameters(args_from_argparse) :classmethod: .. py:class:: YamlRawParameter(source, key, raw_value, key_comment) Bases: :py:obj:`RawParameter` .. py:method:: value(parameter_obj) .. py:method:: keyflag() .. py:method:: valueflags(parameter_obj) .. py:method:: _get_yaml_key_comment(commented_dict, key) :staticmethod: .. py:method:: _get_yaml_list_comments(value) :classmethod: .. py:method:: _get_yaml_list_comment_item(item) :staticmethod: .. py:method:: _get_yaml_map_comments(value) :staticmethod: .. py:method:: make_raw_parameters(source, from_map) :classmethod: .. py:method:: make_raw_parameters_from_file(filepath) :classmethod: .. py:class:: DefaultValueRawParameter(source, key, raw_value) Bases: :py:obj:`RawParameter` Wraps a default value as a RawParameter, for usage in ParameterLoader. .. py:method:: value(parameter_obj) .. py:method:: keyflag() .. py:method:: valueflags(parameter_obj) .. py:class:: LoadedParameter(name, value, key_flag, value_flags, validation=None) Represents a Parameter that has been loaded with configuration value. :param name: name of the loaded parameter :type name: str :param value: the value of the loaded parameter :type value: LoadedParameter or primitive :param key_flag: priority flag for the parameter itself :type key_flag: ParameterFlag or None :param value_flags: priority flags for the parameter values :type value_flags: Any or None :param validation: Given a parameter value as input, return a boolean indicating validity, or alternately return a string describing an invalid value. :type validation: callable .. py:attribute:: _type .. py:attribute:: _element_type .. py:method:: __eq__(other) Return self==value. .. py:method:: __hash__() Return hash(self). .. py:method:: collect_errors(instance, typed_value, source='<>') Validate a LoadedParameter typed value. :param instance: the instance object used to create the LoadedParameter. :type instance: Configuration :param typed_value: typed value to validate. :type typed_value: Any :param source: string description for the source of the typed_value. :type source: str .. py:method:: expand() Recursively expands any environment values in the Loaded Parameter. Returns LoadedParameter .. py:method:: merge(matches) :abstractmethod: Recursively merges matches into one LoadedParameter. :param matches: list of matches of this parameter. :type matches: List Returns: LoadedParameter .. py:method:: typify(source) Recursively types a LoadedParameter. :param source: string describing the source of the LoadedParameter. :type source: str Returns: a primitive, sequence, or map representing the typed value. .. py:method:: _typify_data_structure(value, source, type_hint=None) :staticmethod: .. py:method:: _match_key_is_important(loaded_parameter) :staticmethod: .. py:method:: _first_important_matches(matches) :staticmethod: .. py:class:: PrimitiveLoadedParameter(name, element_type, value, key_flag, value_flags, validation=None) Bases: :py:obj:`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. :param element_type: Type-validation of parameter's value. :type element_type: type or tuple[type] :param value: primitive python value. :type value: primitive value .. py:method:: __eq__(other) Return self==value. .. py:method:: __hash__() Return hash(self). .. py:method:: merge(matches) Recursively merges matches into one LoadedParameter. :param matches: list of matches of this parameter. :type matches: List Returns: LoadedParameter .. py:class:: MapLoadedParameter(name, value, element_type, key_flag, value_flags, validation=None) Bases: :py:obj:`LoadedParameter` LoadedParameter type that holds a map (i.e. dict) of LoadedParameters. :param value: Map of string keys to LoadedParameter values. :type value: Mapping :param element_type: The Parameter type that is held in value. :type element_type: Parameter :param value_flags: Map of priority value flags. :type value_flags: Mapping .. py:attribute:: _type .. py:method:: collect_errors(instance, typed_value, source='<>') Validate a LoadedParameter typed value. :param instance: the instance object used to create the LoadedParameter. :type instance: Configuration :param typed_value: typed value to validate. :type typed_value: Any :param source: string description for the source of the typed_value. :type source: str .. py:method:: merge(parameters: collections.abc.Sequence[MapLoadedParameter]) -> MapLoadedParameter Recursively merges matches into one LoadedParameter. :param matches: list of matches of this parameter. :type matches: List Returns: LoadedParameter .. py:class:: SequenceLoadedParameter(name, value, element_type, key_flag, value_flags, validation=None) Bases: :py:obj:`LoadedParameter` LoadedParameter type that holds a sequence (i.e. list) of LoadedParameters. :param value: Sequence of LoadedParameter values. :type value: Sequence :param element_type: The Parameter type that is held in the sequence. :type element_type: Parameter :param value_flags: Sequence of priority value_flags. :type value_flags: Sequence .. py:attribute:: _type .. py:method:: collect_errors(instance, typed_value, source='<>') Validate a LoadedParameter typed value. :param instance: the instance object used to create the LoadedParameter. :type instance: Configuration :param typed_value: typed value to validate. :type typed_value: Any :param source: string description for the source of the typed_value. :type source: str .. py:method:: merge(matches) Recursively merges matches into one LoadedParameter. :param matches: list of matches of this parameter. :type matches: List Returns: LoadedParameter .. py:class:: ObjectLoadedParameter(name, value, element_type, key_flag, value_flags, validation=None) Bases: :py:obj:`LoadedParameter` LoadedParameter type that holds a mapping (i.e. object) of LoadedParameters. :param value: Object with LoadedParameter fields. :type value: Sequence :param element_type: The Parameter type that is held in the sequence. :type element_type: object :param value_flags: Sequence of priority value_flags. :type value_flags: Sequence .. py:attribute:: _type .. py:method:: collect_errors(instance, typed_value, source='<>') Validate a LoadedParameter typed value. :param instance: the instance object used to create the LoadedParameter. :type instance: Configuration :param typed_value: typed value to validate. :type typed_value: Any :param source: string description for the source of the typed_value. :type source: str .. py:method:: merge(parameters: collections.abc.Sequence[ObjectLoadedParameter]) -> ObjectLoadedParameter Recursively merges matches into one LoadedParameter. :param matches: list of matches of this parameter. :type matches: List Returns: LoadedParameter .. py:class:: ConfigurationObject Dummy class to mark whether a Python object has config parameters within. .. py:method:: to_json() Return a serializable object with defaults filled in .. py: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. :param default: the typed, python representation default value given if the Parameter is not found in a Configuration. :type default: Any :param validation: Given a parameter value as input, return a boolean indicating validity, or alternately return a string describing an invalid value. :type validation: callable .. py:property:: default Returns a DefaultValueRawParameter that wraps the actual default value. .. py:attribute:: _type .. py:attribute:: _element_type .. py:method:: get_all_matches(name, names, instance) Finds all matches of a Parameter in a Configuration instance :param name: canonical name of the parameter to search for :type name: str :param names: alternative aliases of the parameter :type names: tuple(str) :param instance: instance of the configuration to search within :type instance: Configuration Returns (List(RawParameter)): matches of the parameter found in the configuration. .. py:method:: load(name, match) :abstractmethod: Loads a Parameter with the value in a RawParameter. :param name: name of the parameter to pass through :type name: str :param match: the value of the RawParameter match :type match: RawParameter Returns a LoadedParameter .. py:method:: typify(name, source, value) .. py:class:: PrimitiveParameter(default, element_type=None, validation=None) Bases: :py:obj:`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. :param default: default value if the Parameter is not found. :type default: primitive value :param element_type: Type-validation of parameter's value. If None, type(default) is used. :type element_type: type or tuple[type] .. py:method:: load(name, match) Loads a Parameter with the value in a RawParameter. :param name: name of the parameter to pass through :type name: str :param match: the value of the RawParameter match :type match: RawParameter Returns a LoadedParameter .. py:class:: MapParameter(element_type, default=frozendict(), validation=None) Bases: :py:obj:`Parameter` Parameter type for a Configuration class that holds a map (i.e. dict) of Parameters. :param element_type: The Parameter type held in the MapParameter. :type element_type: Parameter :param default: The parameter's default value. If None, will be an empty dict. :type default: Mapping .. py:attribute:: _type .. py:method:: get_all_matches(name, names, instance) Finds all matches of a Parameter in a Configuration instance :param name: canonical name of the parameter to search for :type name: str :param names: alternative aliases of the parameter :type names: tuple(str) :param instance: instance of the configuration to search within :type instance: Configuration Returns (List(RawParameter)): matches of the parameter found in the configuration. .. py:method:: load(name, match) Loads a Parameter with the value in a RawParameter. :param name: name of the parameter to pass through :type name: str :param match: the value of the RawParameter match :type match: RawParameter Returns a LoadedParameter .. py:class:: SequenceParameter(element_type, default=(), validation=None, string_delimiter=',') Bases: :py:obj:`Parameter` Parameter type for a Configuration class that holds a sequence (i.e. list) of Parameters. :param element_type: The Parameter type that is held in the sequence. :type element_type: Parameter :param default: default value, empty tuple if not given. :type default: Sequence :param string_delimiter: separation string used to parse string into sequence. :type string_delimiter: str .. py:attribute:: _type .. py:method:: get_all_matches(name, names, instance) Finds all matches of a Parameter in a Configuration instance :param name: canonical name of the parameter to search for :type name: str :param names: alternative aliases of the parameter :type names: tuple(str) :param instance: instance of the configuration to search within :type instance: Configuration Returns (List(RawParameter)): matches of the parameter found in the configuration. .. py:method:: load(name, match) Loads a Parameter with the value in a RawParameter. :param name: name of the parameter to pass through :type name: str :param match: the value of the RawParameter match :type match: RawParameter Returns a LoadedParameter .. py:class:: ObjectParameter(element_type, default=ConfigurationObject(), validation=None) Bases: :py:obj:`Parameter` Parameter type for a Configuration class that holds an object with Parameter fields. :param element_type: The object type with parameter fields held in ObjectParameter. :type element_type: object :param default: default value, empty tuple if not given. :type default: Sequence .. py:attribute:: _type .. py:method:: get_all_matches(name, names, instance) Finds all matches of a Parameter in a Configuration instance :param name: canonical name of the parameter to search for :type name: str :param names: alternative aliases of the parameter :type names: tuple(str) :param instance: instance of the configuration to search within :type instance: Configuration Returns (List(RawParameter)): matches of the parameter found in the configuration. .. py:method:: load(name, match) Loads a Parameter with the value in a RawParameter. :param name: name of the parameter to pass through :type name: str :param match: the value of the RawParameter match :type match: RawParameter Returns a LoadedParameter .. py:class:: ParameterLoader(parameter_type, aliases=(), expandvars=False) ParameterLoader class contains the top level logic needed to load a parameter from start to finish. :param parameter_type: the type of Parameter that is stored in the loader. :type parameter_type: Parameter :param aliases: alternative aliases for the Parameter :type aliases: tuple(str) :param expandvars: whether or not to recursively expand environmental variables. :type expandvars: bool .. py:property:: name .. py:property:: names .. py:method:: _set_name(name) .. py:method:: __get__(instance, instance_type) .. py:method:: _raw_parameters_from_single_source(raw_parameters) .. py:method:: raw_parameters_from_single_source(name, names, raw_parameters) :staticmethod: .. py:class:: ConfigurationType(name, bases, attr) Bases: :py:obj:`type` metaclass for Configuration .. py:property:: _parameter_loaders :type: dict[str, ParameterLoader] .. py:method:: __call__(*args, **kwargs) Call self as a function. .. py:data:: CONDARC_FILENAMES :value: ('.condarc', 'condarc') .. py:data:: YAML_EXTENSIONS :value: ('.yml', '.yaml') .. py:data:: _RE_CUSTOM_EXPANDVARS .. py:function:: 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% - $$ → $$ - %% → %% - $ → $ - % → % .. py:class:: Configuration(search_path=(), app_name=None, argparse_args=None, **kwargs) .. py:method:: _set_parameter_names_and_aliases() :classmethod: Build parameter_names_and_aliases from the class's parameter loaders. .. py:method:: _expand_search_path(search_path: conda.common.path.PathsType, **kwargs) -> collections.abc.Iterable[pathlib.Path] :staticmethod: .. py:method:: _load_search_path(search_path: collections.abc.Iterable[pathlib.Path]) -> collections.abc.Iterable[tuple[pathlib.Path, dict]] :classmethod: .. py:method:: _set_search_path(search_path: conda.common.path.PathsType, **kwargs) .. py:method:: _set_env_vars(app_name=None) .. py:method:: _set_argparse_args(argparse_args) .. py:method:: _set_raw_data(raw_data: collections.abc.Mapping[collections.abc.Hashable, dict]) .. py:method:: 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. :param alias: The parameter alias to look up. :type alias: str :param ignore_private: If True (default), exclude private parameters (those starting with underscore) from the search. If False, include all parameters regardless of privacy. :type ignore_private: bool, optional :returns: The canonical parameter name if the alias is found, otherwise None. :rtype: str | None .. rubric:: Example >>> config = Configuration() >>> config.name_for_alias("channel_priority") 'channel_priority' >>> config.name_for_alias("unknown_alias") None .. py:method:: _get_parameter_loader(parameter_name) Get parameter loader with fallback for missing parameters. .. py:method:: _reset_cache() .. py:method:: register_reset_callaback(callback) .. py:method:: check_source(source) .. py:method:: validate_all() .. py:method:: _collect_validation_error(func, *args, **kwargs) :staticmethod: .. py:method:: validate_configuration() .. py:method:: post_build_validation() .. py:method:: collect_all() .. py:method:: describe_parameter(parameter_name) .. py:method:: list_parameters(aliases: bool = False) .. py:method:: typify_parameter(parameter_name, value, source) .. py:method:: get_descriptions() :abstractmethod: .. py:function:: unique_sequence_map(*, unique_key: str) Used to validate properties on :class:`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.