Chapter 9: Production Error Handling

Traceback (most recent call last):
  File "/home/user/weather_dashboard.py", line 156, in get_weather_for_city
    latitude, longitude, location_name = self.find_location(city_name)
  File "/home/user/weather_dashboard.py", line 34, in find_location
    location = data["results"][0]
KeyError: 'results'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/user/weather_dashboard.py", line 203, in 
    dashboard.run()
  File "/home/user/weather_dashboard.py", line 178, in run
    weather_data = self.get_weather_for_city(city_name)
  File "/home/user/weather_dashboard.py", line 162, in get_weather_for_city
    raise ConnectionError(f"Failed to get weather data: {str(e)}")
ConnectionError: Failed to get weather data: 'results'

1. User enters city name → Can be empty, whitespace, typos, too long
2. Call Geocoding API → Network timeout, DNS failure, API down
3. Parse response → Missing 'results' key, empty results array
4. Extract coordinates → KeyError if structure differs
5. Call Weather API → Network timeout, rate limit (429), server error (500)
6. Parse weather data → Missing expected fields
7. Display to user → Success! (if nothing failed)

Traceback (most recent call last):
  File "weather_dashboard.py", line 34, in find_location
    location = data["results"][0]
KeyError: 'results'

We couldn't find weather data for "Lndon".
Please check the spelling or try a nearby city.
Examples: London, Dublin, Tokyo

Traceback (most recent call last):
  File "weather_dashboard.py", line 34, in find_location
    location = data["results"][0]
KeyError: 'results'

We couldn't find weather data for "Lndon".
Please check the spelling or try a nearby city.
Examples: London, Dublin, Manchester

requests.exceptions.ReadTimeout: HTTPSConnectionPool(host='api.open-meteo.com', 
port=443): Read timed out. (read timeout=5)

We're having trouble connecting to the weather service.
This is usually temporary - please try again in a moment.
If the problem continues, check your internet connection.

ValueError: City name cannot be empty

Please enter a city name to get weather information.
Type the name of any city or town.
Examples: London, Paris, Tokyo

Transaction declined - Code 51

Your card was declined. 
Please check the card number and expiration date are correct.
If the information is correct, contact your bank to authorize the transaction.

MESSAGE_TEMPLATES = {
    "user_input": {
        "empty": (
            "Please enter a city name to get weather information.",
            "Type the name of any city or town.",
            "Examples: London, Paris, Tokyo"
        ),
        "too_long": (
            "That city name is too long (maximum 100 characters).",
            "Please enter a shorter name.",
            "Examples: London, San Francisco, Mexico City"
        ),
        "invalid_chars": (
            "City names can only contain letters, spaces, hyphens, and apostrophes.",
            "Please check your input and try again.",
            "Examples: London, Saint-Denis, O'Fallon"
        )
    },
    "transient": {
        "timeout": (
            "We're having trouble connecting to the weather service.",
            "This is usually temporary - please try again in a moment.",
            "If the problem continues, check your internet connection."
        ),
        "rate_limit": (
            "We've made too many requests to the weather service.",
            "Please wait {retry_seconds} seconds before trying again.",
            "This helps us stay within service limits."
        ),
        "server_error": (
            "The weather service is currently experiencing issues.",
            "This is temporary - please try again in a few minutes.",
            "If the problem continues, check the service status page."
        )
    },
    "not_found": {
        "city": (
            "We couldn't find weather data for \"{city_name}\".",
            "Please check the spelling or try a nearby city.",
            "Examples: {suggestions}"
        )
    },
    "unknown": {
        "general": (
            "Something unexpected happened while getting weather data.",
            "Please try again. If the problem continues, contact support.",
            "Error details have been logged for investigation."
        )
    }
}

def compose_error_message(category, error_type, **context):
    """Compose a three-part error message from templates."""
    template = MESSAGE_TEMPLATES[category][error_type]
    
    # Format each part with context variables
    what_happened = template[0].format(**context)
    what_to_do = template[1].format(**context)
    examples = template[2].format(**context)
    
    return f"{what_happened}\n{what_to_do}\n{examples}"

# WRONG: Check network first
try:
    response = requests.get(f"https://api.example.com/search?q={city_name}")
    data = response.json()
    location = data["results"][0]  # KeyError if city_name was empty!
except KeyError:
    return "not_found"  # WRONG! This is actually a user_input error

# RIGHT: Check input first
if not city_name or not city_name.strip():
    return "user_input", "empty"

try:
    response = requests.get(f"https://api.example.com/search?q={city_name}")
    data = response.json()
    location = data["results"][0]
except KeyError:
    return "not_found", "city"  # NOW this is accurate

import requests
from requests.exceptions import Timeout, ConnectionError, HTTPError

