Chapter 13: Production-Ready Weather Dashboard Capstone

"""
Error handling infrastructure from Chapter 9.
Provides categorization, message composition, and retry logic.
"""
import requests
import time
import random
from typing import Optional, Dict, Any, Tuple
from datetime import datetime

# ============================================================================
# ERROR CATEGORIZATION (Chapter 9, Section 3)
# ============================================================================

def categorize_error(exception: Exception, response: Optional[requests.Response] = None, 
                    user_input: Optional[str] = None) -> str:
    """
    Map exceptions to four categories for systematic handling.
    Returns: 'user_input', 'transient', 'not_found', or 'unknown'
    From Chapter 9: Check order matters - user input first, then transient,
    then not found, finally unknown.
    """
    # 1. User input validation errors (check first)
    if user_input is not None:
        if not user_input or not user_input.strip():
            return 'user_input'
        if len(user_input) > 100:
            return 'user_input'
        if not any(c.isalpha() for c in user_input):
            return 'user_input'
    
    # 2. Network and timeout errors (transient - worth retrying)
    if isinstance(exception, (requests.exceptions.Timeout, 
                             requests.exceptions.ConnectionError)):
        return 'transient'
    
    # 3. HTTP errors - examine status code
    if isinstance(exception, requests.exceptions.HTTPError):
        if response is None:
            return 'unknown'
        
        status_code = response.status_code
        
        # Server errors (transient - worth retrying)
        if status_code >= 500:
            return 'transient'
        
        # Rate limiting (transient - worth retrying with delay)
        if status_code == 429:
            return 'transient'
        
        # Not found (permanent - don't retry)
        if status_code == 404:
            return 'not_found'
        
        # Other client errors (likely user input issue)
        if 400 <= status_code < 500:
            return 'user_input'
    
    # 4. Parsing and data errors (often means "no results")
    if isinstance(exception, (KeyError, ValueError, TypeError)):
        return 'not_found'
    
    # Everything else is unknown
    return 'unknown'


# ============================================================================
# MESSAGE COMPOSITION (Chapter 9, Section 4)
# ============================================================================

MESSAGE_TEMPLATES = {
    'user_input': {
        'empty': {
            'what': 'Please enter a city name to get weather information.',
            'how': 'Type the name of any city or town.',
            'examples': 'Examples: London, Paris, Tokyo'
        },
        'too_long': {
            'what': 'City names are typically short (under 100 characters).',
            'how': 'Please enter just the city name.',
            'examples': 'Examples: Paris, San Francisco'
        },
        'default': {
            'what': "We couldn't process that city name.",
            'how': 'Please use only letters, spaces, and hyphens.',
            'examples': 'Examples: São Paulo, New York'
        }
    },
    
    'not_found': {
        'with_city': {
            'what': 'We couldn\'t find weather data for "{city_name}".',
            'how': 'Please check the spelling or try a nearby city.',
            'examples': 'Examples: London, Dublin, Manchester'
        },
        'default': {
            'what': "We couldn't find that location in our database.",
            'how': 'Please try a different city name or check spelling.',
            'examples': 'Examples: Tokyo, New York, Sydney'
        }
    },
    
    'transient': {
        'default': {
            'what': "We're having trouble connecting to the weather service.",
            'how': 'This is usually temporary - please try again in a moment.',
            'examples': 'If the problem continues, check your internet connection.'
        },
        'rate_limited': {
            'what': "We're receiving too many requests right now.",
            'how': 'Please wait {retry_after} seconds, then try again.',
            'examples': 'This is a temporary limit from the provider.'
        }
    },
    
    'unknown': {
        'default': {
            'what': 'We encountered an unexpected problem.',
            'how': 'Please try again, or try a different city.',
            'examples': 'If this continues, the service may be unavailable.'
        }
    }
}


def compose_error_message(category: str, context: Optional[Dict[str, Any]] = None) -> str:
    """
    Generate three-part user messages from templates.
    
    From Chapter 9: Three parts - what happened, what to do, examples.
    """
    if context is None:
        context = {}
    
    city_name = context.get('city_name', '')
    retry_after = context.get('retry_after', 0)
    is_rate_limited = context.get('is_rate_limited', False)
    
    templates = MESSAGE_TEMPLATES.get(category, MESSAGE_TEMPLATES['unknown'])
    
    # Select variant within category
    if category == 'user_input':
        if not city_name or not city_name.strip():
            template = templates['empty']
        elif len(city_name) > 100:
            template = templates['too_long']
        else:
            template = templates['default']
    
    elif category == 'not_found':
        if city_name:
            template = templates['with_city']
        else:
            template = templates['default']
    
    elif category == 'transient':
        if is_rate_limited:
            template = templates['rate_limited']
        else:
            template = templates['default']
    
    else:
        template = templates['default']
    
    # Format with context
    what = template['what'].format(city_name=city_name, retry_after=retry_after)
    how = template['how'].format(city_name=city_name, retry_after=retry_after)
    examples = template['examples'].format(city_name=city_name, retry_after=retry_after)
    
    return f"{what}\n{how}\n{examples}"


# ============================================================================
# SIMPLE LOGGING (Chapter 9, Section 6)
# ============================================================================

def log_error_simple(category: str, exception: Exception, 
                    context: Optional[Dict[str, Any]] = None) -> None:
    """Simple console logging for debugging production issues."""
    timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
    print(f"\n[ERROR LOG] {timestamp}")
    print(f"  Category: {category}")
    print(f"  Exception: {type(exception).__name__}: {str(exception)}")
    if context:
        print(f"  User input: {context.get('city_name', 'N/A')}")
    print()


# ============================================================================
# UNIFIED ERROR HANDLER (Chapter 9, Section 6)
# ============================================================================

def handle_error(exception: Exception, context: Optional[Dict[str, Any]] = None,
                response: Optional[requests.Response] = None) -> None:
    """
    Unified error handling: categorize → log → compose → display.
    
    From Chapter 9: One call that orchestrates the complete error response.
    """
    if context is None:
        context = {}
    
    user_input = context.get('city_name', context.get('user_input'))
    
    # Categorize the error
    category = categorize_error(exception, response=response, user_input=user_input)
    
    # Log technical details
    log_error_simple(category, exception, context)
    
    # Add category-specific context for message composition
    if category == 'transient' and response and response.status_code == 429:
        context['is_rate_limited'] = True
        retry_after = response.headers.get('Retry-After', '0')
        try:
            context['retry_after'] = int(retry_after)
        except ValueError:
            context['retry_after'] = 0
    
    # Compose and display user-friendly message
    message = compose_error_message(category, context)
    print("\n" + message + "\n")


# ============================================================================
# SMART RETRY LOGIC (Chapter 9, Section 5)
# ============================================================================

def retry_request(url: str, params: Dict[str, Any], max_attempts: int = 3, 
                 timeout: float = 10.0, base_delay: float = 1.0, 
                 max_delay: float = 60.0) -> Optional[requests.Response]:
    """
    Make HTTP request with exponential backoff + jitter retry.
    
    From Chapter 9: Only retries transient failures (timeouts, 5xx).
    Respects Retry-After header for 429 responses.
    """
    for attempt in range(max_attempts):
        try:
            response = requests.get(url, params=params, timeout=timeout)
            
            # Special handling for 429 (Rate Limited)
            if response.status_code == 429:
                retry_after = response.headers.get('Retry-After')
                if retry_after and attempt < max_attempts - 1:
                    try:
                        wait_time = min(float(retry_after), max_delay)
                        print(f"Rate limited. Waiting {wait_time:.0f} seconds...")
                        time.sleep(wait_time)
                        continue
                    except ValueError:
                        pass  # Invalid Retry-After, fall through
                return response
            
            # Raise for HTTP errors (will be caught below)
            response.raise_for_status()
            return response
        
        except (requests.exceptions.Timeout, 
                requests.exceptions.ConnectionError) as e:
            if attempt == max_attempts - 1:
                return None
            
            # Exponential backoff with jitter (Chapter 9, Section 5.3)
            exponential_delay = min(base_delay * (2 ** attempt), max_delay)
            jitter = random.uniform(0, exponential_delay * 0.5)
            wait_time = exponential_delay + jitter
            
            print(f"Connection issue. Retrying in {wait_time:.1f} seconds...")
            time.sleep(wait_time)
            
        except requests.exceptions.HTTPError as e:
            # Only retry server errors (5xx)
            if e.response and e.response.status_code >= 500:
                if attempt == max_attempts - 1:
                    return None
                
                exponential_delay = min(base_delay * (2 ** attempt), max_delay)
                jitter = random.uniform(0, exponential_delay * 0.5)
                wait_time = exponential_delay + jitter
                
                print(f"Server error {e.response.status_code}. Retrying in {wait_time:.1f}s...")
                time.sleep(wait_time)
            else:
                # 4xx errors - don't retry
                return e.response
        
        except Exception:
            # Unexpected errors - don't retry
            return None
    
    return None

"""
JSON processing infrastructure from Chapter 10.
Provides safe navigation and response normalization.
"""
from typing import Any, List, Optional, Dict, Tuple

# Common collection wrapper keys across different APIs
COMMON_COLLECTION_KEYS = ["items", "results", "data", "content", "entries", "records"]


# ============================================================================
# SAFE NAVIGATION (Chapter 10, Section 4)
# ============================================================================

def safe_get(obj: Any, path: str, default: Any = None) -> Any:
    """
    Dot-path lookup: 'owner.login' → obj['owner']['login'] if present.
    
    From Chapter 10: Returns default if any part of path doesn't exist.
    Prevents crashes from missing nested fields.
    """
    cur = obj
    for part in path.split("."):
        if not isinstance(cur, dict) or part not in cur:
            return default
        cur = cur[part]
    return cur


def try_fields(d: Dict[str, Any], names: List[str], default: Any = None) -> Any:
    """
    Return first present/non-empty field from list of candidates.
    
    From Chapter 10: Useful when different APIs use different field names
    for the same data (e.g., 'id' vs 'order_id').
    """
    for name in names:
        val = d.get(name)
        if val not in (None, ""):
            return val
    return default


# ============================================================================
# COLLECTION NORMALIZATION (Chapter 10, Section 4)
# ============================================================================

def normalize_collection(api_response: Any, 
                        container_hints: Optional[List[str]] = None) -> List[Any]:
    """
    Return a list of items regardless of response shape.
    
    From Chapter 10: Handles direct arrays, wrapped collections, and single objects.
    - list          → itself
    - dict+wrapper  → wrapper list
    - dict (single) → [dict]
    - other         → []
    """
    # Direct array → pass through
    if isinstance(api_response, list):
        return api_response

    # Not a dict → can't extract anything
    if not isinstance(api_response, dict):
        return []

    # Check for common wrapper keys
    keys = (container_hints or []) + COMMON_COLLECTION_KEYS
    for key in keys:
        val = api_response.get(key)
        if isinstance(val, list):
            return val

    # No wrapper found → treat dict as single item
    return [api_response]


