LEDMatrix/src/common

Common Utilities

This directory contains reusable utilities and helpers for LEDMatrix plugins and core modules.

Error Handling (error_handler.py)

Common error handling patterns and utilities:

• handle_file_operation() - Handle file I/O with consistent error handling
• handle_json_operation() - Handle JSON operations with error handling
• safe_execute() - Safely execute operations with error handling
• retry_on_failure() - Decorator for retrying failed operations
• log_and_continue() - Log non-critical errors and continue
• log_and_raise() - Log errors and raise exceptions

Example Usage

from src.common.error_handler import handle_json_operation, safe_execute

# Handle JSON loading
config = handle_json_operation(
    lambda: json.load(open('config.json')),
    "Failed to load config",
    logger,
    default={}
)

# Safe execution with error handling
result = safe_execute(
    lambda: risky_operation(),
    "Operation failed",
    logger,
    default=None
)

API Helpers (api_helper.py)

Utilities for making HTTP requests and handling API responses.

Configuration Helpers (config_helper.py)

Utilities for loading, saving, and validating configuration files.

Display Helpers (display_helper.py)

Utilities for rendering content to the LED matrix display.

Game Helpers (game_helper.py)

Utilities for processing game data and team information.

Logo Helpers (logo_helper.py)

Utilities for loading and managing team logos.

Text Helpers (text_helper.py)

Utilities for text processing and formatting.

Scroll Helpers (scroll_helper.py)

Utilities for scrolling text on the display.

General Utilities (utils.py)

General-purpose utility functions:

• Team abbreviation normalization
• Time formatting
• Boolean parsing
• Logger creation (deprecated - use src.logging_config.get_logger())

Permission Utilities (permission_utils.py)

Helpers for ensuring directory permissions and ownership are correct when running as a service (used by CacheManager to set up its persistent cache directory).

CLI Helpers (cli.py)

Shared CLI argument parsing helpers used by scripts/dev/* and other command-line entry points.

Best Practices

1. Use centralized logging: Import from src.logging_config instead of creating loggers directly
2. Use error handlers: Use error_handler utilities for consistent error handling
3. Reuse utilities: Check existing utilities before creating new ones
4. Document additions: Add documentation when adding new utilities