:py:mod:`condarc` ================= .. py:module:: conda.cli.condarc .. autoapi-nested-parse:: Configuration file manipulation utilities for conda. This module provides classes and functions for working with conda configuration files (.condarc), including reading, writing, and validating configuration keys. Classes ------- .. autoapisummary:: conda.cli.condarc._MissingSentinel conda.cli.condarc.ParameterTypeGroups conda.cli.condarc.ConfigurationFile Functions --------- .. autoapisummary:: conda.cli.condarc._register_enum_representers conda.cli.condarc.validate_provided_parameters Attributes ---------- .. autoapisummary:: conda.cli.condarc.MISSING .. py:function:: _register_enum_representers() -> None Register YAML representers for conda enum types. This function registers custom YAML representers for all conda enum types to ensure they are serialized as strings rather than complex objects. This is called once at module load time to ensure representers are available before any YAML serialization occurs. .. py:class:: _MissingSentinel Sentinel value to indicate a missing configuration key. This is used by ConfigurationFile.get_key() to distinguish between a key that doesn't exist and a key that exists but has a None value. .. py:method:: __repr__() .. py:method:: __bool__() .. py:method:: __eq__(other) .. py:method:: __hash__() .. py:data:: MISSING .. py:class:: ParameterTypeGroups(context: conda.common.configuration.Configuration) Groups configuration parameters by their parameter type. Organizes configuration parameters from a Configuration instance into sequence and map parameters, handling both regular and plugin parameters separately. This is primarily used by ConfigurationFile to efficiently determine which operations are valid for different configuration keys. Initialize ParameterTypeGroups by grouping parameters by type. :param context: Configuration instance containing configuration parameters. .. py:attribute:: _grouped_parameter .. py:property:: sequence_parameters :type: list[str] List of sequence parameter names. .. py:property:: plugin_sequence_parameters :type: list[str] List of plugin sequence parameter names. .. py:property:: map_parameters :type: list[str] List of map parameter names. .. py:property:: plugin_map_parameters :type: list[str] List of plugin map parameter names. .. py:function:: validate_provided_parameters(parameters: collections.abc.Sequence[str], plugin_parameters: collections.abc.Sequence[str], context: conda.common.configuration.Configuration) -> None Validate that provided parameters exist in the configuration context. Compares the provided parameters with the available parameters in the context and raises an error if any are invalid. :param parameters: Regular parameter names to validate. :param plugin_parameters: Plugin parameter names to validate. :param context: Configuration instance containing available parameters. :raises ArgumentError: If any provided parameters are not valid. .. py:class:: ConfigurationFile(path: str | os.PathLike[str] | pathlib.Path | None = None, context: conda.common.configuration.Configuration | None = None, content: dict[str, Any] | None = None, warning_handler: collections.abc.Callable[[str], None] | None = None) Represents and manipulates a conda configuration (.condarc) file. Provides methods to read, write, and modify configuration files while validating keys and maintaining proper structure. Can be used as a context manager for atomic edits: with ConfigurationFile.from_user_condarc() as config: config.set_key("channels", ["conda-forge"]) config.add("channels", "defaults") # File is automatically written when exiting the context .. py:attribute:: _path :value: None .. py:attribute:: _content :value: None .. py:attribute:: _context :value: None .. py:attribute:: _context_params :type: ParameterTypeGroups | None :value: None .. py:attribute:: warning_handler .. py:method:: from_user_condarc(context: conda.common.configuration.Configuration | None = None) -> ConfigurationFile :classmethod: Create a ConfigurationFile instance for the default user .condarc file. :param context: Optional Configuration instance. If None, uses the global context. :returns: ConfigurationFile instance configured for the user's .condarc file. .. py:method:: from_system_condarc(context: conda.common.configuration.Configuration | None = None) -> ConfigurationFile :classmethod: Create a ConfigurationFile instance for the system .condarc file. :param context: Optional Configuration instance. If None, uses the global context. :returns: ConfigurationFile instance configured for the system .condarc file. .. py:method:: from_env_condarc(prefix: str | os.PathLike[str] | pathlib.Path | None = None, context: conda.common.configuration.Configuration | None = None) -> ConfigurationFile :classmethod: Create a ConfigurationFile instance for an environment-specific .condarc file. Environment-specific .condarc files are located at `{prefix}/.condarc` and allow per-environment configuration overrides. :param prefix: Path to the conda environment. If None, uses $CONDA_PREFIX or sys.prefix. :param context: Optional Configuration instance. If None, uses the global context. :returns: ConfigurationFile instance configured for the environment's .condarc file. .. py:method:: __enter__() -> ConfigurationFile Enter the context manager. .. py:method:: __exit__(exc_type, exc_val, exc_tb) -> None Exit the context manager and write changes if no exception occurred. .. py:property:: path :type: str | os.PathLike[str] | pathlib.Path Get the path to the configuration file. :returns: Path to the configuration file. :raises AttributeError: If path has not been set. .. py:property:: context :type: conda.common.configuration.Configuration Get the context instance. If no context was provided during initialization, falls back to the global conda context singleton. This lazy import is necessary to avoid circular dependencies at module load time. :returns: Configuration instance. .. py:property:: context_params :type: ParameterTypeGroups .. py:property:: content :type: dict[str, Any] Get the configuration content, reading from file if needed. :returns: Dictionary containing configuration content. .. py:method:: read(path: str | os.PathLike[str] | pathlib.Path | None = None) -> dict[str, Any] Read configuration content from file. :param path: Optional path to read from. If None, uses the instance path. :returns: Dictionary containing configuration content. .. py:method:: write(path: str | os.PathLike[str] | pathlib.Path | None = None) -> None Write configuration content to file. :param path: Optional path to write to. If None, uses the instance path. :raises CondaError: If the file cannot be written. .. py:method:: key_exists(key: str) -> bool Check if a configuration key is valid. :param key: Configuration key to check. :returns: True if the key is valid, False otherwise. .. py:method:: add(key: str, item: Any, prepend: bool = False) -> None Add an item to a sequence configuration parameter. :param key: Configuration key name (may contain dots for nested keys). :param item: Item to add to the sequence. :param prepend: If True, add to the beginning; if False, add to the end. :raises CondaValueError: If the key is not a known sequence parameter. :raises CouldntParseError: If the key should be a list but isn't. .. py:method:: get_key(key: str) -> tuple[str, Any | _MissingSentinel] Get a configuration value by key. :param key: Configuration key name (may contain dots for nested keys). :returns: Tuple of (key, value) or (key, MISSING) if key doesn't exist. .. py:method:: set_key(key: str, item: Any) -> None Set a configuration value for a primitive or map parameter. :param key: Configuration key name (may contain dots for nested keys). :param item: Value to set. :raises CondaKeyError: If the key is unknown or invalid. .. py:method:: remove_item(key: str, item: Any) -> None Remove an item from a sequence configuration parameter. :param key: Configuration key name. :param item: Item to remove from the sequence. :raises CondaKeyError: If the key is unknown, undefined, or the item is not present. .. py:method:: clear_key(key: str) -> None Clear all values from a sequence configuration parameter. The key remains explicitly configured with an empty list. This differs from ``remove_key()``, which removes the key entirely and may allow a value from another configuration source or a default to take effect. :param key: Sequence configuration key name. :raises CondaKeyError: If the key is unknown or is not a sequence parameter. :raises CouldntParseError: If the configured value is not a sequence. .. py:method:: remove_key(key: str) -> None Remove a configuration key entirely. :param key: Configuration key name (may contain dots for nested keys). :raises CondaKeyError: If the key is undefined in the config.