def extract_items_and_meta(api_response: Any,
                          container_hints: Optional[List[str]] = None
                          ) -> Tuple[List[Any], Dict[str, Any]]:
    """
    Return (items, metadata) and normalize pagination signals.
    
    From Chapter 10: Preserves metadata like totals and pagination cursors
    while extracting the actual data array.
    """
    meta: Dict[str, Any] = {}

    # Direct list → no metadata
    if isinstance(api_response, list):
        return api_response, meta

    # Not a dict → can't extract anything
    if not isinstance(api_response, dict):
        return [], meta

    # Find the collection container
    keys = (container_hints or []) + COMMON_COLLECTION_KEYS
    container_key = None
    for key in keys:
        if key in api_response and isinstance(api_response[key], list):
            container_key = key
            break

    # Extract items and separate metadata
    if container_key:
        items = api_response[container_key]
        # Everything else is metadata
        meta = {k: v for k, v in api_response.items() if k != container_key}
    else:
        # Single object response
        items = [api_response]
        meta = {}

    # Normalize pagination signals into common format
    meta_obj = meta.get("meta") if isinstance(meta.get("meta"), dict) else {}
    
    # Look for cursor-style pagination
    next_token = (
        meta_obj.get("cursor") or
        meta.get("cursor") or
        None
    )
    
    # Look for URL-style pagination
    if not next_token:
        links = meta.get("links") if isinstance(meta.get("links"), dict) else {}
        next_token = meta.get("nextPage") or links.get("next") or None

    # Extract count and page information
    total = meta.get("total") or meta.get("total_count") or meta_obj.get("total") or None
    page_info = {
        "page": meta.get("page") or meta_obj.get("page"),
        "per_page": meta.get("per_page") or meta_obj.get("per_page")
    }
    
    # Add normalized fields to metadata
    meta_norm = {"next_token": next_token, "total": total, "page_info": page_info}

    return items, {**meta, **meta_norm}


def first_item(api_response: Any, 
              container_hints: Optional[List[str]] = None) -> Optional[Dict[str, Any]]:
    """
    Get the first item (or None) across response variants.
    
    From Chapter 10: Convenience helper for single-resource endpoints.
    """
    items = normalize_collection(api_response, container_hints)
    return items[0] if items else None

"""
Validation infrastructure from Chapter 12.
Provides three-layer validation (structure → content → business rules).
"""
from typing import Tuple, Dict, Any, Optional


class ValidationError(Exception):
    """Custom exception for validation failures."""
    pass


# ============================================================================
# STRUCTURE VALIDATION (Chapter 12, Section 2, Layer 1)
# ============================================================================

def validate_structure(data: Any, required_sections: List[str]) -> Tuple[bool, Optional[str]]:
    """
    Validate response has expected top-level structure.
    
    From Chapter 12: Layer 1 catches shape errors before attempting access.
    Returns (is_valid, error_message).
    """
    # Must be a dictionary
    if not isinstance(data, dict):
        return False, "Response must be a dictionary"
    
    # Check required sections exist
    for section in required_sections:
        if section not in data:
            return False, f"Missing required section: '{section}'"
        
        # Section must be a dictionary (not primitive or array)
        if not isinstance(data[section], dict):
            return False, f"Section '{section}' must be a dictionary"
    
    return True, None


# ============================================================================
# CONTENT VALIDATION (Chapter 12, Section 2, Layer 2)
# ============================================================================

def validate_field_type(value: Any, field_name: str, 
                       expected_type: type) -> Tuple[bool, Optional[str]]:
    """
    Validate field has expected type and can be converted safely.
    
    From Chapter 12: Layer 2 checks individual field validity.
    """
    if value is None:
        return False, f"{field_name} cannot be None"
    
    try:
        # Attempt type conversion
        if expected_type == float:
            float(value)
        elif expected_type == int:
            int(value)
        elif expected_type == str:
            str(value)
        return True, None
    except (ValueError, TypeError):
        return False, f"{field_name} must be {expected_type.__name__}, got: {type(value).__name__}"


def validate_range(value: Any, field_name: str, 
                  min_val: Optional[float] = None, 
                  max_val: Optional[float] = None) -> Tuple[bool, Optional[str]]:
    """
    Validate numeric value is within realistic range.
    
    From Chapter 12: Catches sensor errors and placeholder values.
    """
    try:
        num_value = float(value)
    except (ValueError, TypeError):
        return False, f"{field_name} must be numeric"
    
    if min_val is not None and num_value < min_val:
        return False, f"{field_name} {num_value} below minimum {min_val}"
    
    if max_val is not None and num_value > max_val:
        return False, f"{field_name} {num_value} above maximum {max_val}"
    
    return True, None


# ============================================================================
# HELPER: SAFE TYPE CONVERSION (Chapter 12, Section 4)
# ============================================================================

def safe_float(value: Any, field_name: str) -> float:
    """
    Safely convert value to float with descriptive error.
    
    From Chapter 12: Defensive programming for API responses.
    """
    try:
        return float(value)
    except (ValueError, TypeError):
        raise ValidationError(f"Cannot convert {field_name} '{value}' to float")


def safe_int(value: Any, field_name: str) -> int:
    """
    Safely convert value to int with descriptive error.
    
    From Chapter 12: Defensive programming for API responses.
    """
    try:
        return int(value)
    except (ValueError, TypeError):
        raise ValidationError(f"Cannot convert {field_name} '{value}' to int")

"""
Weather API Client Layer - Resilient external communication.

Integrates Chapter 9's retry logic with weather-specific configuration.
Provides clean interfaces that hide resilience complexity from upper layers.
"""
from dataclasses import dataclass
from typing import Optional, Dict, Any
import os

# Import Chapter 9 utilities
from error_handling import retry_request, handle_error


@dataclass
class APIResult:
    """
    Standardized API response wrapper.
    
    Clean interface between API client and processing layers:
    - success: True if data is usable
    - data: Parsed JSON response (or None)
    - error_context: Information for error handling if failed
    """
    success: bool
    data: Optional[Dict[str, Any]]
    error_context: Optional[Dict[str, Any]] = None


class WeatherAPIClient:
    """
    Resilient client for weather and geocoding APIs.
    
    Applies Chapter 9's error handling patterns:
    - Retry with exponential backoff + jitter
    - Systematic error categorization
    - Three-part user messages
    """
    
    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize API client with configuration.
        
        Args:
            api_key: OpenWeatherMap API key (from environment if not provided)
        """
        self.api_key = api_key or os.getenv('OPENWEATHER_API_KEY')
        if not self.api_key:
            raise ValueError("API key required: set OPENWEATHER_API_KEY environment variable")
        
        # API endpoints
        self.geocoding_url = "http://api.openweathermap.org/geo/1.0/direct"
        self.weather_url = "http://api.openweathermap.org/data/2.5/weather"
        
        # Retry configuration (from Chapter 9, Section 5)
        self.max_retries = 3
        self.base_timeout = 10.0
        self.base_delay = 1.0
        self.max_delay = 60.0
    
    def fetch_geocoding(self, city_name: str, limit: int = 5) -> APIResult:
        """
        Fetch location coordinates with retry logic.
        
        Applies Chapter 9 patterns:
        - Uses retry_request() for resilient communication
        - Returns standardized APIResult
        - Error context for handle_error() if needed
        
        Args:
            city_name: City name to geocode
            limit: Maximum number of results to return
            
        Returns:
            APIResult with geocoding data or error context
        """
        params = {
            'q': city_name,
            'limit': limit,
            'appid': self.api_key
        }
        
        try:
            # Chapter 9's retry_request handles transient failures automatically
            response = retry_request(
                url=self.geocoding_url,
                params=params,
                max_attempts=self.max_retries,
                timeout=self.base_timeout,
                base_delay=self.base_delay,
                max_delay=self.max_delay
            )
            
            if response is None:
                # All retries exhausted - transient failure
                return APIResult(
                    success=False,
                    data=None,
                    error_context={
                        'city_name': city_name,
                        'api': 'geocoding',
                        'failure_type': 'connection'
                    }
                )
            
            # Check HTTP status
            if response.status_code == 401:
                return APIResult(
                    success=False,
                    data=None,
                    error_context={
                        'city_name': city_name,
                        'api': 'geocoding',
                        'failure_type': 'authentication'
                    }
                )
            
            if response.status_code >= 400:
                return APIResult(
                    success=False,
                    data=None,
                    error_context={
                        'city_name': city_name,
                        'api': 'geocoding',
                        'status_code': response.status_code,
                        'failure_type': 'http_error'
                    }
                )
            
            # Parse JSON response
            try:
                data = response.json()
            except ValueError as e:
                return APIResult(
                    success=False,
                    data=None,
                    error_context={
                        'city_name': city_name,
                        'api': 'geocoding',
                        'failure_type': 'invalid_json',
                        'exception': e
                    }
                )
            
            # Success - return data for processing layer
            return APIResult(success=True, data=data)
            
        except Exception as e:
            # Unexpected error - categorize and handle
            return APIResult(
                success=False,
                data=None,
                error_context={
                    'city_name': city_name,
                    'api': 'geocoding',
                    'failure_type': 'unexpected',
                    'exception': e
                }
            )
    
    def fetch_weather(self, latitude: float, longitude: float) -> APIResult:
        """
        Fetch weather data with retry logic.
        
        Applies Chapter 9 patterns:
        - Uses retry_request() for resilient communication
        - Returns standardized APIResult
        - Error context for handle_error() if needed
        
        Args:
            latitude: Location latitude
            longitude: Location longitude
            
        Returns:
            APIResult with weather data or error context
        """
        params = {
            'lat': latitude,
            'lon': longitude,
            'units': 'metric',  # Celsius
            'appid': self.api_key
        }
        
        try:
            # Chapter 9's retry_request handles transient failures automatically
            response = retry_request(
                url=self.weather_url,
                params=params,
                max_attempts=self.max_retries,
                timeout=self.base_timeout,
                base_delay=self.base_delay,
                max_delay=self.max_delay
            )
            
            if response is None:
                # All retries exhausted
                return APIResult(
                    success=False,
                    data=None,
                    error_context={
                        'api': 'weather',
                        'coordinates': (latitude, longitude),
                        'failure_type': 'connection'
                    }
                )
            
            # Check HTTP status
            if response.status_code >= 400:
                return APIResult(
                    success=False,
                    data=None,
                    error_context={
                        'api': 'weather',
                        'coordinates': (latitude, longitude),
                        'status_code': response.status_code,
                        'failure_type': 'http_error'
                    }
                )
            
            # Parse JSON response
            try:
                data = response.json()
            except ValueError as e:
                return APIResult(
                    success=False,
                    data=None,
                    error_context={
                        'api': 'weather',
                        'coordinates': (latitude, longitude),
                        'failure_type': 'invalid_json',
                        'exception': e
                    }
                )
            
            # Success
            return APIResult(success=True, data=data)
            
        except Exception as e:
            # Unexpected error
            return APIResult(
                success=False,
                data=None,
                error_context={
                    'api': 'weather',
                    'coordinates': (latitude, longitude),
                    'failure_type': 'unexpected',
                    'exception': e
                }
            )

"""
Normalized data structures for weather dashboard.

