ALT Error Handling

Advanced error handling utilities for Python applications, providing decorators and context managers for consistent and robust error management.

Features

• 🎯 Consistent Error Handling: Decorators for standardized error handling across your application
• 🔄 Exception Conversion: Transform exceptions to match your application's error hierarchy
• 📝 Contextual Information: Add context to exceptions for better debugging
• 🛡️ Safe Execution: Execute functions with fallback values on error
• 🧹 Cleanup Guarantees: Ensure cleanup code runs even when errors occur
• 📊 Error Aggregation: Combine multiple errors into comprehensive error reports
• 🔗 Exception Chain Formatting: Format exception chains for logging

Installation

pip install ALT-error-handling

For development:

git clone https://github.com/Avilir/ALT-error-handling.git
cd ALT-error-handling
pip install -e ".[dev]"

Quick Start

Basic Error Handling

from alt_error_handling import handle_errors

@handle_errors(ValueError, TypeError, reraise=False, default_return=None)
def risky_function(data):
    # This function might raise ValueError or TypeError
    return process_data(data)

# If an error occurs, it will be logged and None will be returned
result = risky_function(invalid_data)

Adding Context to Errors

from alt_error_handling import error_context

def process_user_data(user_id, data):
    with error_context("processing user data", user_id=user_id, data_size=len(data)):
        # Any exception here will include the context information
        validate_data(data)
        transform_data(data)
        save_data(user_id, data)

Core Features

1. Error Handling Decorator

The handle_errors decorator provides comprehensive error handling with logging:

from alt_error_handling import handle_errors
import logging

# Set up logging
logger = logging.getLogger(__name__)

@handle_errors(
    IOError, 
    OSError,
    reraise=True,  # Re-raise after logging
    log_level=logging.ERROR,
    context="file operation",
    logger=logger
)
def read_config(path):
    with open(path) as f:
        return json.load(f)

2. Exception Conversion

Transform exceptions to match your application's error hierarchy:

from alt_error_handling import convert_exceptions

class DataValidationError(Exception):
    """Application-specific validation error"""
    pass

@convert_exceptions({
    ValueError: DataValidationError,
    TypeError: lambda e: DataValidationError(f"Invalid type: {e}"),
    KeyError: lambda e: DataValidationError(f"Missing field: {e}")
})
def validate_user_input(data):
    if not isinstance(data, dict):
        raise TypeError("Data must be a dictionary")
    if "username" not in data:
        raise KeyError("username")
    if not data["username"]:
        raise ValueError("Username cannot be empty")

3. Safe Execution

Execute functions with fallback values:

from alt_error_handling import safe_execute

# Parse JSON with fallback to empty dict
config = safe_execute(
    json.loads, 
    config_string, 
    default={},
    exceptions=(json.JSONDecodeError,)
)

# Calculate with fallback
result = safe_execute(
    lambda: x / y,
    default=float('inf'),
    exceptions=(ZeroDivisionError,)
)

4. Error Context Manager

Add debugging context to any code block:

from alt_error_handling import error_context, ErrorHandlingError

class DatabaseError(ErrorHandlingError):
    """Custom database error with context support"""
    pass

def update_user(user_id, updates):
    with error_context(
        "updating user",
        DatabaseError,
        user_id=user_id,
        update_fields=list(updates.keys())
    ):
        user = db.get_user(user_id)
        user.update(updates)
        db.save(user)

5. Cleanup Guarantees

Ensure cleanup code runs even when errors occur:

from alt_error_handling import ensure_cleanup

def cleanup_resources():
    close_connections()
    release_locks()
    clean_temp_files()

@ensure_cleanup(cleanup_resources)
def process_with_resources():
    acquire_locks()
    open_connections()
    # If this fails, cleanup_resources will still run
    do_processing()

6. Error Aggregation

Collect multiple errors for comprehensive error reporting:

from alt_error_handling import aggregate_errors

errors = []
for item in items:
    try:
        process_item(item)
    except Exception as e:
        errors.append(e)

if errors:
    # Combine all errors into one comprehensive error
    raise aggregate_errors(
        errors,
        message="Failed to process items",
        exception_type=ProcessingError
    )

7. Exception Chain Formatting

Format exception chains for logging:

from alt_error_handling import format_exception_chain

try:
    risky_operation()
except Exception as e:
    # Get a formatted string of the exception chain
    error_details = format_exception_chain(e, include_traceback=True)
    logger.error(f"Operation failed:\n{error_details}")

Best Practices

1. Consistent Error Handling Strategy

# Define application-specific errors
class AppError(ErrorHandlingError):
    """Base application error"""
    pass

class ValidationError(AppError):
    """Validation error"""
    pass

class ProcessingError(AppError):
    """Processing error"""
    pass

# Use consistent error handling throughout
@handle_errors(Exception, reraise=True, context="data processing")
@convert_exceptions({
    ValueError: ValidationError,
    TypeError: ValidationError,
    RuntimeError: ProcessingError
})
def process_data(data):
    validate(data)
    return transform(data)

2. Layered Error Handling

# Low-level function with specific error handling
@handle_errors(IOError, OSError, reraise=False, default_return=None)
def read_file(path):
    with open(path) as f:
        return f.read()

# High-level function with broader error handling
@handle_errors(Exception, context="processing pipeline")
def process_files(file_paths):
    results = []
    for path in file_paths:
        with error_context("processing file", path=path):
            data = read_file(path)
            if data:
                results.append(transform_data(data))
    return results

3. Detailed Error Context

@handle_errors(Exception, reraise=True)
def complex_operation(user_id, data, options):
    with error_context(
        "complex operation",
        user_id=user_id,
        data_size=len(data),
        options=options,
        timestamp=datetime.now().isoformat()
    ):
        # Multiple steps with individual context
        with error_context("validation step"):
            validate_input(data, options)
        
        with error_context("processing step"):
            result = process(data)
        
        with error_context("save step"):
            save_result(user_id, result)
        
        return result

Advanced Usage

Custom Logging Function

def custom_error_logger(logger, error, context, details):
    # Send to monitoring service
    monitoring.send_error({
        'error_type': type(error).__name__,
        'error_message': str(error),
        'context': context,
        'function': details['function'],
        'timestamp': datetime.now().isoformat()
    })
    
    # Log locally
    logger.error(f"{context} failed: {error}")

@handle_errors(
    Exception,
    log_func=custom_error_logger,
    context="critical operation"
)
def critical_operation():
    # ...

Conditional Error Handling

def make_error_handler(debug_mode=False):
    return handle_errors(
        Exception,
        reraise=debug_mode,  # Reraise in debug mode
        default_return=None if not debug_mode else ...,
        log_level=logging.DEBUG if debug_mode else logging.ERROR
    )

# Use based on configuration
@make_error_handler(debug_mode=app.config.DEBUG)
def application_function():
    # ...

Testing

The library includes comprehensive tests. Run them with:

# Run all tests
pytest

# Run with coverage
pytest --cov=alt_error_handling

# Run specific test file
pytest tests/test_core.py

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/Avilir/ALT-error-handling.git
cd ALT-error-handling

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Quality Checks

# Type checking
mypy src

# Linting
ruff check .

# Formatting
black .

# All checks
make check  # If Makefile is available

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Avi Layani
Email: alayani@redhat.com

Acknowledgments

• Inspired by error handling patterns in various Python frameworks
• Built with modern Python development best practices
• Type hints for better IDE support and code clarity