def categorize_error(exception, response=None):
    """
    Categorize any exception into one of four types.
    
    Returns: (category, error_type, context)
    """
    # User input errors (checked before network calls)
    if isinstance(exception, ValueError):
        if "empty" in str(exception).lower():
            return ("user_input", "empty", {})
        elif "too long" in str(exception).lower():
            return ("user_input", "too_long", {})
        else:
            return ("user_input", "invalid_chars", {})
    
    # Transient errors that should be retried
    if isinstance(exception, Timeout):
        return ("transient", "timeout", {})
    
    if isinstance(exception, ConnectionError):
        return ("transient", "connection", {})
    
    if isinstance(exception, HTTPError):
        status_code = exception.response.status_code
        
        # Rate limiting
        if status_code == 429:
            retry_after = exception.response.headers.get('Retry-After', '60')
            return ("transient", "rate_limit", {"retry_seconds": retry_after})
        
        # Server errors (temporary)
        if status_code in [500, 502, 503, 504]:
            return ("transient", "server_error", {})
        
        # Not found
        if status_code == 404:
            return ("not_found", "city", {})
    
    # API returned empty results (city not found)
    if isinstance(exception, KeyError) and exception.args[0] == 'results':
        return ("not_found", "city", {})
    
    # Everything else is unknown
    return ("unknown", "general", {})

def validate_city_name(city_name):
    """
    Validate city name before making API calls.
    Raises ValueError with descriptive message if invalid.
    """
    # Check for empty input
    if not city_name or not city_name.strip():
        raise ValueError("City name cannot be empty")
    
    # Check length
    if len(city_name) > 100:
        raise ValueError("City name too long (maximum 100 characters)")
    
    # Check for valid characters (letters, spaces, hyphens, apostrophes)
    import re
    if not re.match(r"^[a-zA-Z\s\-']+$", city_name):
        raise ValueError("City name contains invalid characters")
    
    return city_name.strip()

def find_location(city_name):
    """Find location with validation."""
    # Validate FIRST, before network call
    try:
        validated_name = validate_city_name(city_name)
    except ValueError as e:
        # Categorize as user_input and return early
        category, error_type, context = categorize_error(e)
        message = compose_error_message(category, error_type, city_name=city_name)
        return None, message
    
    # NOW make the network request
    try:
        response = requests.get(f"https://api.example.com/search?q={validated_name}")
        response.raise_for_status()
        data = response.json()
        return data["results"][0], None
    except Exception as e:
        category, error_type, context = categorize_error(e, response)
        message = compose_error_message(category, error_type, city_name=city_name)
        return None, message

import time

def calculate_backoff_delay(attempt, base_delay=1.0):
    """Calculate exponential backoff delay for retry attempt."""
    return base_delay * (2 ** attempt)

# Usage
for attempt in range(4):
    delay = calculate_backoff_delay(attempt)
    print(f"Attempt {attempt + 1}: wait {delay}s before retry")

# Output:
# Attempt 1: wait 1.0s before retry
# Attempt 2: wait 2.0s before retry
# Attempt 3: wait 4.0s before retry
# Attempt 4: wait 8.0s before retry

12:00:00 - API goes down, 1000 users all fail simultaneously
12:00:01 - ALL 1000 users retry at exactly the same time (thundering herd!)
12:00:03 - ALL 1000 users retry again at exactly the same time
12:00:07 - ALL 1000 users retry again at exactly the same time

12:00:00 - API goes down, 1000 users all fail simultaneously
12:00:01 - Users retry spread across 1.0-1.5 seconds (distributed load)
12:00:03 - Users retry spread across 2.0-3.0 seconds (distributed load)
12:00:07 - Users retry spread across 4.0-6.0 seconds (distributed load)

import time
import random

def calculate_backoff_with_jitter(attempt, base_delay=1.0):
    """Calculate exponential backoff with jitter."""
    exponential_delay = base_delay * (2 ** attempt)
    jitter = random.uniform(0, base_delay * 0.5)
    return exponential_delay + jitter

# Usage - notice the random variation
for attempt in range(4):
    delay = calculate_backoff_with_jitter(attempt)
    print(f"Attempt {attempt + 1}: wait {delay:.2f}s before retry")

# Output (random variation each time):
# Attempt 1: wait 1.23s before retry
# Attempt 2: wait 2.41s before retry
# Attempt 3: wait 4.17s before retry
# Attempt 4: wait 8.38s before retry

import time
import random
import requests
import logging

def retry_with_backoff(func, *args, max_attempts=3, base_delay=1.0, **kwargs):
    """
    Retry function with exponential backoff and jitter.
    Only retries transient failures.
    """
    attempt = 0
    
    while attempt < max_attempts:
        try:
            result = func(*args, **kwargs)
            return result, None
            
        except Exception as e:
            # Categorize the error
            category, error_type, context = categorize_error(e)
            
            # Only retry transient errors
            if category != "transient":
                # Not retryable - return error immediately
                message = compose_error_message(category, error_type, **context)
                return None, message
            
            attempt += 1
            
            # Reached max attempts?
            if attempt >= max_attempts:
                message = compose_error_message(category, error_type, 
                                              attempts=attempt, **context)
                return None, message
            
            # Calculate delay with exponential backoff + jitter
            exponential_delay = base_delay * (2 ** (attempt - 1))
            jitter = random.uniform(0, base_delay * 0.5)
            delay = exponential_delay + jitter
            
            # Log for developers
            logging.warning(
                f"Attempt {attempt} failed: {error_type}. "
                f"Retrying in {delay:.1f}s..."
            )
            
            # Wait before retry
            time.sleep(delay)
    
    # Should never reach here, but handle it anyway
    return None, "Maximum retry attempts exceeded"