These models represent validated, trustworthy data that upper layers consume.
They hide API-specific response formats behind clean Python interfaces.
"""
from dataclasses import dataclass
from datetime import datetime
from typing import Optional, Dict, Any


@dataclass
class Location:
    """
    Validated location from geocoding API.
    
    From Chapter 10: Normalized structure regardless of API response variations.
    From Chapter 12: All fields validated before object creation.
    """
    name: str
    country: str
    state: Optional[str]
    latitude: float
    longitude: float
    
    # Metadata for debugging and quality assessment
    confidence_score: float  # 0.0 to 1.0
    raw_data: Dict[Any, Any]  # Original API response
    
    def display_name(self) -> str:
        """Human-readable location name."""
        parts = [self.name]
        if self.state:
            parts.append(self.state)
        parts.append(self.country)
        return ", ".join(parts)


@dataclass
class CurrentWeather:
    """
    Validated current weather conditions.
    
    From Chapter 12: All fields validated for type and realistic ranges.
    """
    temperature: float  # Celsius
    feels_like: float  # Celsius
    humidity: int  # Percentage (0-100)
    pressure: float  # hPa
    description: str
    icon: str
    
    # Optional fields
    visibility: Optional[float] = None  # kilometers
    wind_speed: Optional[float] = None  # km/h
    wind_direction: Optional[int] = None  # degrees
    
    def temperature_fahrenheit(self) -> float:
        """Convert temperature to Fahrenheit."""
        return (self.temperature * 9/5) + 32
    
    def feels_like_fahrenheit(self) -> float:
        """Convert feels-like temperature to Fahrenheit."""
        return (self.feels_like * 9/5) + 32


@dataclass
class WeatherData:
    """
    Complete validated weather information.
    
    Combines location and weather data with quality metadata.
    """
    location: Location
    current: CurrentWeather
    timestamp: datetime
    timezone: str
    
    # Quality metadata
    data_quality_score: float  # 0.0 to 1.0
    validation_warnings: list  # Non-fatal issues found during validation
    
    # Original response for debugging
    raw_data: Dict[Any, Any]

"""
Geocoding response processor.

Integrates:
- Chapter 10: Safe navigation and collection normalization
- Chapter 12: Three-layer validation (structure → content → business rules)
"""
from typing import List, Tuple, Optional
import requests

# Import Chapter 10 utilities
from json_processing import normalize_collection, safe_get

# Import Chapter 12 utilities
from validation import ValidationError, validate_structure, validate_range, safe_float

# Import data models
from data_models import Location


class GeocodingProcessor:
    """
    Process geocoding API responses into validated Location objects.
    
    Applies systematic validation:
    - Layer 1 (Structure): Response shape and required sections
    - Layer 2 (Content): Field types and realistic ranges
    - Layer 3 (Business Rules): Cross-field logic and confidence scoring
    """
    
    def __init__(self):
        """Initialize processor with validation rules."""
        # Required fields from API response (Chapter 12)
        self.required_fields = ['name', 'country', 'lat', 'lon']
        
        # Coordinate ranges for validation (Chapter 12)
        self.lat_range = (-90, 90)
        self.lon_range = (-180, 180)
    
    def process_response(self, api_response: Dict[Any, Any], 
                        city_name: str) -> List[Location]:
        """
        Process geocoding API response into validated Location objects.
        
        Integrates Chapter 10 + Chapter 12 patterns:
        1. Normalize collection structure (Chapter 10)
        2. Validate each location (Chapter 12, three layers)
        3. Sort by confidence (business logic)
        
        Args:
            api_response: Raw API response from geocoding service
            city_name: Original user input for error context
            
        Returns:
            List of validated Location objects, sorted by confidence
            
        Raises:
            ValidationError: If no valid locations can be extracted
        """
        # Chapter 10: Normalize collection (API returns direct array)
        locations_data = normalize_collection(api_response)
        
        if not locations_data:
            raise ValidationError(f"No locations found for '{city_name}'")
        
        # Process and validate each location
        validated_locations = []
        
        for i, location_data in enumerate(locations_data):
            try:
                # Apply three-layer validation
                validated_location = self._validate_location(location_data, i)
                validated_locations.append(validated_location)
                
            except ValidationError as e:
                # Log validation failure but continue processing others
                print(f"Warning: Skipping invalid location {i}: {e}")
                continue
        
        if not validated_locations:
            raise ValidationError(
                f"No valid locations found for '{city_name}'. "
                "All results failed validation."
            )
        
        # Business rule: Sort by confidence (highest first)
        validated_locations.sort(key=lambda loc: loc.confidence_score, reverse=True)
        
        return validated_locations
    
    def _validate_location(self, location_data: Dict[Any, Any], 
                          index: int) -> Location:
        """
        Validate single location with three-layer approach.
        
        From Chapter 12: Structure → Content → Business Rules
        """
        # LAYER 1: STRUCTURE VALIDATION
        # Check required fields exist (Chapter 12, Section 2)
        missing_fields = []
        for field in self.required_fields:
            if field not in location_data:
                missing_fields.append(field)
        
        if missing_fields:
            raise ValidationError(f"Missing required fields: {missing_fields}")
        
        # LAYER 2: CONTENT VALIDATION
        # Extract and validate coordinates (Chapter 12, Section 2)
        try:
            latitude = safe_float(location_data['lat'], 'latitude')
            longitude = safe_float(location_data['lon'], 'longitude')
        except ValidationError as e:
            raise ValidationError(f"Invalid coordinates: {e}")
        
        # Validate coordinate ranges (Chapter 12, Section 2)
        valid, error = validate_range(latitude, 'latitude', 
                                     min_val=self.lat_range[0], 
                                     max_val=self.lat_range[1])
        if not valid:
            raise ValidationError(error)
        
        valid, error = validate_range(longitude, 'longitude',
                                     min_val=self.lon_range[0],
                                     max_val=self.lon_range[1])
        if not valid:
            raise ValidationError(error)
        
        # Extract and validate text fields (Chapter 10: safe_get)
        name = str(safe_get(location_data, 'name', '')).strip()
        if not name:
            raise ValidationError("Empty location name")
        
        country = str(safe_get(location_data, 'country', '')).strip()
        if not country:
            raise ValidationError("Empty country")
        
        # Optional state field (Chapter 10: defensive extraction)
        state = safe_get(location_data, 'state')
        if state:
            state = str(state).strip()
            if not state:
                state = None
        
        # LAYER 3: BUSINESS RULES
        # Calculate confidence score based on data quality and position
        confidence_score = self._calculate_confidence(location_data, index)
        
        # Create validated Location object
        return Location(
            name=name,
            country=country,
            state=state,
            latitude=latitude,
            longitude=longitude,
            confidence_score=confidence_score,
            raw_data=location_data
        )
    
    def _calculate_confidence(self, location_data: Dict[Any, Any], 
                            index: int) -> float:
        """
        Calculate confidence score for location match.
        
        Business rules (Chapter 12, Layer 3):
        - Higher-ranked results get higher confidence
        - Presence of state increases confidence
        - Generic names decrease confidence
        """
        base_score = 1.0
        
        # Reduce confidence for lower-ranked results
        position_penalty = index * 0.1
        base_score -= position_penalty
        
        # Increase confidence if state is provided (more specific)
        if location_data.get('state'):
            base_score += 0.1
        
        # Reduce confidence for generic names
        name = location_data.get('name', '').lower()
        generic_names = ['city', 'town', 'village', 'municipality']
        if name in generic_names:
            base_score -= 0.2
        
        # Ensure score stays in valid range [0.0, 1.0]
        return max(0.0, min(1.0, base_score))

"""
Weather response processor.

