trivia_app.py

"""
Trivia Q&A Application

A console-based trivia game that fetches questions from the Open Trivia Database API
and provides an interactive Q&A experience with comprehensive logging and error handling.

Design principles: Observability, Reliability, Resilience
"""

import requests
import logging
import html
import sys
from typing import Optional, Dict, List, Any
from dataclasses import dataclass
from enum import Enum


# ============================================================================
# Configuration & Constants
# ============================================================================

API_ENDPOINT = "https://opentdb.com/api.php?amount=10"
REQUEST_TIMEOUT = 10
MAX_RETRIES = 3
RETRY_DELAY = 1


# ============================================================================
# Logging Configuration
# ============================================================================

def setup_logging(level: int = logging.INFO) -> logging.Logger:
    """
    Configure logging for observability.
    
    Args:
        level: Logging level (DEBUG, INFO, WARNING, ERROR)
    
    Returns:
        Configured logger instance
    """
    logger = logging.getLogger("trivia_app")
    logger.setLevel(level)
    
    handler = logging.StreamHandler(sys.stdout)
    formatter = logging.Formatter(
        '%(asctime)s - %(name)s - %(levelname)s - %(message)s',
        datefmt='%Y-%m-%d %H:%M:%S'
    )
    handler.setFormatter(formatter)
    
    if not logger.handlers:
        logger.addHandler(handler)
    
    return logger


logger = setup_logging()


# ============================================================================
# Domain Models
# ============================================================================

class ResponseCode(Enum):
    """API response codes."""
    SUCCESS = 0
    NO_RESULTS = 1
    INVALID_PARAMETER = 2
    TOKEN_NOT_FOUND = 3
    TOKEN_EMPTY = 4


@dataclass
class TriviaQuestion:
    """Represents a single trivia question."""
    category: str
    difficulty: str
    question: str
    correct_answer: str
    incorrect_answers: List[str]
    
    def get_all_answers(self) -> List[str]:
        """
        Get all answers shuffled randomly.
        
        Returns:
            List of all answer options
        """
        import random
        answers = self.incorrect_answers.copy()
        answers.append(self.correct_answer)
        random.shuffle(answers)
        return answers
    
    def decode_html_entities(self) -> None:
        """Decode HTML entities in question and answers."""
        self.question = html.unescape(self.question)
        self.correct_answer = html.unescape(self.correct_answer)
        self.incorrect_answers = [html.unescape(ans) for ans in self.incorrect_answers]


@dataclass
class TriviaResponse:
    """Represents the API response."""
    response_code: int
    results: List[TriviaQuestion]
    
    @staticmethod
    def from_json(data: Dict[str, Any]) -> 'TriviaResponse':
        """
        Create TriviaResponse from JSON data.
        
        Args:
            data: JSON response from API
        
        Returns:
            TriviaResponse instance
        
        Raises:
            ValueError: If data format is invalid
        """
        try:
            response_code = data.get('response_code')
            
            if response_code != ResponseCode.SUCCESS.value:
                raise ValueError(f"API returned error code: {response_code}")
            
            results = []
            for item in data.get('results', []):
                question = TriviaQuestion(
                    category=item.get('category', 'Unknown'),
                    difficulty=item.get('difficulty', 'unknown'),
                    question=item.get('question', ''),
                    correct_answer=item.get('correct_answer', ''),
                    incorrect_answers=item.get('incorrect_answers', [])
                )
                question.decode_html_entities()
                results.append(question)
            
            return TriviaResponse(response_code=response_code, results=results)
        
        except (KeyError, TypeError) as e:
            logger.error(f"Failed to parse API response: {e}")
            raise ValueError(f"Invalid response format: {e}")


# ============================================================================
# API Client (Resilience & Reliability)
# ============================================================================