Enter city name: Tokyo

Looking up coordinates for 'Tokyo'...
Connection issue. Retrying in 1.3 seconds...
Found: Tokyo, Tokyo, Japan

Fetching weather data...
Temperature: 18°C
Conditions: Partly cloudy

Enter city name: Lndon

Looking up coordinates for 'Lndon'...

We couldn't find weather data for "Lndon".
Please check the spelling or try a nearby city.
Examples: London, Dublin, Manchester

def handle_rate_limit(response):
    """Handle 429 rate limit with Retry-After header."""
    if response.status_code == 429:
        retry_after = response.headers.get('Retry-After')
        
        if retry_after:
            # Retry-After is in seconds
            wait_seconds = int(retry_after)
            logging.info(f"Rate limited. Waiting {wait_seconds}s as instructed.")
            time.sleep(wait_seconds)
            return True  # Should retry
        else:
            # No Retry-After header - fall back to exponential backoff
            return True  # Should retry with standard backoff
    
    return False  # Not a rate limit

import logging
from datetime import datetime

# Configure logging at application startup
logging.basicConfig(
    level=logging.INFO,
    format='[%(levelname)s] %(asctime)s | %(message)s',
    datefmt='%Y-%m-%d %H:%M:%S',
    handlers=[
        # Log to file for developers
        logging.FileHandler('weather_dashboard.log'),
        # Also show in console during development
        logging.StreamHandler()
    ]
)

logger = logging.getLogger(__name__)

def log_error(category, error_type, exception, context=None):
    """Log technical details for developers."""
    log_entry = {
        "timestamp": datetime.now().isoformat(),
        "category": category,
        "error_type": error_type,
        "exception_type": type(exception).__name__,
        "exception_message": str(exception),
        "context": context or {}
    }
    
    if category == "user_input":
        logger.info(f"User input rejected: {log_entry}")
    elif category == "transient":
        logger.warning(f"Transient failure: {log_entry}")
    elif category == "not_found":
        logger.info(f"Resource not found: {log_entry}")
    else:  # unknown
        logger.error(f"Unknown error: {log_entry}", exc_info=True)

# Usage
try:
    result = find_location("Lndon")
except KeyError as e:
    category, error_type, context = categorize_error(e)
    
    # Log for developers
    log_error(category, error_type, e, {"user_input": "Lndon"})
    
    # Show message to users
    user_message = compose_error_message(category, error_type, 
                                        city_name="Lndon")
    print(user_message)

def get_weather_with_logging(city_name):
    """Get weather with dual-audience error handling."""
    try:
        # Validate input first
        validated_name = validate_city_name(city_name)
        
        # Make API call
        location_data = find_location(validated_name)
        weather_data = get_weather(location_data)
        
        return weather_data, None
        
    except Exception as e:
        # Categorize the error
        category, error_type, context = categorize_error(e)
        context["user_input"] = city_name
        
        # Log technical details for developers
        log_entry = {
            "category": category,
            "error_type": error_type,
            "exception": str(e),
            "context": context
        }
        
        if category == "user_input":
            logger.info(f"Input validation failed: {log_entry}")
        elif category == "transient":
            logger.warning(f"Transient error occurred: {log_entry}")
        elif category == "not_found":
            logger.info(f"Resource not found: {log_entry}")
        else:
            logger.error(f"Unknown error: {log_entry}", exc_info=True)
        
        # Compose friendly message for users
        user_message = compose_error_message(category, error_type, **context)
        
        return None, user_message

# Usage
weather, error = get_weather_with_logging("Lndon")

if error:
    # User sees this:
    print(error)
    # "We couldn't find weather data for 'Lndon'."
    # "Please check the spelling or try a nearby city."
    # "Examples: London, Dublin, Manchester"
else:
    print(f"Temperature: {weather['temp']}°C")

# Developer sees this in logs:
# [INFO] 2024-03-15 14:23:15 | Resource not found: {
#   'category': 'not_found', 
#   'error_type': 'city',
#   'exception': "KeyError: 'results'",
#   'context': {'user_input': 'Lndon'}
# }

# Install pytest
pip install pytest pytest-mock --break-system-packages

# Create test file
touch test_weather_dashboard.py

# Run tests
pytest test_weather_dashboard.py -v

import pytest
from unittest.mock import Mock, patch
from requests.exceptions import Timeout, ConnectionError, HTTPError
from weather_dashboard import (
    categorize_error,
    compose_error_message,
    validate_city_name,
    retry_with_backoff,
    find_location,
    get_weather
)

# ==================== CATEGORIZATION TESTS ====================

def test_categorize_empty_user_input():
    """Empty city name should categorize as user_input."""
    exception = ValueError("City name cannot be empty")
    category, error_type, context = categorize_error(exception)
    assert category == "user_input"
    assert error_type == "empty"