Integrates:
- Chapter 10: Safe navigation for nested weather data
- Chapter 12: Three-layer validation with realistic ranges
"""
from datetime import datetime
from typing import List, Dict, Any

# Import Chapter 10 utilities
from json_processing import safe_get

# Import Chapter 12 utilities
from validation import ValidationError, validate_structure, validate_range
from validation import safe_float, safe_int

# Import data models
from data_models import Location, CurrentWeather, WeatherData


class WeatherProcessor:
    """
    Process weather API responses into validated WeatherData objects.
    
    Applies Chapter 12's three-layer validation:
    - Layer 1: Response structure
    - Layer 2: Field types and realistic ranges
    - Layer 3: Cross-field business rules
    """
    
    def __init__(self):
        """Initialize processor with validation rules."""
        # Required top-level sections (Chapter 12, Layer 1)
        self.required_sections = ['main', 'weather', 'dt', 'timezone']
        
        # Required fields within 'main' section (Chapter 12, Layer 2)
        self.main_required = ['temp', 'feels_like', 'humidity', 'pressure']
        
        # Realistic ranges for validation (Chapter 12, Layer 2)
        self.temp_range = (-100, 60)  # Celsius
        self.humidity_range = (0, 100)  # Percentage
        self.pressure_range = (800, 1200)  # hPa
    
    def process_response(self, api_response: Dict[Any, Any], 
                        location: Location) -> WeatherData:
        """
        Process weather API response into validated WeatherData object.
        
        Integrates Chapter 10 + Chapter 12:
        1. Validate structure (Chapter 12, Layer 1)
        2. Extract with safe navigation (Chapter 10)
        3. Validate content (Chapter 12, Layer 2)
        4. Apply business rules (Chapter 12, Layer 3)
        
        Args:
            api_response: Raw weather API response
            location: Validated location this weather corresponds to
            
        Returns:
            Validated WeatherData object
            
        Raises:
            ValidationError: If response fails validation
        """
        warnings = []
        
        # LAYER 1: STRUCTURE VALIDATION (Chapter 12)
        valid, error = validate_structure(api_response, self.required_sections)
        if not valid:
            raise ValidationError(f"Invalid weather response structure: {error}")
        
        # Extract main weather data section (Chapter 10: safe access)
        main_data = api_response['main']
        if not isinstance(main_data, dict):
            raise ValidationError("'main' section must be a dictionary")
        
        # Check required fields in main section
        missing_fields = [field for field in self.main_required 
                         if field not in main_data]
        if missing_fields:
            raise ValidationError(f"Missing main weather fields: {missing_fields}")
        
        # LAYER 2: CONTENT VALIDATION (Chapter 12)
        # Extract and validate temperature
        try:
            temperature = safe_float(main_data['temp'], 'temperature')
        except ValidationError as e:
            raise ValidationError(f"Invalid temperature: {e}")
        
        valid, error = validate_range(temperature, 'temperature',
                                     min_val=self.temp_range[0],
                                     max_val=self.temp_range[1])
        if not valid:
            raise ValidationError(error)
        
        # Extract and validate feels-like temperature
        try:
            feels_like = safe_float(main_data['feels_like'], 'feels_like')
        except ValidationError as e:
            raise ValidationError(f"Invalid feels_like: {e}")
        
        # Validate humidity
        try:
            humidity = safe_int(main_data['humidity'], 'humidity')
        except ValidationError as e:
            raise ValidationError(f"Invalid humidity: {e}")
        
        valid, error = validate_range(humidity, 'humidity',
                                     min_val=self.humidity_range[0],
                                     max_val=self.humidity_range[1])
        if not valid:
            raise ValidationError(error)
        
        # Validate pressure
        try:
            pressure = safe_float(main_data['pressure'], 'pressure')
        except ValidationError as e:
            raise ValidationError(f"Invalid pressure: {e}")
        
        valid, error = validate_range(pressure, 'pressure',
                                     min_val=self.pressure_range[0],
                                     max_val=self.pressure_range[1])
        if not valid:
            raise ValidationError(error)
        
        # Extract weather description (Chapter 10: safe_get with defaults)
        weather_list = safe_get(api_response, 'weather', [])
        if not weather_list:
            raise ValidationError("No weather conditions data")
        
        primary_weather = weather_list[0]
        description = str(safe_get(primary_weather, 'description', 'Unknown')).title()
        icon = str(safe_get(primary_weather, 'icon', ''))
        
        # Extract optional fields (Chapter 10: defensive extraction)
        visibility = safe_get(main_data, 'visibility')
        if visibility is not None:
            try:
                visibility = float(visibility) / 1000  # Convert meters to km
            except (ValueError, TypeError):
                visibility = None
                warnings.append("Could not parse visibility data")
        
        wind_speed = safe_get(api_response, 'wind.speed')
        if wind_speed is not None:
            try:
                wind_speed = float(wind_speed)
            except (ValueError, TypeError):
                wind_speed = None
                warnings.append("Could not parse wind speed")
        
        wind_direction = safe_get(api_response, 'wind.deg')
        if wind_direction is not None:
            try:
                wind_direction = int(wind_direction)
            except (ValueError, TypeError):
                wind_direction = None
                warnings.append("Could not parse wind direction")
        
        # Extract timestamp (Chapter 10: safe extraction)
        try:
            timestamp = datetime.fromtimestamp(api_response['dt'])
        except (ValueError, TypeError, OSError) as e:
            raise ValidationError(f"Invalid timestamp: {e}")
        
        # Extract timezone
        timezone = str(safe_get(api_response, 'timezone', 'UTC'))
        
        # LAYER 3: BUSINESS RULES (Chapter 12)
        # Validate feels-like vs actual temperature relationship
        temp_diff = abs(feels_like - temperature)
        if temp_diff > 20:
            warnings.append(
                f"Large difference between temperature ({temperature}°C) "
                f"and feels-like ({feels_like}°C)"
            )
        
        # Create validated CurrentWeather object
        current_weather = CurrentWeather(
            temperature=temperature,
            feels_like=feels_like,
            humidity=humidity,
            pressure=pressure,
            description=description,
            icon=icon,
            visibility=visibility,
            wind_speed=wind_speed,
            wind_direction=wind_direction
        )
        
        # Calculate data quality score
        quality_score = self._calculate_quality_score(api_response, warnings)
        
        # Create complete WeatherData object
        return WeatherData(
            location=location,
            current=current_weather,
            timestamp=timestamp,
            timezone=timezone,
            data_quality_score=quality_score,
            validation_warnings=warnings,
            raw_data=api_response
        )
    
    def _calculate_quality_score(self, api_response: Dict[Any, Any],
                                warnings: List[str]) -> float:
        """
        Calculate data quality score.
        
        Business logic (Chapter 12, Layer 3):
        - Reduce score for missing optional fields
        - Reduce score for validation warnings
        - Increase score for recent data
        """
        score = 1.0
        
        # Reduce score for missing optional fields
        if safe_get(api_response, 'visibility') is None:
            score -= 0.1
        
        if safe_get(api_response, 'wind.speed') is None:
            score -= 0.05
        
        # Reduce score for validation warnings
        score -= len(warnings) * 0.1
        
        # Increase score for recent data (less than 5 minutes old)
        try:
            data_age = datetime.now().timestamp() - api_response['dt']
            if data_age < 300:  # Less than 5 minutes
                score += 0.1
        except (KeyError, TypeError):
            pass
        
        # Ensure score stays in valid range
        return max(0.0, min(1.0, score))

"""Test the processing layer with real API responses."""

# Test 1: Valid geocoding response
print("=== Testing Processing Layer ===\n")
print("Test 1: Valid geocoding response")

geocoding_response = [
    {
        "name": "London",
        "country": "GB",
        "state": "England",
        "lat": 51.5074,
        "lon": -0.1278
    }
]

processor = GeocodingProcessor()
locations = processor.process_response(geocoding_response, "London")

print(f"Locations found: {len(locations)}")
print(f"First location: {locations[0].display_name()}")
print(f"Coordinates: ({locations[0].latitude}, {locations[0].longitude})")
print(f"Confidence: {locations[0].confidence_score:.2f}")
print()

# Test 2: Invalid coordinate range
print("Test 2: Invalid coordinate range")

invalid_response = [
    {
        "name": "Invalid",
        "country": "XX",
        "lat": 999,  # Out of range
        "lon": -0.1278
    }
]

try:
    locations = processor.process_response(invalid_response, "Invalid")
    print("ERROR: Should have raised ValidationError")
except ValidationError as e:
    print(f"âœ" Correctly caught invalid coordinates: {e}")
print()

# Test 3: Valid weather response
print("Test 3: Valid weather response")

weather_response = {
    "main": {
        "temp": 15.5,
        "feels_like": 14.2,
        "humidity": 72,
        "pressure": 1013.2
    },
    "weather": [
        {
            "description": "light rain",
            "icon": "10d"
        }
    ],
    "dt": int(datetime.now().timestamp()),
    "timezone": "Europe/London",
    "wind": {
        "speed": 5.2,
        "deg": 230
    }
}

weather_processor = WeatherProcessor()
location = locations[0]  # Use London from Test 1

weather_data = weather_processor.process_response(weather_response, location)

print(f"Temperature: {weather_data.current.temperature}°C")
print(f"Feels like: {weather_data.current.feels_like}°C")
print(f"Conditions: {weather_data.current.description}")
print(f"Quality score: {weather_data.data_quality_score:.2f}")
print(f"Warnings: {len(weather_data.validation_warnings)}")
print()

# Test 4: Temperature out of range
print("Test 4: Temperature out of realistic range")

invalid_weather = {
    "main": {
        "temp": 150,  # Unrealistic
        "feels_like": 145,
        "humidity": 72,
        "pressure": 1013.2
    },
    "weather": [{"description": "error", "icon": ""}],
    "dt": int(datetime.now().timestamp()),
    "timezone": "UTC"
}

try:
    weather_data = weather_processor.process_response(invalid_weather, location)
    print("ERROR: Should have raised ValidationError")
except ValidationError as e:
    print(f"âœ" Correctly caught unrealistic temperature: {e}")
print()

"""
Workflow result models for business logic layer.

These capture the complete state of a weather dashboard request,
including success/failure status, data, alternatives, and diagnostics.
"""
from dataclasses import dataclass, field
from typing import Optional, List, Dict, Any
from enum import Enum

from data_models import WeatherData, Location


class WorkflowStatus(Enum):
    """Status of workflow execution."""
    SUCCESS = "success"
    PARTIAL_SUCCESS = "partial_success"  # Got location but not weather
    FAILURE = "failure"


@dataclass
class WorkflowResult:
    """
    Complete result from weather dashboard workflow.
    
    Supports three outcomes:
    1. SUCCESS: weather_data is populated
    2. PARTIAL_SUCCESS: locations found but weather failed
    3. FAILURE: couldn't even find location
    
    From Chapter 9: Always returns result object, never raises exceptions.
    From Chapter 8: Preserves alternative locations for user selection.
    """
    status: WorkflowStatus
    
    # Primary results
    weather_data: Optional[WeatherData] = None
    locations: List[Location] = field(default_factory=list)
    
    # Error information (if not SUCCESS)
    error_message: Optional[str] = None
    error_category: Optional[str] = None  # From Chapter 9's four categories
    
    # User communication
    warnings: List[str] = field(default_factory=list)
    suggestions: List[str] = field(default_factory=list)
    
    # Diagnostic metadata
    processing_metadata: Dict[str, Any] = field(default_factory=dict)
    
    @property
    def succeeded(self) -> bool:
        """Quick check if workflow succeeded fully."""
        return self.status == WorkflowStatus.SUCCESS
    
    @property
    def has_weather(self) -> bool:
        """Check if weather data is available."""
        return self.weather_data is not None
    
    @property
    def has_locations(self) -> bool:
        """Check if location data is available."""
        return len(self.locations) > 0

"""
Weather dashboard orchestrator - coordinates complete workflow.

