Python Dependency Manager Companion

(deep_dive_config_management)= # Programmatic `.condarc` File API This guide explains how to programmatically read and write conda configuration files (`.condarc`) using the `ConfigurationFile` class. This is useful for tools that need to modify conda settings without shelling out to `conda config` commands. ## Overview The `conda.cli.condarc.ConfigurationFile` class provides a high-level interface for reading, modifying, and writing conda configuration files (`.condarc`). It handles: - Configuration file validation - Type checking and conversion - Parameter existence checking - Atomic file operations via context manager - Support for sequence, map, and primitive parameters ## Basic Usage ### Reading Configuration ```python from conda.cli.condarc import ConfigurationFile # Read user's .condarc file config = ConfigurationFile.from_user_condarc() # Access the configuration content print(config.content) # {'channels': ['defaults', 'conda-forge'], 'auto_update_conda': False} # Get a specific key key, value = config.get_key("channels") print(f"{key}: {value}") # channels: ['defaults', 'conda-forge'] ``` ### Writing Configuration ```python from conda.cli.condarc import ConfigurationFile # Create a configuration file instance config = ConfigurationFile.from_user_condarc() # Set a primitive parameter config.set_key("auto_update_conda", False) # Add to a sequence parameter config.add("channels", "conda-forge", prepend=True) # Set a map parameter config.set_key("proxy_servers.http", "http://proxy.example.com") # Write changes to file config.write() ``` ### Using Context Manager For atomic operations, use the context manager pattern: ```python from conda.cli.condarc import ConfigurationFile # Changes are automatically written on successful exit with ConfigurationFile.from_user_condarc() as config: config.set_key("channels", ["conda-forge", "defaults"]) config.set_key("auto_update_conda", False) # File is written here automatically ``` If an exception occurs within the context, changes are not written: ```python try: with ConfigurationFile.from_user_condarc() as config: config.set_key("channels", ["conda-forge"]) raise ValueError("Something went wrong") except ValueError: pass # File was NOT modified because of the exception ``` ## Factory Methods The `ConfigurationFile` class provides several factory methods for common configuration file locations: ### User Configuration ```python from conda.cli.condarc import ConfigurationFile # User's .condarc file (typically ~/.condarc) config = ConfigurationFile.from_user_condarc() ``` ### System Configuration ```python from conda.cli.condarc import ConfigurationFile # System-wide .condarc file config = ConfigurationFile.from_system_condarc() ``` ### Environment Configuration ```python from conda.cli.condarc import ConfigurationFile # Environment-specific .condarc file at {prefix}/.condarc config = ConfigurationFile.from_env_condarc(prefix="/path/to/env") # Or use CONDA_PREFIX environment variable config = ConfigurationFile.from_env_condarc() ``` ### Custom Path ```python from pathlib import Path from conda.cli.condarc import ConfigurationFile # Custom configuration file path config = ConfigurationFile(path=Path("/custom/path/.condarc")) ``` ## Parameter Types Conda configuration parameters come in three types, and each supports different operations: ### Primitive Parameters Single scalar values (strings, numbers, booleans): ```python config.set_key("auto_update_conda", False) config.set_key("channel_priority", "strict") config.set_key("rollback_enabled", True) ``` ### Sequence Parameters Lists of values: ```python # Add to end of list config.add("channels", "conda-forge", prepend=False) # Add to beginning of list config.add("channels", "defaults", prepend=True) # Remove from list config.remove_item("channels", "conda-forge") ``` ### Map Parameters Dictionaries with nested values: ```python # Set a map entry config.set_key("proxy_servers.http", "http://proxy.example.com") config.set_key("proxy_servers.https", "https://proxy.example.com") # Add to a nested sequence within a map config.add("conda_build.config_file", "/path/to/config.yaml") ``` ## Key Validation The `ConfigurationFile` class validates keys against the current conda context: ```python from conda.cli.condarc import ConfigurationFile config = ConfigurationFile.from_user_condarc() # Check if a key exists if config.key_exists("channels"): print("channels is a valid parameter") # Attempting to set an invalid key raises an error try: config.set_key("invalid_key", "value") except Exception as e: print(f"Error: {e}") # Error: CondaKeyError: 'invalid_key': unknown parameter ``` ## Handling Missing Keys When getting a key that doesn't exist, the method returns a sentinel value: ```python from conda.cli.condarc import ConfigurationFile, MISSING config = ConfigurationFile(content={}) key, value = config.get_key("undefined_key") if value is MISSING: print(f"Key '{key}' not found in config") ``` ## Working with Plugin Configuration Plugin parameters use a `plugins.` prefix: ```python # Set a plugin-specific parameter config.set_key("plugins.custom_solver.enabled", True) # Add to a plugin sequence parameter config.add("plugins.custom_reporters.backends", "custom_backend") ``` ## Advanced Usage ### Custom Context You can provide a custom context instance for testing or specialized configurations: ```python from conda.base.context import Context from conda.cli.condarc import ConfigurationFile # Create a custom context custom_context = Context() # Use it with ConfigurationFile config = ConfigurationFile(path="/path/to/config", context=custom_context) ``` ### Warning Handlers Customize how warnings are reported: ```python warnings = [] def collect_warnings(msg): warnings.append(msg) config = ConfigurationFile(path="/path/to/config", warning_handler=collect_warnings) config.add("channels", "defaults", prepend=False) # If "defaults" already exists, a warning is collected print(warnings) ``` ### Manual Read/Write Control For more control over when files are read or written: ```python from conda.cli.condarc import ConfigurationFile config = ConfigurationFile(path="/path/to/.condarc") # Explicitly read config.read() # Make changes config.content["channels"] = ["conda-forge"] # Explicitly write config.write() # Or write to a different location config.write(path="/different/path/.condarc") ``` ### Working with Content Directly The `content` property provides direct access to the underlying configuration dictionary: ```python config = ConfigurationFile.from_user_condarc() # Access content current_channels = config.content.get("channels", []) # Modify content directly (use with caution) config.content["channels"] = ["conda-forge", "defaults"] config.write() ``` **Note**: Direct content manipulation bypasses validation. Use the provided methods (`set_key`, `add`, `remove_item`, etc.) for safer operations. ## Complete Example Here's a complete example that demonstrates multiple operations: ```python from conda.cli.condarc import ConfigurationFile # Use context manager for atomic operations with ConfigurationFile.from_user_condarc() as config: # Set primitive parameters config.set_key("auto_update_conda", False) config.set_key("channel_priority", "strict") # Configure channels config.set_key("channels", []) # Clear existing config.add("channels", "conda-forge", prepend=False) config.add("channels", "defaults", prepend=False) # Set proxy servers config.set_key("proxy_servers.http", "http://proxy.example.com:8080") config.set_key("proxy_servers.https", "https://proxy.example.com:8080") # Configure conda-build config.add("conda_build.config_file", "/path/to/conda_build_config.yaml") # Print current configuration print("Current configuration:") for key, value in config.content.items(): print(f" {key}: {value}") # File is automatically written when exiting the context manager print("Configuration saved!") ``` ## Migration Guide If you were previously using the private functions from `conda.cli.main_config`, here's how to migrate: ### Before (deprecated) ```python from conda.cli.main_config import ( _read_rc, _write_rc, _set_key, _get_key, _remove_key, ) # Old way rc_config = _read_rc("/path/to/.condarc") _set_key("auto_update_conda", False, rc_config) _write_rc("/path/to/.condarc", rc_config) ``` ### After (recommended) ```python from conda.cli.condarc import ConfigurationFile # New way config = ConfigurationFile(path="/path/to/.condarc") config.set_key("auto_update_conda", False) config.write() # Or even simpler with context manager with ConfigurationFile(path="/path/to/.condarc") as config: config.set_key("auto_update_conda", False) ``` ## Error Handling The `ConfigurationFile` class raises specific exceptions for different error conditions: ```python from conda.cli.condarc import ConfigurationFile from conda.exceptions import CondaKeyError, CondaValueError, CouldntParseError config = ConfigurationFile.from_user_condarc() try: # Unknown parameter config.set_key("unknown_param", "value") except CondaKeyError as e: print(f"Invalid key: {e}") try: # Invalid operation for parameter type config.set_key("channels", "not-a-list") except CondaKeyError as e: print(f"Invalid operation: {e}") try: # Adding to a non-sequence parameter config.add("auto_update_conda", "value") except CondaValueError as e: print(f"Type error: {e}") ``` ## Thread Safety The `ConfigurationFile` class is not thread-safe. If you need to access configuration from multiple threads, consider using locks or creating separate instances for each thread. ## Best Practices 1. **Use context managers**: For atomic operations, always use the context manager pattern to ensure changes are only written on success. 2. **Validate keys**: Use `key_exists()` to check parameter validity before attempting operations. 3. **Use factory methods**: Prefer `from_user_condarc()`, `from_system_condarc()`, and `from_env_condarc()` over manual path construction. 4. **Handle missing keys**: Always check for `MISSING` when using `get_key()` to handle undefined parameters gracefully. 5. **Avoid direct content manipulation**: Use the provided methods (`set_key`, `add`, etc.) instead of modifying `content` directly to ensure proper validation. 6. **Custom warning handlers**: For library code, provide custom warning handlers to integrate with your logging system. ## See Also - {ref}`deep_dive_context` - Understanding the conda context object - {doc}`/configuration` - User-facing configuration documentation - {doc}`/dev-guide/api/conda/cli/index` - CLI API documentation