def test_categorize_whitespace_input():
    """Whitespace-only input should categorize as user_input."""
    exception = ValueError("City name cannot be empty")
    category, error_type, context = categorize_error(exception)
    assert category == "user_input"

def test_categorize_too_long_input():
    """City name over 100 chars should categorize as user_input."""
    exception = ValueError("City name too long (maximum 100 characters)")
    category, error_type, context = categorize_error(exception)
    assert category == "user_input"
    assert error_type == "too_long"

def test_categorize_invalid_chars():
    """Invalid characters should categorize as user_input."""
    exception = ValueError("City name contains invalid characters")
    category, error_type, context = categorize_error(exception)
    assert category == "user_input"
    assert error_type == "invalid_chars"

def test_categorize_timeout():
    """Network timeout should categorize as transient."""
    exception = Timeout("Request timed out")
    category, error_type, context = categorize_error(exception)
    assert category == "transient"
    assert error_type == "timeout"

def test_categorize_connection_error():
    """Connection errors should categorize as transient."""
    exception = ConnectionError("Failed to establish connection")
    category, error_type, context = categorize_error(exception)
    assert category == "transient"
    assert error_type == "connection"

def test_categorize_rate_limit():
    """429 rate limit should categorize as transient with retry context."""
    response = type('Response', (), {
        'status_code': 429,
        'headers': {'Retry-After': '60'}
    })()
    exception = HTTPError(response=response)
    
    category, error_type, context = categorize_error(exception, response)
    
    assert category == "transient"
    assert error_type == "rate_limit"
    assert context["retry_seconds"] == "60"

def test_categorize_server_error_500():
    """500 server error should categorize as transient."""
    response = type('Response', (), {'status_code': 500})()
    exception = HTTPError(response=response)
    category, error_type, context = categorize_error(exception, response)
    assert category == "transient"
    assert error_type == "server_error"

def test_categorize_server_error_503():
    """503 service unavailable should categorize as transient."""
    response = type('Response', (), {'status_code': 503})()
    exception = HTTPError(response=response)
    category, error_type, context = categorize_error(exception, response)
    assert category == "transient"

def test_categorize_key_error():
    """KeyError for 'results' should categorize as not_found."""
    exception = KeyError('results')
    category, error_type, context = categorize_error(exception)
    assert category == "not_found"
    assert error_type == "city"

def test_categorize_404():
    """404 response should categorize as not_found."""
    response = type('Response', (), {'status_code': 404})()
    exception = HTTPError(response=response)
    category, error_type, context = categorize_error(exception, response)
    assert category == "not_found"

def test_categorize_unknown_error():
    """Unexpected exceptions should categorize as unknown."""
    exception = RuntimeError("Something weird happened")
    category, error_type, context = categorize_error(exception)
    assert category == "unknown"
    assert error_type == "general"

# ==================== MESSAGE COMPOSITION TESTS ====================

def test_message_has_three_parts_empty_input():
    """Empty input message should have three parts."""
    message = compose_error_message("user_input", "empty")
    lines = message.split('\n')
    assert len(lines) == 3

def test_message_has_three_parts_not_found():
    """Not found message should have three parts."""
    message = compose_error_message("not_found", "city",
                                   city_name="Lndon",
                                   suggestions="London, Dublin")
    lines = message.split('\n')
    assert len(lines) == 3
    assert "Lndon" in lines[0]

def test_message_quotes_user_input():
    """Messages should quote back user input."""
    message = compose_error_message("not_found", "city",
                                   city_name="Lndon",
                                   suggestions="London, Dublin")
    assert "Lndon" in message

def test_message_includes_retry_time():
    """Rate limit messages should include retry time."""
    message = compose_error_message("transient", "rate_limit",
                                   retry_seconds="60")
    assert "60" in message
    assert "seconds" in message.lower()

def test_message_transient_no_technical_jargon():
    """Transient error messages should avoid technical terms."""
    message = compose_error_message("transient", "timeout")
    
    # Should NOT contain technical terms
    assert "KeyError" not in message
    assert "Traceback" not in message
    assert "Exception" not in message
    
    # SHOULD contain friendly language
    assert any(word in message.lower() for word in 
               ["trouble", "try", "moment", "temporary"])

def test_message_unknown_gives_actionable_guidance():
    """Unknown error messages should still be actionable."""
    message = compose_error_message("unknown", "general")
    assert "try again" in message.lower()
    assert len(message.split('\n')) == 3

# ==================== RETRY LOGIC TESTS ====================

@patch('weather_dashboard.requests.get')
def test_retry_succeeds_on_second_attempt(mock_get, mocker):
    """Should retry transient failures and succeed eventually."""
    # Mock first call fails, second succeeds
    mock_get.side_effect = [
        Timeout("First attempt fails"),
        type('Response', (), {
            'status_code': 200,
            'json': lambda: {"results": [{"latitude": 51.5, "longitude": -0.1}]}
        })()
    ]
    
    mocker.patch('time.sleep')
    
    def test_func():
        response = mock_get()
        response.raise_for_status()
        return response.json()
    
    result, error = retry_with_backoff(test_func, max_attempts=3)
    
    assert error is None
    assert result is not None
    assert mock_get.call_count == 2