Integrates:
- Chapter 8: Multi-API orchestration patterns
- Chapter 9: Error categorization and handling
- Chapter 10: Data processing
- Chapter 12: Validation throughout
"""
import time
from typing import List

# Import all layers
from weather_api_client import WeatherAPIClient, APIResult
from geocoding_processor import GeocodingProcessor
from weather_processor import WeatherProcessor
from workflow_models import WorkflowResult, WorkflowStatus

# Import Chapter 9 utilities
from error_handling import categorize_error, handle_error

# Import Chapter 12 utilities
from validation import ValidationError


class WeatherOrchestrator:
    """
    Orchestrates complete weather dashboard workflow.
    
    From Chapter 8: Coordinates geocoding → weather workflow
    From Chapter 9: Systematic error handling at each step
    Produces WorkflowResult that presentation layer displays
    """
    
    def __init__(self, api_key: str):
        """
        Initialize orchestrator with all required components.
        
        Args:
            api_key: OpenWeatherMap API key
        """
        # Layer initialization
        self.api_client = WeatherAPIClient(api_key)
        self.geocoding_processor = GeocodingProcessor()
        self.weather_processor = WeatherProcessor()
    
    def get_weather(self, city_name: str) -> WorkflowResult:
        """
        Execute complete weather dashboard workflow.
        
        Workflow steps:
        1. Validate input
        2. Fetch geocoding data (with retry from Chapter 9)
        3. Process and validate locations (Chapter 10 + 12)
        4. Fetch weather data (with retry from Chapter 9)
        5. Process and validate weather (Chapter 10 + 12)
        6. Return complete result
        
        From Chapter 9: Never raises exceptions - always returns WorkflowResult
        
        Args:
            city_name: City name from user input
            
        Returns:
            WorkflowResult with status, data, and error context
        """
        start_time = time.time()
        processing_steps = []
        warnings = []
        suggestions = []
        
        # STEP 1: INPUT VALIDATION
        # From Chapter 12: Validate before making API calls
        step_start = time.time()
        
        if not city_name or not city_name.strip():
            # From Chapter 9: Categorize as user_input error
            return self._create_failure_result(
                error_message="City name cannot be empty",
                error_category="user_input",
                suggestions=[
                    "Please enter a city name",
                    "Examples: London, Paris, Tokyo"
                ],
                processing_steps=processing_steps,
                start_time=start_time
            )
        
        city_name = city_name.strip()
        
        if len(city_name) > 100:
            return self._create_failure_result(
                error_message=f"City name too long ({len(city_name)} characters)",
                error_category="user_input",
                suggestions=[
                    "Please enter just the city name",
                    "Maximum length: 100 characters"
                ],
                processing_steps=processing_steps,
                start_time=start_time
            )
        
        processing_steps.append({
            'step': 'input_validation',
            'duration': time.time() - step_start,
            'status': 'success'
        })
        
        # STEP 2: FETCH GEOCODING DATA
        # From Chapter 9: API client handles retry automatically
        step_start = time.time()
        
        geocoding_result = self.api_client.fetch_geocoding(city_name, limit=5)
        
        processing_steps.append({
            'step': 'geocoding_api',
            'duration': time.time() - step_start,
            'status': 'success' if geocoding_result.success else 'failed'
        })
        
        if not geocoding_result.success:
            # From Chapter 9: Use error context for categorization
            error_ctx = geocoding_result.error_context
            exception_type = error_ctx.get('failure_type', 'unknown')
            
            # Map failure types to Chapter 9's categories
            if exception_type == 'authentication':
                category = 'unknown'
                message = "API authentication failed"
                suggestions = ["Check API key configuration"]
            elif exception_type == 'connection':
                category = 'transient'
                message = f"Could not connect to geocoding service for '{city_name}'"
                suggestions = [
                    "Check your internet connection",
                    "Try again in a moment"
                ]
            else:
                category = 'unknown'
                message = f"Geocoding request failed for '{city_name}'"
                suggestions = ["Try again or try a different city"]
            
            return self._create_failure_result(
                error_message=message,
                error_category=category,
                suggestions=suggestions,
                processing_steps=processing_steps,
                start_time=start_time
            )
        
        # STEP 3: PROCESS AND VALIDATE LOCATIONS
        # From Chapter 10 + 12: Transform and validate response
        step_start = time.time()
        
        try:
            locations = self.geocoding_processor.process_response(
                geocoding_result.data, 
                city_name
            )
            
            processing_steps.append({
                'step': 'location_processing',
                'duration': time.time() - step_start,
                'status': 'success',
                'locations_found': len(locations)
            })
            
            # Add warning if confidence is low (from Chapter 12)
            if locations[0].confidence_score < 0.7:
                warnings.append(
                    f"Location match for '{city_name}' has low confidence. "
                    "Results may be imprecise."
                )
            
        except ValidationError as e:
            processing_steps.append({
                'step': 'location_processing',
                'duration': time.time() - step_start,
                'status': 'failed',
                'error': str(e)
            })
            
            return self._create_failure_result(
                error_message=f"Could not process location data for '{city_name}'",
                error_category='not_found',
                suggestions=[
                    "Check the spelling of the city name",
                    "Try a more specific name (include country or state)",
                    "Examples: 'London, UK' or 'Paris, France'"
                ],
                processing_steps=processing_steps,
                start_time=start_time
            )
        
        # Select primary location (highest confidence)
        primary_location = locations[0]
        
        # STEP 4: FETCH WEATHER DATA
        # From Chapter 9: API client handles retry automatically
        step_start = time.time()
        
        weather_result = self.api_client.fetch_weather(
            primary_location.latitude,
            primary_location.longitude
        )
        
        processing_steps.append({
            'step': 'weather_api',
            'duration': time.time() - step_start,
            'status': 'success' if weather_result.success else 'failed'
        })
        
        if not weather_result.success:
            # From Chapter 8: Partial success - return locations even without weather
            error_ctx = weather_result.error_context
            
            return WorkflowResult(
                status=WorkflowStatus.PARTIAL_SUCCESS,
                weather_data=None,
                locations=locations,
                error_message="Weather data unavailable",
                error_category='transient',
                warnings=warnings,
                suggestions=[
                    "Weather service is temporarily unavailable",
                    "Location data is still available above",
                    "Try again in a few moments"
                ],
                processing_metadata={
                    'steps': processing_steps,
                    'total_duration': time.time() - start_time
                }
            )
        
        # STEP 5: PROCESS AND VALIDATE WEATHER
        # From Chapter 10 + 12: Transform and validate response
        step_start = time.time()
        
        try:
            weather_data = self.weather_processor.process_response(
                weather_result.data,
                primary_location
            )
            
            processing_steps.append({
                'step': 'weather_processing',
                'duration': time.time() - step_start,
                'status': 'success',
                'quality_score': weather_data.data_quality_score
            })
            
            # Add quality warnings (from Chapter 12)
            if weather_data.data_quality_score < 0.8:
                warnings.append(
                    "Weather data quality is lower than normal. "
                    "Information may be less accurate."
                )
            
            # Include processor's validation warnings
            warnings.extend(weather_data.validation_warnings)
            
        except ValidationError as e:
            processing_steps.append({
                'step': 'weather_processing',
                'duration': time.time() - step_start,
                'status': 'failed',
                'error': str(e)
            })
            
            # Partial success - validation failed but location is good
            return WorkflowResult(
                status=WorkflowStatus.PARTIAL_SUCCESS,
                weather_data=None,
                locations=locations,
                error_message="Weather data validation failed",
                error_category='unknown',
                warnings=warnings,
                suggestions=[
                    "Weather data was incomplete or invalid",
                    "Location data is still available above",
                    "Try again shortly"
                ],
                processing_metadata={
                    'steps': processing_steps,
                    'total_duration': time.time() - start_time
                }
            )
        
        # SUCCESS - All steps completed
        return WorkflowResult(
            status=WorkflowStatus.SUCCESS,
            weather_data=weather_data,
            locations=locations,
            warnings=warnings,
            suggestions=[],
            processing_metadata={
                'steps': processing_steps,
                'total_duration': time.time() - start_time
            }
        )
    
    def _create_failure_result(self, error_message: str, error_category: str,
                              suggestions: List[str], processing_steps: List[Dict],
                              start_time: float) -> WorkflowResult:
        """
        Create standardized failure result.
        
        From Chapter 9: Consistent error result structure.
        """
        return WorkflowResult(
            status=WorkflowStatus.FAILURE,
            weather_data=None,
            locations=[],
            error_message=error_message,
            error_category=error_category,
            suggestions=suggestions,
            processing_metadata={
                'steps': processing_steps,
                'total_duration': time.time() - start_time
            }
        )

"""Test complete workflow orchestration."""
import os

# Test with real API (requires OPENWEATHER_API_KEY env var)
api_key = os.getenv('OPENWEATHER_API_KEY')
if not api_key:
    print("Set OPENWEATHER_API_KEY environment variable to test")
else:
    orchestrator = WeatherOrchestrator(api_key)
    
    print("=== Testing Complete Workflow ===\n")
    
    # Test 1: Valid city (success)
    print("Test 1: Valid city - full success")
    result = orchestrator.get_weather("London")
    print(f"Status: {result.status.value}")
    print(f"Has weather: {result.has_weather}")
    if result.has_weather:
        weather = result.weather_data
        print(f"Location: {weather.location.display_name()}")
        print(f"Temperature: {weather.current.temperature}°C")
        print(f"Conditions: {weather.current.description}")
        print(f"Quality: {weather.data_quality_score:.2f}")
    print(f"Warnings: {len(result.warnings)}")
    print(f"Processing time: {result.processing_metadata['total_duration']:.2f}s")
    print()
    
    # Test 2: Empty input (user error)
    print("Test 2: Empty input - validation failure")
    result = orchestrator.get_weather("")
    print(f"Status: {result.status.value}")
    print(f"Error category: {result.error_category}")
    print(f"Error message: {result.error_message}")
    print(f"Suggestions: {len(result.suggestions)}")
    print()
    
    # Test 3: Ambiguous city (low confidence warning)
    print("Test 3: Ambiguous city name")
    result = orchestrator.get_weather("Springfield")
    print(f"Status: {result.status.value}")
    if result.has_locations:
        print(f"Locations found: {len(result.locations)}")
        print(f"Primary: {result.locations[0].display_name()}")
        print(f"Confidence: {result.locations[0].confidence_score:.2f}")
    print(f"Warnings: {result.warnings}")
    print()
    
    # Test 4: Invalid city (not found)
    print("Test 4: Non-existent city")
    result = orchestrator.get_weather("Atlantis")
    print(f"Status: {result.status.value}")
    print(f"Error category: {result.error_category}")
    print(f"Has locations: {result.has_locations}")
    print(f"Suggestions ({len(result.suggestions)}):")
    for suggestion in result.suggestions:
        print(f"  - {suggestion}")
    print()

"""
Presentation layer for weather dashboard.

Transforms WorkflowResult into user-friendly displays.
Handles SUCCESS, PARTIAL_SUCCESS, and FAILURE states.
"""

def display_weather_result(result):
    """
    Display weather dashboard result with appropriate formatting.
    
    Args:
        result: WorkflowResult from orchestrator
    """
    print("\n" + "="*70)
    
    if result.status == WorkflowStatus.SUCCESS:
        _display_success(result)
    elif result.status == WorkflowStatus.PARTIAL_SUCCESS:
        _display_partial_success(result)
    else:  # FAILURE
        _display_failure(result)
    
    print("="*70 + "\n")


def _display_success(result):
    """Display successful weather data retrieval."""
    weather = result.weather_data
    location = weather.location
    current = weather.current
    
    # Header with location
    location_name = f"{location.name}"
    if location.admin1:
        location_name += f", {location.admin1}"
    location_name += f", {location.country}"
    
    print(f"🌤️  WEATHER FOR {location_name.upper()}")
    print("="*70)
    
    # Location confidence (if not perfect)
    if location.confidence_score < 1.0:
        print(f"\n📍 Location confidence: {location.confidence_score:.0%}")
    
    # Current conditions
    print(f"\n🌡️  CURRENT CONDITIONS")
    print(f"   Temperature:     {current.temperature:.1f}°C")
    
    # Show feels-like if significantly different
    temp_diff = abs(current.feels_like - current.temperature)
    if temp_diff > 2:
        print(f"   Feels like:      {current.feels_like:.1f}°C")
    
    print(f"   Description:     {current.description}")
    print(f"   Humidity:        {current.humidity}%")
    print(f"   Pressure:        {current.pressure:.0f} hPa")
    
    # Optional fields (only if available)
    if current.wind_speed:
        wind_str = f"   Wind:            {current.wind_speed:.1f} km/h"
        if current.wind_direction:
            compass = _degrees_to_compass(current.wind_direction)
            wind_str += f" from {compass}"
        print(wind_str)
    
    if current.visibility:
        print(f"   Visibility:      {current.visibility:.1f} km")
    
    # Data quality indicator
    print(f"\n📊 DATA QUALITY")
    print(f"   Updated:         {weather.timestamp.strftime('%Y-%m-%d %H:%M:%S')}")
    print(f"   Timezone:        {weather.timezone}")
    
    quality_description = _quality_score_description(weather.data_quality_score)
    print(f"   Quality:         {weather.data_quality_score:.0%} ({quality_description})")
    
    # Show validation warnings if any
    if weather.validation_warnings:
        print(f"\n⚠️  DATA WARNINGS:")
        for warning in weather.validation_warnings:
            print(f"   • {warning}")
    
    # Show alternative locations if multiple were found
    if len(result.locations) > 1:
        print(f"\n📋 OTHER LOCATIONS MATCHING YOUR SEARCH:")
        for i, alt_location in enumerate(result.locations[1:4], 1):  # Show top 3 alternatives
            alt_name = f"{alt_location.name}"
            if alt_location.admin1:
                alt_name += f", {alt_location.admin1}"
            alt_name += f", {alt_location.country}"
            print(f"   {i}. {alt_name} (confidence: {alt_location.confidence_score:.0%})")


def _display_partial_success(result):
    """Display partial success (location found, weather failed)."""
    print("⚠️  PARTIAL SUCCESS")
    print("="*70)
    
    print(f"\n✓ Location(s) found:")
    for i, location in enumerate(result.locations[:3], 1):
        location_name = f"{location.name}"
        if location.admin1:
            location_name += f", {location.admin1}"
        location_name += f", {location.country}"
        print(f"   {i}. {location_name}")
        print(f"      Coordinates: ({location.latitude:.4f}, {location.longitude:.4f})")
        print(f"      Confidence: {location.confidence_score:.0%}")
    
    # Show why weather failed
    print(f"\n✗ Weather data unavailable")
    print(f"   Reason: {result.error_message}")
    
    # Category-based guidance (from Chapter 9)
    if result.error_category == 'transient':
        print(f"\n💡 WHAT TO DO:")
        print(f"   • This is usually temporary")
        print(f"   • Try again in a few moments")
        print(f"   • Check your internet connection if problem persists")
    
    # Show warnings if any
    if result.warnings:
        print(f"\n⚠️  WARNINGS:")
        for warning in result.warnings:
            print(f"   • {warning}")


def _display_failure(result):
    """Display complete failure with Chapter 9's three-part guidance."""
    print("❌ UNABLE TO GET WEATHER DATA")
    print("="*70)
    
    # Three-part error message pattern from Chapter 9
    print(f"\n{result.error_message}")
    
    # Category-specific guidance
    if result.error_category == 'user_input':
        print(f"\n💡 WHAT TO DO:")
        print(f"   • Check the spelling of the city name")
        print(f"   • Try a more specific location (e.g., 'London, UK' instead of 'London')")
        print(f"   • Examples: 'New York, NY', 'Paris, France', 'Tokyo, Japan'")
    
    elif result.error_category == 'not_found':
        print(f"\n💡 WHAT TO DO:")
        print(f"   • Verify the spelling")
        print(f"   • Try a nearby major city")
        print(f"   • Use country codes for clarity (e.g., 'Birmingham, UK' vs 'Birmingham, AL')")
    
    elif result.error_category == 'transient':
        print(f"\n💡 WHAT TO DO:")
        print(f"   • This is usually temporary")
        print(f"   • Try again in a few moments")
        print(f"   • Check your internet connection")
    
    else:  # unknown
        print(f"\n💡 WHAT TO DO:")
        print(f"   • Try again with a different location")
        print(f"   • If problem persists, the service may be temporarily unavailable")
    
    # Show warnings if any
    if result.warnings:
        print(f"\n⚠️  WARNINGS:")
        for warning in result.warnings:
            print(f"   • {warning}")


