utils.py

"""
Utility functions for the USA Swimming scraper
"""

import re
import logging
from typing import Optional, Union

def clean_text(text: str) -> str:
    """Clean and normalize text data"""
    if not text:
        return ""
    
    # Remove extra whitespace and normalize
    text = re.sub(r'\s+', ' ', text.strip())
    
    # Remove special characters that might cause issues
    text = text.replace('\xa0', ' ')  # Non-breaking space
    text = text.replace('\u200b', '')  # Zero-width space
    
    return text

def parse_swim_time(time_str: str) -> Optional[float]:
    """
    Parse a swim time string and convert to seconds
    
    Examples:
        "20.37r" -> 20.37
        "1:02.45" -> 62.45
        "15:23.78" -> 923.78
    """
    if not time_str:
        return None
    
    # Remove any non-numeric characters except : and .
    clean_time = re.sub(r'[^\d:.]', '', time_str)
    
    if not clean_time:
        return None
    
    try:
        # Handle different time formats
        if ':' in clean_time:
            parts = clean_time.split(':')
            if len(parts) == 2:
                # MM:SS.ss format
                minutes = int(parts[0])
                seconds = float(parts[1])
                return minutes * 60 + seconds
            elif len(parts) == 3:
                # HH:MM:SS.ss format
                hours = int(parts[0])
                minutes = int(parts[1])
                seconds = float(parts[2])
                return hours * 3600 + minutes * 60 + seconds
        else:
            # SS.ss format
            return float(clean_time)
    
    except (ValueError, IndexError):
        logging.warning(f"Could not parse swim time: {time_str}")
        return None

def format_swim_time(seconds: float) -> str:
    """Convert seconds back to swim time format"""
    if seconds is None:
        return ""
    
    if seconds < 60:
        return f"{seconds:.2f}"
    elif seconds < 3600:
        minutes = int(seconds // 60)
        secs = seconds % 60
        return f"{minutes}:{secs:05.2f}"
    else:
        hours = int(seconds // 3600)
        minutes = int((seconds % 3600) // 60)
        secs = seconds % 60
        return f"{hours}:{minutes:02d}:{secs:05.2f}"

def validate_event(event: str) -> bool:
    """Validate if an event string is properly formatted"""
    if not event:
        return False
    
    # Basic pattern: number + stroke + course
    pattern = r'^\d+\s+(FR|BK|BR|FL|IM)\s+(SCY|SCM|LCM)$'
    return bool(re.match(pattern, event))

def parse_age_group(age_group: str) -> tuple:
    """Parse age group string and return min/max ages"""
    if not age_group:
        return None, None
    
    # Handle special cases
    if age_group.lower() == 'open':
        return None, None
    elif '&' in age_group:
        if 'under' in age_group.lower():
            # "10 & Under"
            age = int(re.findall(r'\d+', age_group)[0])
            return None, age
        elif 'over' in age_group.lower():
            # "19 & Over"
            age = int(re.findall(r'\d+', age_group)[0])
            return age, None
    elif '-' in age_group:
        # "15-16"
        ages = re.findall(r'\d+', age_group)
        if len(ages) == 2:
            return int(ages[0]), int(ages[1])
    else:
        # Single age
        age_match = re.search(r'\d+', age_group)
        if age_match:
            age = int(age_match.group())
            return age, age
    
    return None, None

def extract_rank(rank_str: str) -> Union[int, str]:
    """Extract numeric rank from rank string, handling ties"""
    if not rank_str:
        return ""
    
    # Remove any non-numeric characters except for 'T' (tie)
    clean_rank = re.sub(r'[^\dT]', '', rank_str)
    
    # Handle tie notation
    if 'T' in clean_rank:
        return clean_rank
    
    # Try to convert to integer
    try:
        return int(clean_rank)
    except ValueError:
        return rank_str

def normalize_team_name(team_name: str) -> str:
    """Normalize team name for consistency"""
    if not team_name:
        return ""
    
    # Common normalization rules
    team_name = clean_text(team_name)
    
    # Remove common suffixes/prefixes that might vary
    team_name = re.sub(r'\b(swim|swimming|club|team|aquatic|aquatics)\b', '', team_name, flags=re.IGNORECASE)
    team_name = clean_text(team_name)
    
    return team_name

def validate_search_params(params: dict) -> list:
    """Validate search parameters and return list of errors"""
    errors = []
    
    # Required parameters
    if 'event' not in params or not params['event']:
        errors.append("Event is required")
    elif not validate_event(params['event']):
        errors.append(f"Invalid event format: {params['event']}")
    
    # Optional parameter validation
    if 'year' in params:
        try:
            year = int(params['year'])
            if year < 1994 or year > 2025:
                errors.append(f"Year must be between 1994 and 2025: {year}")
        except ValueError:
            errors.append(f"Invalid year format: {params['year']}")
    
    if 'max_results' in params:
        try:
            max_results = int(params['max_results'])
            if max_results < 1 or max_results > 1000:
                errors.append("Max results must be between 1 and 1000")
        except ValueError:
            errors.append(f"Invalid max_results format: {params['max_results']}")
    
    return errors

def create_batch_query_template() -> str:
    """Create a template for batch query files"""
    template = """# USA Swimming Batch Query File
# Format: parameter=value (space-separated)
# Lines starting with # are comments

# Example queries:
year=2025 gender=Female age-group=15-16 event="50 FR SCY" max-results=50
year=2024 gender=Male age-group=Open event="100 FR LCM" time-standard="Summer Nationals"
year=2025 gender=Female age-group=13-14 event="200 IM SCY" exclude-foreign=true

# Available parameters:
# year, gender, age-group, event, time-standard, course, zone, lsc
# max-results, exclude-foreign, best-times-only
"""
    return template