class TriviaAPIClient:
    """Handles communication with the Open Trivia Database API."""
    
    def __init__(self, endpoint: str = API_ENDPOINT, timeout: int = REQUEST_TIMEOUT):
        """
        Initialize the API client.
        
        Args:
            endpoint: API endpoint URL
            timeout: Request timeout in seconds
        """
        self.endpoint = endpoint
        self.timeout = timeout
    
    def fetch_questions(self) -> Optional[TriviaResponse]:
        """
        Fetch trivia questions from the API with retry logic.
        
        Returns:
            TriviaResponse if successful, None otherwise
        """
        import time
        
        for attempt in range(1, MAX_RETRIES + 1):
            try:
                logger.info(f"Fetching questions from API (attempt {attempt}/{MAX_RETRIES})")
                
                response = requests.get(
                    self.endpoint,
                    timeout=self.timeout
                )
                
                response.raise_for_status()
                logger.debug(f"API response status: {response.status_code}")
                
                data = response.json()
                trivia_response = TriviaResponse.from_json(data)
                
                logger.info(f"Successfully fetched {len(trivia_response.results)} questions")
                return trivia_response
            
            except requests.exceptions.Timeout:
                logger.warning(f"Request timeout on attempt {attempt}")
                if attempt < MAX_RETRIES:
                    time.sleep(RETRY_DELAY)
            
            except requests.exceptions.ConnectionError:
                logger.warning(f"Connection error on attempt {attempt}")
                if attempt < MAX_RETRIES:
                    time.sleep(RETRY_DELAY)
            
            except requests.exceptions.HTTPError as e:
                logger.error(f"HTTP error: {e}")
                return None
            
            except ValueError as e:
                logger.error(f"Response parsing error: {e}")
                return None
        
        logger.error(f"Failed to fetch questions after {MAX_RETRIES} attempts")
        return None


# ============================================================================
# Trivia Game (Accuracy & Agility)
# ============================================================================

class TriviaGame:
    """Manages the trivia game flow and scoring."""
    
    def __init__(self, questions: List[TriviaQuestion]):
        """
        Initialize the game.
        
        Args:
            questions: List of trivia questions
        """
        self.questions = questions
        self.current_question_index = 0
        self.score = 0
        self.answers_given = []
    
    def get_current_question(self) -> Optional[TriviaQuestion]:
        """Get the current question."""
        if self.current_question_index < len(self.questions):
            return self.questions[self.current_question_index]
        return None
    
    def submit_answer(self, selected_answer: str) -> bool:
        """
        Submit an answer and check if it's correct.
        
        Args:
            selected_answer: The answer selected by the user
        
        Returns:
            True if answer is correct, False otherwise
        """
        question = self.get_current_question()
        if question is None:
            return False
        
        is_correct = selected_answer == question.correct_answer
        
        self.answers_given.append({
            'question': question.question,
            'selected': selected_answer,
            'correct': question.correct_answer,
            'is_correct': is_correct
        })
        
        if is_correct:
            self.score += 1
            logger.debug(f"Correct answer. Score: {self.score}/{len(self.answers_given)}")
        else:
            logger.debug(f"Incorrect answer. Correct was: {question.correct_answer}")
        
        self.current_question_index += 1
        return is_correct
    
    def is_game_over(self) -> bool:
        """Check if all questions have been answered."""
        return self.current_question_index >= len(self.questions)
    
    def get_score_percentage(self) -> float:
        """Get the score as a percentage."""
        if len(self.answers_given) == 0:
            return 0.0
        return (self.score / len(self.answers_given)) * 100


# ============================================================================
# Console UI
# ============================================================================