def _degrees_to_compass(degrees):
    """Convert wind direction degrees to compass direction."""
    directions = ['N', 'NNE', 'NE', 'ENE', 'E', 'ESE', 'SE', 'SSE',
                 'S', 'SSW', 'SW', 'WSW', 'W', 'WNW', 'NW', 'NNW']
    index = round(degrees / 22.5) % 16
    return directions[index]


def _quality_score_description(score):
    """Convert quality score to human-readable description."""
    if score >= 0.9:
        return "Excellent"
    elif score >= 0.8:
        return "Good"
    elif score >= 0.7:
        return "Fair"
    else:
        return "Poor"

# Test the presentation layer with mock results
from workflow_models import WorkflowResult, WorkflowStatus
from data_models import WeatherData, Location, CurrentWeather
from datetime import datetime

print("=== Testing Presentation Layer ===\n")

# Test 1: Success display
print("Test 1: SUCCESS display")
mock_location = Location(
    name="London",
    country="United Kingdom",
    state="England",
    latitude=51.5074,
    longitude=-0.1278,
    confidence_score=0.95,
    raw_data={}
)

mock_weather = CurrentWeather(
    temperature=15.3,
    feels_like=13.8,
    humidity=72,
    pressure=1013.2,
    description="Light Rain",
    icon="10d",
    wind_speed=12.5,
    wind_direction=225,
    visibility=8.5
)

mock_weather_data = WeatherData(
    location=mock_location,
    current=mock_weather,
    timestamp=datetime.now(),
    timezone="Europe/London",
    data_quality_score=0.92,
    validation_warnings=[],
    raw_data={}
)

success_result = WorkflowResult(
    status=WorkflowStatus.SUCCESS,
    weather_data=mock_weather_data,
    locations=[mock_location],
    error_message=None,
    error_category=None,
    warnings=[],
    suggestions=[],
    processing_metadata={'total_duration': 1.23}
)

display_weather_result(success_result)

# Test 2: Partial success display
print("\nTest 2: PARTIAL_SUCCESS display")
partial_result = WorkflowResult(
    status=WorkflowStatus.PARTIAL_SUCCESS,
    weather_data=None,
    locations=[mock_location],
    error_message="Weather API temporarily unavailable",
    error_category='transient',
    warnings=[],
    suggestions=["Try again in a moment"],
    processing_metadata={'total_duration': 0.85}
)

display_weather_result(partial_result)

# Test 3: Failure display
print("\nTest 3: FAILURE display")
failure_result = WorkflowResult(
    status=WorkflowStatus.FAILURE,
    weather_data=None,
    locations=[],
    error_message="Could not find location 'Atlantis'",
    error_category='not_found',
    warnings=[],
    suggestions=["Check spelling", "Try a nearby city"],
    processing_metadata={'total_duration': 0.45}
)

display_weather_result(failure_result)

"""
Configuration management for weather dashboard.

Centralizes all configuration values and provides environment-based overrides.
"""
import os
from dataclasses import dataclass


@dataclass
class WeatherDashboardConfig:
    """Configuration for production weather dashboard."""
    
    # API Configuration
    api_key: str
    geocoding_url: str = "http://api.openweathermap.org/geo/1.0/direct"
    weather_url: str = "http://api.openweathermap.org/data/2.5/weather"
    
    # Retry Configuration (from Chapter 9)
    max_retries: int = 3
    base_timeout: float = 10.0
    base_delay: float = 1.0
    max_delay: float = 60.0
    
    # Validation Configuration
    min_input_length: int = 2
    max_input_length: int = 100
    
    # Display Configuration
    show_debug_info: bool = False
    max_alternative_locations: int = 3
    
    @classmethod
    def from_environment(cls):
        """
        Create configuration from environment variables.
        
        Returns:
            WeatherDashboardConfig with values from environment
            
        Raises:
            ValueError: If required environment variables are missing
        """
        api_key = os.getenv('OPENWEATHER_API_KEY')
        if not api_key:
            raise ValueError(
                "Missing required environment variable: OPENWEATHER_API_KEY\n"
                "Set it with: export OPENWEATHER_API_KEY='your_key_here'"
            )
        
        # Optional overrides from environment
        max_retries = int(os.getenv('WEATHER_MAX_RETRIES', '3'))
        base_timeout = float(os.getenv('WEATHER_TIMEOUT', '10.0'))
        show_debug = os.getenv('WEATHER_DEBUG', 'false').lower() == 'true'
        
        return cls(
            api_key=api_key,
            max_retries=max_retries,
            base_timeout=base_timeout,
            show_debug_info=show_debug
        )


def load_config():
    """
    Load configuration with error handling.
    
    Returns:
        WeatherDashboardConfig instance
    """
    try:
        return WeatherDashboardConfig.from_environment()
    except ValueError as e:
        print(f"\n❌ Configuration Error: {e}\n")
        raise

"""
Production Weather Dashboard - Main Application

Integrates all components into a complete, interactive application.
Demonstrates production-grade architecture and error handling.
"""
import sys
import signal
from datetime import datetime

# Import all layers
from config import load_config
from weather_orchestrator import WeatherOrchestrator
from display_weather import display_weather_result


class WeatherDashboardApp:
    """
    Main application coordinator for weather dashboard.
    
    Manages application lifecycle: initialization, interactive loop, shutdown.
    """
    
    def __init__(self, config):
        """
        Initialize application with configuration.
        
        Args:
            config: WeatherDashboardConfig instance
        """
        self.config = config
        self.orchestrator = None
        self.running = False
        self.request_count = 0
        self.start_time = None
        
        # Setup signal handlers for graceful shutdown
        signal.signal(signal.SIGINT, self._signal_handler)
        signal.signal(signal.SIGTERM, self._signal_handler)
    
    def initialize(self):
        """
        Initialize all application components.
        
        Returns:
            bool: True if initialization successful, False otherwise
        """
        print("\n🌤️  Production Weather Dashboard")
        print("=" * 70)
        print("Initializing components...")
        
        try:
            # Initialize orchestrator with all layers
            self.orchestrator = WeatherOrchestrator(self.config.api_key)
            
            # Configure orchestrator with config values
            self.orchestrator.api_client.max_retries = self.config.max_retries
            self.orchestrator.api_client.base_timeout = self.config.base_timeout
            
            print("✓ API client initialized")
            print("✓ Geocoding processor initialized")
            print("✓ Weather processor initialized")
            print("✓ Business logic coordinator initialized")
            print("✓ Presentation layer ready")
            
            if self.config.show_debug_info:
                print("\n⚠️  Debug mode enabled")
            
            print("\nReady to process weather requests!")
            return True
            
        except Exception as e:
            print(f"\n❌ Initialization failed: {e}")
            return False
    
    def run(self):
        """
        Run interactive weather dashboard session.
        
        Manages the main application loop and user interaction.
        """
        if not self.initialize():
            return
        
        self.running = True
        self.start_time = datetime.now()
        
        print("\n" + "=" * 70)
        print("INSTRUCTIONS")
        print("=" * 70)
        print("Enter city names, coordinates, or locations:")
        print("  • City: 'London' or 'San Francisco, CA'")
        print("  • With country: 'Paris, France' or 'Tokyo, Japan'")
        print("  • Coordinates: '51.5074,-0.1278'")
        print("\nCommands:")
        print("  • 'quit' or 'exit' - Exit the application")
        print("  • 'debug' - Toggle debug information")
        print("  • 'stats' - Show session statistics")
        print("=" * 70 + "\n")
        
        while self.running:
            try:
                # Get user input
                user_input = input("📍 Enter location (or command): ").strip()
                
                # Handle empty input
                if not user_input:
                    print("Please enter a location or command.\n")
                    continue
                
                # Handle commands
                if self._handle_command(user_input):
                    continue
                
                # Process weather request
                self._process_weather_request(user_input)
                
            except EOFError:
                # Handle Ctrl+D (EOF)
                print("\n")
                self._shutdown()
                break
                
            except Exception as e:
                print(f"\n❌ Unexpected error: {e}")
                print("Please try again.\n")
    
    def _process_weather_request(self, user_input):
        """
        Process a weather request through the complete workflow.
        
        Args:
            user_input: User's location input
        """
        # Track request
        self.request_count += 1
        request_start = datetime.now()
        
        print()  # Blank line for spacing
        
        # Show processing indicator for longer requests
        if self.config.show_debug_info:
            print(f"🔄 Processing request #{self.request_count}...")
        
        # Execute workflow through orchestrator
        result = self.orchestrator.get_weather_for_city(user_input)
        
        # Display result through presentation layer
        display_weather_result(result)
        
        # Show debug information if enabled
        if self.config.show_debug_info:
            self._display_debug_info(result, request_start)
        
        print()  # Blank line for spacing
    
    def _handle_command(self, user_input):
        """
        Handle special commands.
        
        Args:
            user_input: User's input string
            
        Returns:
            bool: True if input was a command, False otherwise
        """
        command = user_input.lower()
        
        # Quit commands
        if command in ['quit', 'exit', 'q']:
            self._shutdown()
            return True
        
        # Toggle debug mode
        if command == 'debug':
            self.config.show_debug_info = not self.config.show_debug_info
            status = "enabled" if self.config.show_debug_info else "disabled"
            print(f"\n🔧 Debug mode {status}\n")
            return True
        
        # Show statistics
        if command == 'stats':
            self._display_statistics()
            return True
        
        # Help command
        if command == 'help':
            self._display_help()
            return True
        
        return False
    
    def _display_debug_info(self, result, request_start):
        """Display detailed debug information about the request."""
        request_duration = (datetime.now() - request_start).total_seconds()
        
        print("\n🔧 DEBUG INFORMATION")
        print("-" * 70)
        print(f"Request duration: {request_duration:.3f}s")
        print(f"Workflow status: {result.status.value}")
        
        metadata = result.processing_metadata
        print(f"Processing steps: {len(metadata.get('steps', []))}")
        
        for step in metadata.get('steps', []):
            step_name = step.get('step', 'unknown')
            step_duration = step.get('duration', 0)
            step_status = step.get('status', 'unknown')
            print(f"  • {step_name}: {step_duration:.3f}s ({step_status})")
        
        if result.warnings:
            print(f"Warnings: {len(result.warnings)}")
        
        print("-" * 70)
    
    def _display_statistics(self):
        """Display session statistics."""
        if not self.start_time:
            print("\nNo statistics available yet.\n")
            return
        
        session_duration = (datetime.now() - self.start_time).total_seconds()
        
        print("\n" + "=" * 70)
        print("📊 SESSION STATISTICS")
        print("=" * 70)
        print(f"Session started:     {self.start_time.strftime('%Y-%m-%d %H:%M:%S')}")
        print(f"Session duration:    {session_duration:.1f}s")
        print(f"Requests processed:  {self.request_count}")
        
        if self.request_count > 0:
            avg_time = session_duration / self.request_count
            print(f"Average per request: {avg_time:.2f}s")
        
        print("=" * 70 + "\n")
    
    def _display_help(self):
        """Display help information."""
        print("\n" + "=" * 70)
        print("❓ HELP")
        print("=" * 70)
        print("\nLocation Formats:")
        print("  • City name: 'London', 'Paris', 'Tokyo'")
        print("  • City with state: 'San Francisco, CA'")
        print("  • City with country: 'London, UK', 'Paris, France'")
        print("  • Coordinates: 'latitude,longitude' (e.g., '51.5074,-0.1278')")
        print("\nCommands:")
        print("  • quit/exit - Exit the application")
        print("  • debug - Toggle detailed debug information")
        print("  • stats - Show session statistics")
        print("  • help - Show this help message")
        print("=" * 70 + "\n")
    
    def _shutdown(self):
        """Perform graceful shutdown."""
        self.running = False
        
        print("\n" + "=" * 70)
        print("👋 SHUTTING DOWN")
        print("=" * 70)
        
        if self.start_time:
            session_duration = (datetime.now() - self.start_time).total_seconds()
            print(f"Session duration: {session_duration:.1f}s")
            print(f"Requests processed: {self.request_count}")
        
        print("\nThank you for using Weather Dashboard!")
        print("=" * 70 + "\n")
    
    def _signal_handler(self, signum, frame):
        """Handle interrupt signals gracefully."""
        print("\n")  # New line after ^C
        self._shutdown()
        sys.exit(0)