@patch('weather_dashboard.requests.get')
def test_retry_respects_max_attempts(mock_get, mocker):
    """Should stop after max_attempts failures."""
    mock_get.side_effect = Timeout("Always fails")
    mocker.patch('time.sleep')
    
    def test_func():
        response = mock_get()
        return response.json()
    
    result, error = retry_with_backoff(test_func, max_attempts=3)
    
    assert result is None
    assert error is not None
    assert mock_get.call_count == 3

@patch('weather_dashboard.requests.get')
def test_no_retry_for_user_input_error(mock_get, mocker):
    """Should not retry user_input category errors."""
    mocker.patch('time.sleep')
    
    def test_func():
        raise ValueError("City name cannot be empty")
    
    result, error = retry_with_backoff(test_func, max_attempts=3)
    
    assert result is None
    assert "city name" in error.lower()

@patch('weather_dashboard.requests.get')
def test_retry_uses_exponential_backoff(mock_get, mocker):
    """Should wait with exponential backoff between retries."""
    mock_get.side_effect = [
        Timeout("Fail"),
        Timeout("Fail again"),
        type('Response', (), {'json': lambda: {"success": True}})()
    ]
    
    sleep_spy = mocker.patch('time.sleep')
    
    def test_func():
        response = mock_get()
        return response.json()
    
    result, error = retry_with_backoff(test_func, max_attempts=3, base_delay=1.0)
    
    sleep_calls = [call[0][0] for call in sleep_spy.call_args_list]
    assert len(sleep_calls) == 2
    assert sleep_calls[0] < 2.0
    assert sleep_calls[1] >= 2.0

# ==================== INTEGRATION TESTS ====================

@patch('weather_dashboard.requests.get')
def test_end_to_end_city_not_found(mock_get):
    """Complete flow for city not found."""
    mock_get.return_value.json.return_value = {
        "results": []
    }
    mock_get.return_value.status_code = 200
    mock_get.return_value.raise_for_status = Mock()
    
    result, error = find_location("Lndon")
    
    assert result is None
    assert "Lndon" in error
    assert "couldn't find" in error.lower()

def test_categorization_drives_message_selection():
    """Verify categorization determines which message template is used."""
    test_cases = [
        (ValueError("empty"), "user_input", "empty"),
        (Timeout("timeout"), "transient", "timeout"),
        (KeyError("results"), "not_found", "city"),
        (RuntimeError("unknown"), "unknown", "general")
    ]
    
    for exception, expected_category, expected_type in test_cases:
        category, error_type, context = categorize_error(exception)
        assert category == expected_category
        assert error_type == expected_type
        
        message = compose_error_message(category, error_type, **context)
        assert len(message.split('\n')) == 3

import pytest
from requests.exceptions import Timeout, ConnectionError, HTTPError
from weather_dashboard import categorize_error

def test_categorize_empty_user_input():
    """Empty city name should categorize as user_input."""
    exception = ValueError("City name cannot be empty")
    category, error_type, context = categorize_error(exception)
    
    assert category == "user_input"
    assert error_type == "empty"

def test_categorize_timeout():
    """Network timeout should categorize as transient."""
    exception = Timeout("Request timed out")
    category, error_type, context = categorize_error(exception)
    
    assert category == "transient"
    assert error_type == "timeout"

def test_categorize_404():
    """404 response should categorize as not_found."""
    # Create mock HTTPError with 404 status
    response = type('Response', (), {'status_code': 404})()
    exception = HTTPError(response=response)
    
    category, error_type, context = categorize_error(exception, response)
    
    assert category == "not_found"
    assert error_type == "city"

def test_categorize_rate_limit():
    """429 response should categorize as transient with retry context."""
    response = type('Response', (), {
        'status_code': 429,
        'headers': {'Retry-After': '60'}
    })()
    exception = HTTPError(response=response)
    
    category, error_type, context = categorize_error(exception, response)
    
    assert category == "transient"
    assert error_type == "rate_limit"
    assert context["retry_seconds"] == "60"

def test_categorize_unknown_error():
    """Unexpected exceptions should categorize as unknown."""
    exception = RuntimeError("Something weird happened")
    category, error_type, context = categorize_error(exception)
    
    assert category == "unknown"
    assert error_type == "general"

from weather_dashboard import compose_error_message

def test_message_has_three_parts():
    """Every message should have what/how/examples structure."""
    message = compose_error_message("not_found", "city", 
                                   city_name="Lndon",
                                   suggestions="London, Dublin, Manchester")
    
    lines = message.split('\n')
    assert len(lines) == 3  # Three-part pattern
    
    # Part 1: What happened
    assert "Lndon" in lines[0]  # Quotes user input
    assert "couldn't find" in lines[0].lower()
    
    # Part 2: What to do
    assert "check" in lines[1].lower() or "try" in lines[1].lower()
    
    # Part 3: Examples
    assert "example" in lines[2].lower() or ":" in lines[2]