class ConsoleUI:
    """Handles console-based user interface."""
    
    @staticmethod
    def clear_screen() -> None:
        """Clear the console screen."""
        import os
        os.system('cls' if os.name == 'nt' else 'clear')
    
    @staticmethod
    def print_header(text: str) -> None:
        """Print a formatted header."""
        print("\n" + "=" * 80)
        print(f" {text}")
        print("=" * 80)
    
    @staticmethod
    def print_question(question: TriviaQuestion, question_number: int, total: int) -> None:
        """
        Display a trivia question.
        
        Args:
            question: The question to display
            question_number: Current question number
            total: Total number of questions
        """
        print(f"\n[Question {question_number}/{total}]")
        print(f"Category: {question.category}")
        print(f"Difficulty: {question.difficulty.upper()}")
        print(f"\n{question.question}\n")
    
    @staticmethod
    def print_options(options: List[str]) -> None:
        """
        Display answer options.
        
        Args:
            options: List of answer options
        """
        for i, option in enumerate(options, 1):
            print(f"  {i}. {option}")
    
    @staticmethod
    def get_user_selection(num_options: int) -> int:
        """
        Get user's answer selection.
        
        Args:
            num_options: Number of available options
        
        Returns:
            The selected option number (1-indexed)
        """
        while True:
            try:
                selection = input(f"\nYour answer (1-{num_options}): ").strip()
                selection_int = int(selection)
                
                if 1 <= selection_int <= num_options:
                    return selection_int
                else:
                    print(f"Please enter a number between 1 and {num_options}")
            
            except ValueError:
                print("Invalid input. Please enter a number.")
    
    @staticmethod
    def print_answer_feedback(is_correct: bool, correct_answer: str) -> None:
        """
        Display feedback for the user's answer.
        
        Args:
            is_correct: Whether the answer was correct
            correct_answer: The correct answer
        """
        if is_correct:
            print("\n✓ CORRECT!")
        else:
            print(f"\n✗ INCORRECT. The correct answer was: {correct_answer}")
    
    @staticmethod
    def print_final_score(game: TriviaGame) -> None:
        """Display final game results."""
        ConsoleUI.print_header("GAME OVER - FINAL RESULTS")
        print(f"\nTotal Score: {game.score}/{len(game.questions)}")
        print(f"Percentage: {game.get_score_percentage():.1f}%")
        print("\n" + "-" * 80)
        print("Question Summary:\n")
        
        for i, answer_data in enumerate(game.answers_given, 1):
            status = "✓" if answer_data['is_correct'] else "✗"
            print(f"{i}. {status} {answer_data['question']}")
            print(f"   Your answer: {answer_data['selected']}")
            if not answer_data['is_correct']:
                print(f"   Correct answer: {answer_data['correct']}")
            print()


# ============================================================================
# Main Application
# ============================================================================

def main() -> None:
    """Main application entry point."""
    logger.info("Starting Trivia Q&A Application")
    
    ConsoleUI.clear_screen()
    ConsoleUI.print_header("TRIVIA Q&A - OPEN TRIVIA DATABASE")
    print("\nFetching trivia questions from the Open Trivia Database...")
    
    # Fetch questions from API
    client = TriviaAPIClient()
    trivia_response = client.fetch_questions()
    
    if trivia_response is None or len(trivia_response.results) == 0:
        print("\n✗ Failed to fetch trivia questions. Please check your connection and try again.")
        logger.error("Application terminated due to API fetch failure")
        return
    
    # Initialize and run game
    game = TriviaGame(trivia_response.results)
    
    try:
        while not game.is_game_over():
            question = game.get_current_question()
            question_number = game.current_question_index + 1
            
            ConsoleUI.print_question(
                question,
                question_number,
                len(game.questions)
            )
            
            options = question.get_all_answers()
            ConsoleUI.print_options(options)
            
            # Get user's answer
            selection_index = ConsoleUI.get_user_selection(len(options)) - 1
            selected_answer = options[selection_index]
            
            # Check answer and provide feedback
            is_correct = game.submit_answer(selected_answer)
            ConsoleUI.print_answer_feedback(is_correct, question.correct_answer)
            
            # Pause before next question
            if not game.is_game_over():
                input("\nPress Enter to continue to the next question...")
        
        # Display final results
        ConsoleUI.print_final_score(game)
        logger.info(f"Game completed. Final score: {game.score}/{len(game.questions)}")
    
    except KeyboardInterrupt:
        print("\n\n✗ Game interrupted by user.")
        logger.info("Game interrupted by user")
    
    except Exception as e:
        logger.error(f"Unexpected error during game: {e}", exc_info=True)
        print(f"\n✗ An unexpected error occurred: {e}")


if __name__ == "__main__":
    main()