def main():
    """
    Main entry point for weather dashboard application.
    
    Handles configuration loading and application lifecycle.
    """
    try:
        # Load configuration
        config = load_config()
        
        # Create and run application
        app = WeatherDashboardApp(config)
        app.run()
        
    except ValueError as e:
        # Configuration error
        print(f"Cannot start application: {e}")
        sys.exit(1)
        
    except KeyboardInterrupt:
        # User interrupted during startup
        print("\n\nStartup interrupted. Exiting.")
        sys.exit(0)
        
    except Exception as e:
        # Unexpected error during startup
        print(f"\n❌ Fatal error: {e}")
        sys.exit(1)


if __name__ == "__main__":
    main()

$ export OPENWEATHER_API_KEY='your_api_key_here'
$ python main.py

🌤️  Production Weather Dashboard
======================================================================
Initializing components...
✓ API client initialized
✓ Geocoding processor initialized
✓ Weather processor initialized
✓ Business logic coordinator initialized
✓ Presentation layer ready

Ready to process weather requests!

======================================================================
INSTRUCTIONS
======================================================================
Enter city names, coordinates, or locations:
  • City: 'London' or 'San Francisco, CA'
  • With country: 'Paris, France' or 'Tokyo, Japan'
  • Coordinates: '51.5074,-0.1278'

Commands:
  • 'quit' or 'exit' - Exit the application
  • 'debug' - Toggle debug information
  • 'stats' - Show session statistics
======================================================================

📍 Enter location (or command): London

======================================================================
🌤️  WEATHER FOR LONDON, ENGLAND, UNITED KINGDOM
======================================================================

🌡️  CURRENT CONDITIONS
   Temperature:     15.3°C
   Feels like:      13.8°C
   Description:     Light Rain
   Humidity:        72%
   Pressure:        1013 hPa
   Wind:            12.5 km/h from SW
   Visibility:      8.5 km

📊 DATA QUALITY
   Updated:         2025-10-07 14:23:45
   Timezone:        Europe/London
   Quality:         92% (Excellent)
======================================================================

📍 Enter location (or command): debug

🔧 Debug mode enabled

📍 Enter location (or command): Tokyo

🔄 Processing request #2...

======================================================================
🌤️  WEATHER FOR TOKYO, TOKYO, JAPAN
======================================================================

🌡️  CURRENT CONDITIONS
   Temperature:     18.2°C
   Description:     Clear Sky
   Humidity:        45%
   Pressure:        1015 hPa
   Wind:            8.3 km/h from E

📊 DATA QUALITY
   Updated:         2025-10-07 23:24:15
   Timezone:        Asia/Tokyo
   Quality:         95% (Excellent)
======================================================================

🔧 DEBUG INFORMATION
----------------------------------------------------------------------
Request duration: 1.234s
Workflow status: success
Processing steps: 4
  • input_validation: 0.001s (success)
  • geocoding_api: 0.456s (success)
  • location_processing: 0.012s (success)
  • weather_api: 0.623s (success)
  • weather_processing: 0.008s (success)
----------------------------------------------------------------------

📍 Enter location (or command): stats

======================================================================
📊 SESSION STATISTICS
======================================================================
Session started:     2025-10-07 14:23:30
Session duration:    125.3s
Requests processed:  2
Average per request: 62.65s
======================================================================

📍 Enter location (or command): quit

======================================================================
👋 SHUTTING DOWN
======================================================================
Session duration: 145.8s
Requests processed: 2

Thank you for using Weather Dashboard!
======================================================================

weather_dashboard/
│
├── main.py                      # Application coordinator
├── config.py                    # Configuration management
│
├── core/                        # Core business logic
│   ├── __init__.py
│   ├── weather_orchestrator.py  # Business logic layer
│   └── workflow_models.py       # Workflow result structures
│
├── api/                         # API client layer
│   ├── __init__.py
│   └── weather_api_client.py    # Resilient API client
│
├── processing/                  # Data processing layer
│   ├── __init__.py
│   ├── geocoding_processor.py   # Location processing
│   ├── weather_processor.py     # Weather processing
│   └── data_models.py           # Normalized data structures
│
├── presentation/                # Presentation layer
│   ├── __init__.py
│   └── display_weather.py       # Display formatting
│
├── validation/                  # Input validation
│   ├── __init__.py
│   └── input_validator.py       # Input validation
│
├── utils/                       # Utility modules (from Chapters 9-12)
│   ├── __init__.py
│   ├── error_handling.py        # Chapter 9 utilities
│   ├── json_processing.py       # Chapter 10 utilities
│   └── validation.py            # Chapter 12 utilities
│
├── tests/                       # Test suite
│   ├── __init__.py
│   ├── test_integration.py      # Integration tests
│   ├── test_api_client.py       # API client tests
│   ├── test_processors.py       # Processing tests
│   └── test_orchestrator.py     # Workflow tests
│
├── requirements.txt             # Python dependencies
├── README.md                    # Project documentation
└── .env.example                 # Environment variable template

"""
Unit tests for weather dashboard components.

Tests individual functions and classes in isolation.
Fast, focused tests that run in milliseconds.
"""
import pytest
from datetime import datetime

# Import components to test
from validation.input_validator import InputValidator
from utils.error_handling import categorize_error
from utils.validation import validate_structure, validate_range
from processing.data_models import Location, CurrentWeather, WeatherData


class TestInputValidator:
    """Unit tests for input validation."""
    
    def setup_method(self):
        """Initialize validator before each test."""
        self.validator = InputValidator()
    
    def test_valid_city_name(self):
        """Test validation of simple city name."""
        result = self.validator.validate_location_input("London")
        
        assert result.normalized_query == "London"
        assert result.confidence >= 0.6
    
    def test_city_with_state(self):
        """Test validation of city with state code."""
        result = self.validator.validate_location_input("San Francisco, CA")
        
        assert result.normalized_query == "San Francisco, CA"
        assert result.confidence >= 0.8
    
    def test_coordinates(self):
        """Test validation of coordinate input."""
        result = self.validator.validate_location_input("51.5074,-0.1278")
        
        assert result.normalized_query == "51.5074,-0.1278"
        assert result.confidence >= 0.95
    
    def test_empty_input(self):
        """Test that empty input raises validation error."""
        with pytest.raises(Exception) as exc_info:
            self.validator.validate_location_input("")
        
        assert "cannot be empty" in str(exc_info.value).lower()
    
    def test_input_too_short(self):
        """Test that single character input raises error."""
        with pytest.raises(Exception) as exc_info:
            self.validator.validate_location_input("a")
        
        assert "too short" in str(exc_info.value).lower()
    
    def test_input_too_long(self):
        """Test that excessively long input raises error."""
        long_input = "a" * 101
        
        with pytest.raises(Exception) as exc_info:
            self.validator.validate_location_input(long_input)
        
        assert "too long" in str(exc_info.value).lower()
    
    def test_whitespace_normalization(self):
        """Test that whitespace is properly trimmed."""
        result = self.validator.validate_location_input("  London  ")
        
        assert result.normalized_query == "London"


class TestErrorCategorization:
    """Unit tests for error categorization from Chapter 9."""
    
    def test_empty_input_categorized_as_user_input(self):
        """Test that empty input categorizes as user_input."""
        category = categorize_error(ValueError(), user_input="")
        
        assert category == 'user_input'
    
    def test_too_long_input_categorized_as_user_input(self):
        """Test that too-long input categorizes as user_input."""
        long_input = "a" * 101
        category = categorize_error(ValueError(), user_input=long_input)
        
        assert category == 'user_input'
    
    def test_network_timeout_categorized_as_transient(self):
        """Test that timeouts categorize as transient."""
        import requests
        error = requests.exceptions.Timeout()
        category = categorize_error(error)
        
        assert category == 'transient'
    
    def test_connection_error_categorized_as_transient(self):
        """Test that connection errors categorize as transient."""
        import requests
        error = requests.exceptions.ConnectionError()
        category = categorize_error(error)
        
        assert category == 'transient'
    
    def test_keyerror_categorized_as_not_found(self):
        """Test that KeyError (no results) categorizes as not_found."""
        error = KeyError('results')
        category = categorize_error(error)
        
        assert category == 'not_found'


