Best Practices for Error Handling in Python

# File: practical/config_manager.py

import os
import json
import logging
from pathlib import Path
from typing import Any, Dict, Optional

# Set up logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger("ConfigManager")

# Custom exceptions
class ConfigError(Exception):
    """Base exception for configuration-related errors."""
    pass

class ConfigFileError(ConfigError):
    """Raised when there's an issue with the configuration file."""
    pass

class ConfigParseError(ConfigError):
    """Raised when parsing the configuration fails."""
    pass

class ConfigValidationError(ConfigError):
    """Raised when configuration validation fails."""
    pass

class ConfigManager:
    """A robust configuration manager with comprehensive error handling."""
    
    def __init__(self, app_name: str, config_dir: Optional[str] = None):
        """
        Initialize the configuration manager.
        
        Args:
            app_name: Name of the application (used for default directories)
            config_dir: Custom configuration directory (optional)
        """
        self.app_name = app_name
        
        # Set up configuration directory
        if config_dir:
            self.config_dir = Path(config_dir)
        else:
            # Use a default location based on platform
            if os.name == 'nt':  # Windows
                self.config_dir = Path(os.environ.get('APPDATA', '')) / app_name
            else:  # Unix/Linux/Mac
                self.config_dir = Path.home() / f".{app_name.lower()}"
        
        # Set up configuration file paths
        self.config_file = self.config_dir / "config.json"
        self.defaults_file = self.config_dir / "defaults.json"
        
        # Initialize configuration dictionary
        self.config = {}
        self.defaults = {}
        
        logger.info(f"Initialized ConfigManager for {app_name}")
        logger.info(f"Configuration directory: {self.config_dir}")
    
    def load(self, validate: bool = True) -> Dict[str, Any]:
        """
        Load configuration from files.
        
        Args:
            validate: Whether to validate the configuration
            
        Returns:
            The loaded configuration dictionary
            
        Raises:
            ConfigFileError: If there's an issue with the configuration files
            ConfigParseError: If parsing the configuration fails
            ConfigValidationError: If validation fails
        """
        logger.info("Loading configuration")
        
        # Load defaults
        try:
            self.defaults = self._load_config_file(self.defaults_file, required=False)
            logger.info(f"Loaded defaults: {len(self.defaults)} settings")
        except ConfigError as e:
            logger.warning(f"Could not load defaults: {e}")
            self.defaults = {}
        
        # Start with defaults
        self.config = self.defaults.copy() if self.defaults else {}
        
        # Load user configuration
        try:
            user_config = self._load_config_file(self.config_file, required=False)
            if user_config:
                logger.info(f"Loaded user configuration: {len(user_config)} settings")
                
                # Update defaults with user settings
                self.config.update(user_config)
        except ConfigError as e:
            logger.warning(f"Could not load user configuration: {e}")
        
        # Validate if requested
        if validate and self.config:
            try:
                self._validate_config(self.config)
                logger.info("Configuration validation passed")
            except ConfigValidationError as e:
                logger.error(f"Configuration validation failed: {e}")
                raise
        
        return self.config
    
    def save(self) -> None:
        """
        Save the current configuration to file.
        
        Raises:
            ConfigFileError: If there's an issue saving the configuration file
        """
        logger.info("Saving configuration")
        
        # Ensure the configuration directory exists
        try:
            os.makedirs(self.config_dir, exist_ok=True)
        except OSError as e:
            raise ConfigFileError(f"Could not create configuration directory: {e}")
        
        # Save the configuration
        try:
            with open(self.config_file, 'w', encoding='utf-8') as f:
                json.dump(self.config, f, indent=2)
            logger.info(f"Configuration saved to {self.config_file}")
        except (OSError, TypeError) as e:
            raise ConfigFileError(f"Error saving configuration: {e}")
    
    def get(self, key: str, default: Any = None) -> Any:
        """
        Get a configuration value.
        
        Args:
            key: Configuration key
            default: Default value if the key is not found
            
        Returns:
            The configuration value or default
        """
        return self.config.get(key, default)
    
    def set(self, key: str, value: Any) -> None:
        """
        Set a configuration value.
        
        Args:
            key: Configuration key
            value: Configuration value
        """
        self.config[key] = value
    
    def _load_config_file(self, filepath: Path, required: bool = True) -> Dict[str, Any]:
        """
        Load a configuration file.
        
        Args:
            filepath: Path to the configuration file
            required: Whether the file is required to exist
            
        Returns:
            The loaded configuration dictionary
            
        Raises:
            ConfigFileError: If there's an issue with the configuration file
            ConfigParseError: If parsing the configuration fails
        """
        # Check if the file exists
        if not filepath.exists():
            if required:
                raise ConfigFileError(f"Configuration file not found: {filepath}")
            else:
                logger.info(f"Configuration file not found (optional): {filepath}")
                return {}
        
        # Try to load the configuration
        try:
            with open(filepath, 'r', encoding='utf-8') as f:
                try:
                    return json.load(f)
                except json.JSONDecodeError as e:
                    raise ConfigParseError(f"Invalid JSON in {filepath}: {e}") from e
        except OSError as e:
            raise ConfigFileError(f"Error reading {filepath}: {e}")
    
    def _validate_config(self, config: Dict[str, Any]) -> None:
        """
        Validate configuration values.
        
        In a real application, this would check for required fields,
        type validation, range validation, etc.
        
        Args:
            config: Configuration dictionary to validate
            
        Raises:
            ConfigValidationError: If validation fails
        """
        # Example validation: check for required fields
        required_fields = ['log_level', 'debug']
        missing_fields = [field for field in required_fields if field not in config]
        
        if missing_fields:
            raise ConfigValidationError(
                f"Missing required configuration fields: {', '.join(missing_fields)}"
            )
        
        # Example validation: check field types
        if not isinstance(config.get('debug'), bool):
            raise ConfigValidationError(
                f"Field 'debug' must be a boolean, got: {type(config.get('debug')).__name__}"
            )
        
        # Example validation: check field values
        valid_log_levels = ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']
        if config.get('log_level') not in valid_log_levels:
            raise ConfigValidationError(
                f"Invalid log_level: {config.get('log_level')}. "
                f"Must be one of: {', '.join(valid_log_levels)}"
            )

# Example usage
def demonstrate_config_manager():
    # Create a configuration manager
    config_manager = ConfigManager("MyApp")
    
    try:
        # Try to load the configuration
        config = config_manager.load(validate=False)
        print(f"Loaded configuration: {config}")
        
        # Set some values
        config_manager.set('debug', True)
        config_manager.set('log_level', 'INFO')
        config_manager.set('max_threads', 4)
        
        # Save the configuration
        config_manager.save()
        print("Configuration saved")
        
        # Load and validate
        try:
            config = config_manager.load(validate=True)
            print("Configuration validated successfully")
        except ConfigValidationError as e:
            print(f"Validation error: {e}")
    except ConfigError as e:
        print(f"Configuration error: {e}")
    except Exception as e:
        print(f"Unexpected error: {e}")

# Run the demonstration
# demonstrate_config_manager()
                    

This example demonstrates a robust configuration management system that incorporates many error handling best practices:

• Custom exception hierarchy for different error types
• Specific error handling for different failure scenarios
• Proper cleanup with context managers
• Detailed logging for operational visibility
• Clear and specific error messages
• Input validation for early error detection