ezquiz 0.6.0

Add your description here

ezquiz

A flexible quiz framework with FastAPI backend and interactive web UI.

Features

• Multiple Quiz Support: Host multiple quizzes under different paths from a single server
• Custom Logic: Create custom logic for question generation
• Quick Start: Support for simple text input and fill-in-the-blank questions
• Visual Feedback: Text diff visualization for incorrect answers
• Flexible: Get quizzed only on what is relevant to you

Installation

pip install ezquiz

Quick Start

from ezquiz import APIGame, Q

# Create a game
game = APIGame()

# Add a simple quiz using from_dict
questions = Q.from_dict({
    "What is the capital of France?": "Paris",
    "What is the largest planet in the Solar System?": "Jupiter",
})

game.add_quiz("trivia", "General Trivia", {"general": questions})

# Start the server
game.start(host="localhost", port=8000)

Visit http://localhost:8000/ to see the quiz lobby.

For a more advanced example of using custom functions to generate dynamic questions, see examples/spanish_conj.py which demonstrates Spanish verb conjugation with random subject-verb combinations and computed answers.

Creating Questions

Method 1: Using from_dict (Simple)

The easiest way to create questions is using from_dict, which maps question text to answers:

# Simple text questions
spanish_questions = Q.from_dict({
    "How many eyes does a spider have?": "8",
    "What is the chemical formula for water?": "H2O",
})

# Fill-in-the-blank questions (type="fill")
# Use [...] to indicate where the input field should appear
fill_questions = Q.from_dict(
    {
        "The capital of France is [...].": "Paris",
        "The largest planet in our solar system is [...].": "Jupiter",
        "Water freezes at [...] degrees Celsius.": "0",
    },
    question_type="fill"
)

# Case-sensitive matching (default is case-insensitive)
code_questions = Q.from_dict(
    {"Enter the secret code:": "ABC123"},
    case_sensitive=True
)

from_dict Parameters

• dct: Dictionary mapping question strings to answers
• question_type: "simple" (default) or "fill" for inline input
• case_sensitive: False (default) for case-insensitive matching, True for exact case matching

Method 2: Custom Q with Functions (Flexible)

For more control, create a Q instance directly with custom functions. This is useful for:

• Randomized questions
• Dynamic content
• Custom validation logic
• Adding context to questions

from random import randint
from ezquiz import Q

# Create a quiz that generates random addition problems
def get_seed():
    """Generate random numbers for the question."""
    return (randint(1, 20), randint(1, 20))

def ask(seed):
    """Create the question dictionary from the seed."""
    a, b = seed
    return {
        "text": f"What is {a} + {b}?",
        "type": "simple",
        "context": "",  # Optional context shown above question
        "hints": [],    # Optional hints
    }

def correct(seed):
    """Return the correct answer from the seed."""
    a, b = seed
    return str(a + b)

# Create the Q instance
math_q = Q[tuple[int, int]](
    get_seed=get_seed,
    ask=ask,
    correct=correct,
)

Creating Multi-Quiz Servers

Host multiple quizzes from a single server:

from ezquiz import APIGame, Q

# Create different question sets
geo_qs = Q.from_dict({
    "Capital of France?": "Paris",
    "Capital of Japan?": "Tokyo",
})

spanish_qs = Q.from_dict({
    "Hello in Spanish?": "Hola",
    "Thank you in Spanish?": "Gracias",
})

# Create game and add quizzes
game = APIGame()

game.add_quiz("geography", "World Geography", {"capitals": geo_qs})
game.add_quiz("spanish", "Spanish 101", {"vocabulary": spanish_qs})

# Start server
game.start(host="localhost", port=8000)

Access:

• Lobby: http://localhost:8000/
• Math: http://localhost:8000/math/
• Geography: http://localhost:8000/geography/
• Spanish: http://localhost:8000/spanish/

Question Types

Simple Questions

Text input field below the question:

Q.from_dict({"What is 2+2?": "4"}, question_type="simple")

Fill-in-the-Blank

Inline input field within the text:

Q.from_dict(
    {"The capital of [...] is Paris.": "France"},
    question_type="fill"
)

Answer Validation

Case-Insensitive (Default)

Q.from_dict({"What color is the sky?": "blue"})
# Accepts: "blue", "Blue", "BLUE", etc.

Case-Sensitive

Q.from_dict(
    {"Enter the code:": "AbC123"},
    case_sensitive=True
)
# Only accepts: "AbC123"

Roadmap

Planned features and enhancements:

Question Types & Media

• Multiple Choice: Support for multiple choice questions with customizable options
• Images: Display images alongside or within questions
• Audio: Play audio clips for listening comprehension or music theory quizzes

Analytics & Statistics

• Quiz Performance: Track correct/incorrect answers per quiz and category
• Progress Tracking: View learning progress over time
• Session History: Review past quiz sessions and results

Question Selection & Weighting

• Weighted Probability: Configure question selection probability based on performance
• Spaced Repetition: Prioritize questions based on difficulty and recall success
• Category Weighting: Adjust frequency of questions from different categories

Settings & Customization

• Explanation Toggle: Option to show/hide explanations after answers
• Timed Quizzes: Add time limits per question or per quiz
• Retry Options: Allow multiple attempts on incorrect answers
• Quiz Length: Configure number of questions per session