class TestDataValidation:
    """Unit tests for validation utilities from Chapter 12."""
    
    def test_validate_structure_success(self):
        """Test structure validation with valid data."""
        data = {
            'main': {'temp': 15.3},
            'weather': [{'description': 'clear'}]
        }
        
        is_valid, error = validate_structure(data, ['main', 'weather'])
        
        assert is_valid is True
        assert error is None
    
    def test_validate_structure_missing_section(self):
        """Test structure validation detects missing sections."""
        data = {'main': {'temp': 15.3}}
        
        is_valid, error = validate_structure(data, ['main', 'weather'])
        
        assert is_valid is False
        assert 'weather' in error
    
    def test_validate_range_within_bounds(self):
        """Test range validation with valid value."""
        is_valid, error = validate_range(15.3, 'temperature', -100, 60)
        
        assert is_valid is True
        assert error is None
    
    def test_validate_range_below_minimum(self):
        """Test range validation detects values below minimum."""
        is_valid, error = validate_range(-150, 'temperature', -100, 60)
        
        assert is_valid is False
        assert 'below minimum' in error
    
    def test_validate_range_above_maximum(self):
        """Test range validation detects values above maximum."""
        is_valid, error = validate_range(100, 'temperature', -100, 60)
        
        assert is_valid is False
        assert 'above maximum' in error


class TestDataModels:
    """Unit tests for data model construction."""
    
    def test_location_creation(self):
        """Test creating valid Location object."""
        location = Location(
            name="London",
            country="United Kingdom",
            state="England",
            latitude=51.5074,
            longitude=-0.1278,
            confidence_score=0.95,
            raw_data={}
        )
        
        assert location.name == "London"
        assert location.latitude == 51.5074
        assert location.confidence_score == 0.95
    
    def test_weather_condition_creation(self):
        """Test creating valid CurrentWeather object."""
        weather = CurrentWeather(
            temperature=15.3,
            feels_like=13.8,
            humidity=72,
            pressure=1013.2,
            description="Light Rain",
            icon="10d"
        )
        
        assert weather.temperature == 15.3
        assert weather.description == "Light Rain"
    
    def test_weather_data_creation(self):
        """Test creating complete WeatherData object."""
        location = Location(
            name="London",
            country="UK",
            state=None,
            latitude=51.5074,
            longitude=-0.1278,
            confidence_score=0.95,
            raw_data={}
        )
        
        current = CurrentWeather(
            temperature=15.3,
            feels_like=13.8,
            humidity=72,
            pressure=1013.2,
            description="Clear",
            icon="01d"
        )
        
        weather_data = WeatherData(
            location=location,
            current=current,
            timestamp=datetime.now(),
            timezone="Europe/London",
            data_quality_score=0.92,
            validation_warnings=[],
            raw_data={}
        )
        
        assert weather_data.location.name == "London"
        assert weather_data.current.temperature == 15.3
        assert weather_data.data_quality_score == 0.92


# Run unit tests with: pytest tests/test_components.py -v

"""
Integration tests for weather dashboard.

Tests layer interactions and data flow through the system.
Uses mocking to avoid external API dependencies.
"""
import pytest
from unittest.mock import Mock, patch, MagicMock
from datetime import datetime

from api.weather_api_client import WeatherAPIClient, APIResult
from processing.geocoding_processor import GeocodingProcessor
from processing.weather_processor import WeatherProcessor
from core.weather_orchestrator import WeatherOrchestrator


class TestAPIClientIntegration:
    """Test API client with retry logic."""
    
    @patch('requests.get')
    def test_successful_request(self, mock_get):
        """Test successful API request."""
        # Mock successful response
        mock_response = Mock()
        mock_response.status_code = 200
        mock_response.json.return_value = {'results': [{'name': 'London'}]}
        mock_get.return_value = mock_response
        
        client = WeatherAPIClient()
        result = client.fetch_geocoding("London")
        
        assert result.success is True
        assert result.data is not None
        assert 'results' in result.data
    
    @patch('requests.get')
    def test_retry_on_timeout(self, mock_get):
        """Test that client retries on timeout."""
        import requests
        
        # First two calls timeout, third succeeds
        mock_response = Mock()
        mock_response.status_code = 200
        mock_response.json.return_value = {'results': []}
        
        mock_get.side_effect = [
            requests.exceptions.Timeout(),
            requests.exceptions.Timeout(),
            mock_response
        ]
        
        client = WeatherAPIClient()
        result = client.fetch_geocoding("London")
        
        # Should have tried 3 times
        assert mock_get.call_count == 3
        assert result.success is True
    
    @patch('requests.get')
    def test_no_retry_on_404(self, mock_get):
        """Test that client doesn't retry 404 errors."""
        import requests
        
        mock_response = Mock()
        mock_response.status_code = 404
        
        error = requests.exceptions.HTTPError()
        error.response = mock_response
        mock_get.side_effect = error
        
        client = WeatherAPIClient()
        result = client.fetch_geocoding("NonexistentCity")
        
        # Should only try once (no retry for 404)
        assert mock_get.call_count == 1
        assert result.success is False


class TestProcessorIntegration:
    """Test processor with API client results."""
    
    def test_geocoding_processor_with_valid_response(self):
        """Test geocoding processor with valid API response."""
        # Create mock API result
        api_response = APIResult(
            success=True,
            data=[{
                'name': 'London',
                'country': 'United Kingdom',
                'state': 'England',
                'lat': 51.5074,
                'lon': -0.1278
            }],
            error_context=None
        )
        
        processor = GeocodingProcessor()
        locations = processor.process_response(api_response, "London")
        
        assert len(locations) > 0
        assert locations[0].name == "London"
        assert locations[0].latitude == 51.5074
    
    def test_geocoding_processor_with_empty_results(self):
        """Test processor handles empty results gracefully."""
        api_response = APIResult(
            success=True,
            data=[],
            error_context=None
        )
        
        processor = GeocodingProcessor()
        
        with pytest.raises(Exception) as exc_info:
            processor.process_response(api_response, "Atlantis")
        
        assert "No locations found" in str(exc_info.value)
    
    def test_weather_processor_with_valid_response(self):
        """Test weather processor with valid API response."""
        from processing.data_models import Location
        
        location = Location(
            name="London",
            country="UK",
            state=None,
            latitude=51.5074,
            longitude=-0.1278,
            confidence_score=0.95,
            raw_data={}
        )
        
        api_response = APIResult(
            success=True,
            data={
                'main': {
                    'temp': 15.3,
                    'feels_like': 13.8,
                    'humidity': 72,
                    'pressure': 1013.2
                },
                'weather': [{
                    'description': 'light rain',
                    'icon': '10d'
                }],
                'dt': int(datetime.now().timestamp()),
                'timezone': 'Europe/London'
            },
            error_context=None
        )
        
        processor = WeatherProcessor()
        weather_data = processor.process_response(api_response, location)
        
        assert weather_data.location.name == "London"
        assert weather_data.current.temperature == 15.3
        assert weather_data.data_quality_score > 0


class TestOrchestratorIntegration:
    """Test complete workflow orchestration."""
    
    @patch('api.weather_api_client.WeatherAPIClient.fetch_geocoding')
    @patch('api.weather_api_client.WeatherAPIClient.fetch_weather')
    def test_successful_workflow(self, mock_weather, mock_geocoding):
        """Test complete successful workflow."""
        # Mock geocoding response
        mock_geocoding.return_value = APIResult(
            success=True,
            data=[{
                'name': 'London',
                'country': 'United Kingdom',
                'state': 'England',
                'lat': 51.5074,
                'lon': -0.1278
            }],
            error_context=None
        )
        
        # Mock weather response
        mock_weather.return_value = APIResult(
            success=True,
            data={
                'main': {
                    'temp': 15.3,
                    'feels_like': 13.8,
                    'humidity': 72,
                    'pressure': 1013.2
                },
                'weather': [{
                    'description': 'clear sky',
                    'icon': '01d'
                }],
                'dt': int(datetime.now().timestamp()),
                'timezone': 'Europe/London'
            },
            error_context=None
        )
        
        orchestrator = WeatherOrchestrator()
        result = orchestrator.get_weather_for_city("London")
        
        assert result.succeeded
        assert result.has_weather
        assert result.weather_data.location.name == "London"
    
    @patch('api.weather_api_client.WeatherAPIClient.fetch_geocoding')
    def test_workflow_with_geocoding_failure(self, mock_geocoding):
        """Test workflow when geocoding fails."""
        mock_geocoding.return_value = APIResult(
            success=False,
            data=None,
            error_context={'failure_type': 'not_found'}
        )
        
        orchestrator = WeatherOrchestrator()
        result = orchestrator.get_weather_for_city("Atlantis")
        
        assert not result.succeeded
        assert not result.has_weather
        assert result.error_message is not None


# Run integration tests with: pytest tests/test_integration.py -v

"""
End-to-end tests for weather dashboard.

Tests complete workflows with real API calls.
Slower tests that verify production behavior.
"""
import pytest
import os
import time
from core.weather_orchestrator import WeatherOrchestrator


# Skip E2E tests if no API key available
pytestmark = pytest.mark.skipif(
    not os.getenv('OPENWEATHER_API_KEY'),
    reason="OPENWEATHER_API_KEY not set"
)


class TestEndToEnd:
    """End-to-end tests with real APIs."""
    
    def setup_method(self):
        """Initialize orchestrator before each test."""
        api_key = os.getenv('OPENWEATHER_API_KEY')
        self.orchestrator = WeatherOrchestrator(api_key)
    
    def test_major_city_workflow(self):
        """Test complete workflow with major city."""
        result = self.orchestrator.get_weather_for_city("London")
        
        # Verify success
        assert result.succeeded
        assert result.has_weather
        
        # Verify location data
        assert result.weather_data.location.name
        assert -90 <= result.weather_data.location.latitude <= 90
        assert -180 <= result.weather_data.location.longitude <= 180
        
        # Verify weather data
        assert -100 <= result.weather_data.current.temperature <= 60
        assert 0 <= result.weather_data.current.humidity <= 100
        assert result.weather_data.current.description
        
        # Verify quality metadata
        assert 0 <= result.weather_data.data_quality_score <= 1
        assert result.weather_data.timestamp
    
    def test_city_with_country_workflow(self):
        """Test workflow with city and country specification."""
        result = self.orchestrator.get_weather_for_city("Paris, France")
        
        assert result.succeeded
        assert result.has_weather
        assert "Paris" in result.weather_data.location.name
    
    def test_nonexistent_city_workflow(self):
        """Test workflow with nonexistent city."""
        result = self.orchestrator.get_weather_for_city("Atlantis12345")
        
        # Should fail gracefully
        assert not result.succeeded
        assert not result.has_weather
        assert result.error_message is not None
        assert result.error_category is not None
    
    def test_empty_input_workflow(self):
        """Test workflow with empty input."""
        result = self.orchestrator.get_weather_for_city("")
        
        # Should fail at input validation
        assert not result.succeeded
        assert result.error_category == 'user_input'
    
    def test_multiple_requests_workflow(self):
        """Test that multiple requests work correctly."""
        cities = ["London", "Paris", "Tokyo"]
        results = []
        
        for city in cities:
            result = self.orchestrator.get_weather_for_city(city)
            results.append(result)
            
            # Small delay to avoid rate limiting
            time.sleep(1)
        
        # All should succeed
        assert all(r.succeeded for r in results)
        
        # Each should have different coordinates
        coords = [(r.weather_data.location.latitude, 
                  r.weather_data.location.longitude) for r in results]
        assert len(coords) == len(set(coords))  # All unique
    
    def test_performance_benchmark(self):
        """Test that requests complete in reasonable time."""
        start_time = time.time()
        
        result = self.orchestrator.get_weather_for_city("London")
        
        duration = time.time() - start_time
        
        # Should complete in under 10 seconds
        assert duration < 10.0
        assert result.succeeded


# Run E2E tests with: pytest tests/test_end_to_end.py -v -s