condarc

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

_MissingSentinel	Sentinel value to indicate a missing configuration key.
ParameterTypeGroups	Groups configuration parameters by their parameter type.
ConfigurationFile	Represents and manipulates a conda configuration (.condarc) file.

Functions

_register_enum_representers(→ None)	Register YAML representers for conda enum types.
validate_provided_parameters(→ None)	Validate that provided parameters exist in the configuration context.

Attributes

MISSING

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

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.

__repr__()

Return repr(self).

__bool__()

__eq__(other)

Return self==value.

__hash__()

Return hash(self).

MISSING

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.

Parameters:

context -- Configuration instance containing configuration parameters.

sequence_parameters() → list[str]

List of sequence parameter names.

plugin_sequence_parameters() → list[str]

List of plugin sequence parameter names.

map_parameters() → list[str]

List of map parameter names.

plugin_map_parameters() → list[str]

List of plugin map parameter names.

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.

Parameters:

• parameters -- Regular parameter names to validate.

• plugin_parameters -- Plugin parameter names to validate.

• context -- Configuration instance containing available parameters.

Raises:

ArgumentError -- If any provided parameters are not valid.

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

property path: 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.

property context: 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.

property context_params: ParameterTypeGroups

property content: dict[str, Any]

Get the configuration content, reading from file if needed.

Returns:

Dictionary containing configuration content.

classmethod from_user_condarc(context: conda.common.configuration.Configuration | None = None) → ConfigurationFile

Create a ConfigurationFile instance for the default user .condarc file.

Parameters:

context -- Optional Configuration instance. If None, uses the global context.

Returns:

ConfigurationFile instance configured for the user's .condarc file.

classmethod from_system_condarc(context: conda.common.configuration.Configuration | None = None) → ConfigurationFile

Create a ConfigurationFile instance for the system .condarc file.

Parameters:

context -- Optional Configuration instance. If None, uses the global context.

Returns:

ConfigurationFile instance configured for the system .condarc file.

classmethod from_env_condarc(prefix: str | os.PathLike[str] | pathlib.Path | None = None, context: conda.common.configuration.Configuration | None = None) → ConfigurationFile

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.

Parameters:

• prefix -- Path to the conda environment. If None, uses $CONDA_PREFIX or sys.prefix.

• context -- Optional Configuration instance. If None, uses the global context.

Returns:

ConfigurationFile instance configured for the environment's .condarc file.

__enter__() → ConfigurationFile

Enter the context manager.

__exit__(exc_type, exc_val, exc_tb) → None

Exit the context manager and write changes if no exception occurred.

read(path: str | os.PathLike[str] | pathlib.Path | None = None) → dict[str, Any]

Read configuration content from file.

Parameters:

path -- Optional path to read from. If None, uses the instance path.

Returns:

Dictionary containing configuration content.

write(path: str | os.PathLike[str] | pathlib.Path | None = None) → None

Write configuration content to file.

Parameters:

path -- Optional path to write to. If None, uses the instance path.

Raises:

CondaError -- If the file cannot be written.

key_exists(key: str) → bool

Check if a configuration key is valid.

Parameters:

key -- Configuration key to check.

Returns:

True if the key is valid, False otherwise.

add(key: str, item: Any, prepend: bool = False) → None

Add an item to a sequence configuration parameter.

Parameters:

• key -- Configuration key name (may contain dots for nested keys).

• item -- Item to add to the sequence.

• prepend -- If True, add to the beginning; if False, add to the end.

Raises:

• CondaValueError -- If the key is not a known sequence parameter.

• CouldntParseError -- If the key should be a list but isn't.

get_key(key: str) → tuple[str, Any | _MissingSentinel]

Get a configuration value by key.

Parameters:

key -- Configuration key name (may contain dots for nested keys).

Returns:

Tuple of (key, value) or (key, MISSING) if key doesn't exist.

set_key(key: str, item: Any) → None

Set a configuration value for a primitive or map parameter.

Parameters:

• key -- Configuration key name (may contain dots for nested keys).

• item -- Value to set.

Raises:

CondaKeyError -- If the key is unknown or invalid.

remove_item(key: str, item: Any) → None

Remove an item from a sequence configuration parameter.

Parameters:

• key -- Configuration key name.

• item -- Item to remove from the sequence.

Raises:

CondaKeyError -- If the key is unknown, undefined, or the item is not present.

remove_key(key: str) → None

Remove a configuration key entirely.

Parameters:

key -- Configuration key name (may contain dots for nested keys).

Raises:

CondaKeyError -- If the key is undefined in the config.