def test_message_quotes_user_input():
    """Messages should quote back user input."""
    message = compose_error_message("not_found", "city",
                                   city_name="Lndon",
                                   suggestions="London, Dublin")
    
    assert "Lndon" in message  # User sees exactly what they typed

def test_message_no_technical_jargon():
    """User messages should avoid technical terms."""
    message = compose_error_message("transient", "timeout")
    
    # Should NOT contain technical terms
    assert "KeyError" not in message
    assert "Traceback" not in message
    assert "Exception" not in message
    assert ".py" not in message
    
    # SHOULD contain friendly language
    assert any(word in message.lower() for word in 
               ["trouble", "try again", "moment", "temporary"])

import pytest
from unittest.mock import Mock, patch
from weather_dashboard import retry_with_backoff

def test_retry_succeeds_on_second_attempt(mocker):
    """Should retry transient failures and succeed eventually."""
    # Mock function that fails once then succeeds
    mock_func = Mock(side_effects=[
        Timeout("First attempt fails"),
        {"temp": 18, "conditions": "Cloudy"}  # Second attempt succeeds
    ])
    
    # Mock time.sleep so test runs instantly
    mocker.patch('time.sleep')
    
    result, error = retry_with_backoff(mock_func, max_attempts=3)
    
    assert error is None
    assert result["temp"] == 18
    assert mock_func.call_count == 2  # Failed once, succeeded once

def test_retry_respects_max_attempts(mocker):
    """Should stop after max_attempts failures."""
    # Mock function that always fails
    mock_func = Mock(side_effect=Timeout("Always fails"))
    mocker.patch('time.sleep')
    
    result, error = retry_with_backoff(mock_func, max_attempts=3)
    
    assert result is None
    assert error is not None
    assert mock_func.call_count == 3  # Tried 3 times then gave up

def test_no_retry_for_user_input_errors(mocker):
    """Should not retry user_input category errors."""
    # Mock function that raises user input error
    mock_func = Mock(side_effect=ValueError("City name cannot be empty"))
    mocker.patch('time.sleep')
    
    result, error = retry_with_backoff(mock_func, max_attempts=3)
    
    assert result is None
    assert "city name" in error.lower()
    assert mock_func.call_count == 1  # No retry - failed immediately

def test_retry_uses_exponential_backoff(mocker):
    """Should wait with exponential backoff between retries."""
    mock_func = Mock(side_effect=[
        Timeout("Fail"),
        Timeout("Fail again"),
        {"success": True}
    ])
    
    # Spy on time.sleep to verify backoff
    sleep_spy = mocker.patch('time.sleep')
    
    result, error = retry_with_backoff(mock_func, max_attempts=3, base_delay=1.0)
    
    # Verify sleep was called with increasing delays
    sleep_calls = [call[0][0] for call in sleep_spy.call_args_list]
    assert len(sleep_calls) == 2  # Two retries = two sleeps
    assert sleep_calls[0] < 2.0  # First retry ~1s + jitter
    assert sleep_calls[1] >= 2.0  # Second retry ~2s + jitter

def test_end_to_end_city_not_found(mocker):
    """Complete flow for city not found."""
    # Mock API to return empty results
    mock_response = {
        "status": "OK",
        "results": []  # Empty results = city not found
    }
    mocker.patch('requests.get').return_value.json.return_value = mock_response
    
    # Call the complete function
    from weather_dashboard import get_weather_for_city
    result, error = get_weather_for_city("Lndon")
    
    # Verify results
    assert result is None
    assert "Lndon" in error  # Quotes user input
    assert "couldn't find" in error.lower()
    assert any(city in error for city in ["London", "Dublin", "Manchester"])

def test_end_to_end_network_timeout_with_retry(mocker):
    """Complete flow for timeout that succeeds on retry."""
    mock_get = mocker.patch('requests.get')
    mock_get.side_effect = [
        Timeout("First attempt times out"),
        type('Response', (), {
            'status_code': 200,
            'json': lambda: {"results": [{"lat": 51.5, "lon": -0.1}]}
        })()
    ]
    mocker.patch('time.sleep')  # Skip delays
    
    from weather_dashboard import get_weather_for_city
    result, error = get_weather_for_city("London")
    
    assert error is None  # Succeeded after retry
    assert result is not None
    assert mock_get.call_count == 2  # Failed once, succeeded once

def test_categorization_drives_message_selection():
    """Verify categorization determines which message template is used."""
    test_cases = [
        (ValueError("empty"), "user_input", "empty"),
        (Timeout("timeout"), "transient", "timeout"),
        (KeyError("results"), "not_found", "city"),
        (RuntimeError("unknown"), "unknown", "general")
    ]
    
    for exception, expected_category, expected_type in test_cases:
        category, error_type, context = categorize_error(exception)
        assert category == expected_category
        assert error_type == expected_type
        
        # Verify correct message template is selected
        message = compose_error_message(category, error_type, **context)
        assert len(message.split('\n')) == 3  # Three-part pattern

pytest test_weather_dashboard.py -v

