Skip to content

README.md

Latest commit

 

History

History
161 lines (124 loc) · 4.52 KB

README.md

File metadata and controls

161 lines (124 loc) · 4.52 KB

Util [⚡] Caching (caching.py)

Performance-oriented caching utilities with timing and monitoring capabilities.Module

This directory contains cross-cutting utilities that are used across multiple modules in the voodoo-box. These utilities provide common functionality for caching, logging, error handling, and other shared concerns.

Available Utilities

[⚡] Caching (caching.py)

Performance-oriented caching utilities with timing and monitoring capabilities.

Key Features:

  • TimedLRUCache: LRU cache with performance timing
  • simple_cache: Easy-to-use caching decorator
  • CacheStats: Cache performance analysis

Usage Example:

from voodoo_box.utils.caching import TimedLRUCache, simple_cache

@TimedLRUCache(maxsize=64)
def expensive_api_call(player_id):
    # Expensive operation
    return api_response

@simple_cache(maxsize=32)
def calculate_stats(data):
    return processed_data

Logging (logging.py)

Comprehensive logging setup with colored console output and JSON file logging.

Key Features:

  • LoggerSetup: Centralized logger configuration
  • ColoredFormatter: Console output with colors
  • JSONFileHandler: Structured JSON log files
  • PerformanceLogger: Context manager for timing operations

Usage Example:

from voodoo_box.utils.logging import setup_project_logging, PerformanceLogger

# Set up project loggers
loggers = setup_project_logging("my_project", debug=True)
logger = loggers['main']

# Use performance logging
with PerformanceLogger(loggers['performance'], "data_processing"):
    # Your operation here
    process_data()

Error Handling (error_handling.py)

Robust error handling with retry logic, circuit breakers, and validation.

Key Features:

  • retry_with_backoff: Automatic retry with exponential backoff
  • CircuitBreaker: Circuit breaker pattern for external services
  • ErrorHandler: Centralized error handling and statistics
  • validate_input: Input validation decorators

Usage Example:

from voodoo_box.utils.error_handling import (
    retry_with_backoff, CircuitBreaker, RetryConfig, ErrorHandler
)

# Retry configuration
@retry_with_backoff(RetryConfig(max_attempts=5))
def api_call():
    # Code that might fail
    pass

# Circuit breaker for external services
@CircuitBreaker(failure_threshold=3)
def external_service_call():
    # External service interaction
    pass

# Error handling context
error_handler = ErrorHandler()
with ExceptionContext(error_handler, {"operation": "data_load"}):
    load_data()

Integration Patterns

Multi-Module Usage

# Example: Using multiple utilities together
from voodoo_box.utils.logging import setup_project_logging
from voodoo_box.utils.caching import TimedLRUCache
from voodoo_box.utils.error_handling import retry_with_backoff, RetryConfig

# Set up logging
loggers = setup_project_logging("my_app")
logger = loggers['main']

# Create cached function with retry logic
@TimedLRUCache(maxsize=64)
@retry_with_backoff(RetryConfig(max_attempts=3))
def robust_api_call(endpoint):
    logger.info(f"Calling API endpoint: {endpoint}")
    # API call logic
    return response

Error Monitoring

from voodoo_box.utils.error_handling import ErrorHandler
from voodoo_box.utils.logging import setup_project_logging

loggers = setup_project_logging("monitoring")
error_handler = ErrorHandler(loggers['main'])

# Monitor application errors
try:
    risky_operation()
except Exception as e:
    error_handler.handle_error(e, context={"user_id": "123"})

# Get error statistics
stats = error_handler.get_error_stats()
loggers['main'].info(f"Error statistics: {stats}")

Testing and Validation

All utilities include example usage and can be tested individually:

# Test caching utilities
python -m voodoo_box.utils.caching

# Test logging setup
python -m voodoo_box.utils.logging

# Test error handling
python -m voodoo_box.utils.error_handling

Best Practices

  1. Logging Strategy: Use structured logging with appropriate levels
  2. Cache Management: Monitor cache hit rates and clear when needed
  3. Error Handling: Use circuit breakers for external services
  4. Performance: Combine caching with performance logging for optimization
  5. Context: Always provide context when handling errors

Dependencies

  • Standard library only (no external dependencies)
  • Compatible with Python 3.7+
  • Works with both Windows and Unix systems

Future Enhancements

  • Async versions of utilities
  • Metrics collection and monitoring
  • Configuration file support
  • Database logging handlers