"""
Utility functions for the components app.

These utilities can be used across multiple apps in the project.
"""
from datetime import datetime
from typing import Any


def format_atlas_event_date(value: Any) -> str:
    """
    Convert Atlas API eventDate to formatted date string.
    
    The Atlas API sometimes returns eventDate as a UTC timestamp in milliseconds
    (a bug in the API). This function handles both numeric timestamps and string dates.
    
    Args:
        value: Either a numeric timestamp (milliseconds) or a string date
        
    Returns:
        Formatted date string (DD/MM/YYYY) or the original value if already a string,
        or empty string if conversion fails
        
    Examples:
        >>> format_atlas_event_date(1609459200000)  # 2021-01-01 00:00:00 UTC
        '01/01/2021'
        
        >>> format_atlas_event_date('2021-01-01')
        '2021-01-01'
        
        >>> format_atlas_event_date(None)
        ''
    """
    if not value:
        return ''
    
    # If it's already a string, return it as-is
    if isinstance(value, str):
        return value
    
    # If it's a number (int or float), convert from timestamp
    if isinstance(value, (int, float)):
        try:
            # Convert milliseconds to seconds for datetime
            timestamp_seconds = int(value) / 1000
            dt = datetime.fromtimestamp(timestamp_seconds)
            return dt.strftime('%d/%m/%Y')
        except (ValueError, TypeError, OSError):
            return ''
    
    # For any other type, return empty string
    return ''