# Expected output:
test_categorize_empty_user_input PASSED                       [  5%]
test_categorize_timeout PASSED                                [ 10%]
test_categorize_404 PASSED                                    [ 15%]
test_categorize_rate_limit PASSED                             [ 20%]
test_categorize_unknown_error PASSED                          [ 25%]
test_message_has_three_parts PASSED                           [ 30%]
test_message_quotes_user_input PASSED                         [ 35%]
test_message_no_technical_jargon PASSED                       [ 40%]
test_retry_succeeds_on_second_attempt PASSED                  [ 45%]
test_retry_respects_max_attempts PASSED                       [ 50%]
test_no_retry_for_user_input_errors PASSED                    [ 55%]
test_retry_uses_exponential_backoff PASSED                    [ 60%]
test_end_to_end_city_not_found PASSED                         [ 65%]
test_end_to_end_network_timeout_with_retry PASSED             [ 70%]
test_categorization_drives_message_selection PASSED           [ 75%]

==================== 15 passed in 0.23s ====================

import requests
import time
import random
import logging
import re
from requests.exceptions import Timeout, ConnectionError, HTTPError
from datetime import datetime

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='[%(levelname)s] %(asctime)s | %(message)s',
    datefmt='%Y-%m-%d %H:%M:%S',
    handlers=[
        logging.FileHandler('weather_dashboard.log'),
        logging.StreamHandler()
    ]
)
logger = logging.getLogger(__name__)

# Message templates for all error types
MESSAGE_TEMPLATES = {
    "user_input": {
        "empty": (
            "Please enter a city name to get weather information.",
            "Type the name of any city or town.",
            "Examples: London, Paris, Tokyo"
        ),
        "too_long": (
            "That city name is too long (maximum 100 characters).",
            "Please enter a shorter name.",
            "Examples: London, San Francisco, Mexico City"
        ),
        "invalid_chars": (
            "City names can only contain letters, spaces, hyphens, and apostrophes.",
            "Please check your input and try again.",
            "Examples: London, Saint-Denis, O'Fallon"
        )
    },
    "transient": {
        "timeout": (
            "We're having trouble connecting to the weather service.",
            "This is usually temporary - please try again in a moment.",
            "If the problem continues, check your internet connection."
        ),
        "connection": (
            "We're having trouble connecting to the weather service.",
            "This is usually temporary - please try again in a moment.",
            "If the problem continues, check your internet connection."
        ),
        "rate_limit": (
            "We've made too many requests to the weather service.",
            "Please wait {retry_seconds} seconds before trying again.",
            "This helps us stay within service limits."
        ),
        "server_error": (
            "The weather service is currently experiencing issues.",
            "This is temporary - please try again in a few minutes.",
            "If the problem continues, check the service status page."
        )
    },
    "not_found": {
        "city": (
            "We couldn't find weather data for \"{city_name}\".",
            "Please check the spelling or try a nearby city.",
            "Examples: {suggestions}"
        )
    },
    "unknown": {
        "general": (
            "Something unexpected happened while getting weather data.",
            "Please try again. If the problem continues, contact support.",
            "Error details have been logged for investigation."
        )
    }
}

def categorize_error(exception, response=None):
    """Categorize any exception into one of four types."""
    # User input errors (checked before network calls)
    if isinstance(exception, ValueError):
        if "empty" in str(exception).lower():
            return ("user_input", "empty", {})
        elif "too long" in str(exception).lower():
            return ("user_input", "too_long", {})
        else:
            return ("user_input", "invalid_chars", {})
    
    # Transient errors that should be retried
    if isinstance(exception, Timeout):
        return ("transient", "timeout", {})
    
    if isinstance(exception, ConnectionError):
        return ("transient", "connection", {})
    
    if isinstance(exception, HTTPError):
        status_code = exception.response.status_code
        
        if status_code == 429:
            retry_after = exception.response.headers.get('Retry-After', '60')
            return ("transient", "rate_limit", {"retry_seconds": retry_after})
        
        if status_code in [500, 502, 503, 504]:
            return ("transient", "server_error", {})
        
        if status_code == 404:
            return ("not_found", "city", {})
    
    # API returned empty results (city not found)
    if isinstance(exception, KeyError) and exception.args[0] == 'results':
        return ("not_found", "city", {})
    
    # Everything else is unknown
    return ("unknown", "general", {})

def compose_error_message(category, error_type, **context):
    """Compose a three-part error message from templates."""
    template = MESSAGE_TEMPLATES[category][error_type]
    
    # Add default suggestions if missing
    if category == "not_found" and "suggestions" not in context:
        context["suggestions"] = "London, Paris, Tokyo"
    
    # Format each part with context variables
    what_happened = template[0].format(**context)
    what_to_do = template[1].format(**context)
    examples = template[2].format(**context)
    
    return f"{what_happened}\n{what_to_do}\n{examples}"

def log_error(category, error_type, exception, context=None):
    """Log technical details for developers."""
    log_entry = {
        "timestamp": datetime.now().isoformat(),
        "category": category,
        "error_type": error_type,
        "exception_type": type(exception).__name__,
        "exception_message": str(exception),
        "context": context or {}
    }
    
    if category == "user_input":
        logger.info(f"User input rejected: {log_entry}")
    elif category == "transient":
        logger.warning(f"Transient failure: {log_entry}")
    elif category == "not_found":
        logger.info(f"Resource not found: {log_entry}")
    else:  # unknown
        logger.error(f"Unknown error: {log_entry}", exc_info=True)

def validate_city_name(city_name):
    """Validate city name before making API calls."""
    if not city_name or not city_name.strip():
        raise ValueError("City name cannot be empty")
    
    if len(city_name) > 100:
        raise ValueError("City name too long (maximum 100 characters)")
    
    if not re.match(r"^[a-zA-Z\s\-']+$", city_name):
        raise ValueError("City name contains invalid characters")
    
    return city_name.strip()

def calculate_backoff_with_jitter(attempt, base_delay=1.0):
    """Calculate exponential backoff with jitter."""
    exponential_delay = base_delay * (2 ** attempt)
    jitter = random.uniform(0, base_delay * 0.5)
    return exponential_delay + jitter

def retry_with_backoff(func, *args, max_attempts=3, base_delay=1.0, **kwargs):
    """Retry function with exponential backoff and jitter."""
    attempt = 0
    
    while attempt < max_attempts:
        try:
            result = func(*args, **kwargs)
            return result, None
            
        except Exception as e:
            category, error_type, context = categorize_error(e)
            
            # Only retry transient errors
            if category != "transient":
                log_error(category, error_type, e, context)
                message = compose_error_message(category, error_type, **context)
                return None, message
            
            attempt += 1
            
            if attempt >= max_attempts:
                log_error(category, error_type, e, context)
                message = compose_error_message(category, error_type, 
                                              attempts=attempt, **context)
                return None, message
            
            delay = calculate_backoff_with_jitter(attempt - 1, base_delay)
            
            logger.warning(
                f"Attempt {attempt} failed: {error_type}. "
                f"Retrying in {delay:.1f}s..."
            )
            
            time.sleep(delay)
    
    return None, "Maximum retry attempts exceeded"

def find_location(city_name):
    """Find location coordinates for a city with error handling."""
    try:
        validated_name = validate_city_name(city_name)
    except ValueError as e:
        category, error_type, context = categorize_error(e)
        log_error(category, error_type, e, {"user_input": city_name})
        message = compose_error_message(category, error_type, city_name=city_name)
        return None, message
    
    def make_location_request():
        response = requests.get(
            "https://geocoding-api.open-meteo.com/v1/search",
            params={"name": validated_name, "count": 1},
            timeout=5
        )
        response.raise_for_status()
        data = response.json()
        
        if not data.get("results"):
            raise KeyError("results")
        
        location = data["results"][0]
        return {
            "lat": location["latitude"],
            "lon": location["longitude"],
            "name": location["name"]
        }
    
    result, error = retry_with_backoff(make_location_request)
    
    if error:
        # Add city name to error message if not already there
        if "{city_name}" in error:
            error = error.replace("{city_name}", city_name)
        return None, error
    
    return result, None

def get_weather(location):
    """Get weather data for location coordinates with error handling."""
    def make_weather_request():
        response = requests.get(
            "https://api.open-meteo.com/v1/forecast",
            params={
                "latitude": location["lat"],
                "longitude": location["lon"],
                "current_weather": True
            },
            timeout=5
        )
        response.raise_for_status()
        data = response.json()
        
        current = data["current_weather"]
        return {
            "temperature": current["temperature"],
            "windspeed": current["windspeed"],
            "conditions": "Clear" if current["weathercode"] == 0 else "Cloudy"
        }
    
    result, error = retry_with_backoff(make_weather_request)
    return result, error

class WeatherDashboard:
    """Production weather dashboard with complete error handling."""
    
    def get_weather_for_city(self, city_name):
        """Get weather for a city with complete error handling."""
        print(f"\nLooking up coordinates for '{city_name}'...")
        location, error = find_location(city_name)
        
        if error:
            return None, error
        
        print(f"Found: {location['name']}")
        print(f"\nFetching weather data...")
        
        weather, error = get_weather(location)
        
        if error:
            return None, error
        
        return weather, None
    
    def run(self):
        """Run the interactive dashboard."""
        print("=" * 50)
        print("Weather Dashboard (Production)")
        print("=" * 50)
        
        while True:
            city_name = input("\nEnter city name (or 'quit' to exit): ").strip()
            
            if city_name.lower() in ['quit', 'exit', 'q']:
                print("Goodbye!")
                break
            
            weather, error = self.get_weather_for_city(city_name)
            
            if error:
                print(f"\n{error}")
            else:
                print(f"\n{'=' * 50}")
                print(f"Weather for {city_name}")
                print(f"{'=' * 50}")
                print(f"Temperature: {weather['temperature']}°C")
                print(f"Wind Speed: {weather['windspeed']} km/h")
                print(f"Conditions: {weather['conditions']}")
                print(f"{'=' * 50}")

if __name__ == "__main__":
    dashboard = WeatherDashboard()
    dashboard.run()