quizy 0.1.1

A simple, elegant Python framework for creating and running interactive quizzes

Quizy 🎯

A simple, elegant Python framework for creating and running interactive quizzes

Quizy makes it incredibly easy to create educational quizzes, assessments, and interactive learning experiences in Python. Whether you're a teacher, student, or developer, Quizy provides a clean API for building engaging quiz applications.

✨ Features

• 🚀 Simple API - Create quizzes in just a few lines of code
• 📝 Interactive CLI - Built-in command-line interface for running quizzes
• 🎨 Customizable - Add explanations, customize questions, and build complex quizzes
• 🔌 Extensible - Easy to integrate into your own applications
• 📦 Zero Dependencies - Pure Python, no external packages required
• ✅ Type-Safe - Clean, well-documented code with proper error handling

🚀 Quick Start

Installation

pip install quizy

Or install from source:

git clone https://github.com/yourusername/quizy.git
cd quizy
pip install -e .

Your First Quiz in 30 Seconds

import quizy as q

# Use a built-in quiz
quiz_101 = q.quiz_101
quiz_101.start()

That's it! You'll get an interactive quiz experience right in your terminal.

📖 Usage Guide

Using Built-in Quizzes

Quizy comes with sample quizzes to get you started:

import quizy as q

# Python Basics Quiz
quiz_101 = q.quiz_101
quiz_101.start()

# Data Structures Quiz
quiz_102 = q.quiz_102
quiz_102.start()

Creating Custom Quizzes

Build your own quizzes with the Quiz and Question classes:

from quizy import Quiz, Question

# Create a new quiz
geography_quiz = Quiz("World Geography Challenge")

# Add questions with multiple choice options
geography_quiz.add_question(Question(
    text="What is the capital of France?",
    options=["London", "Berlin", "Paris", "Madrid"],
    correct_answer="Paris",
    explanation="Paris has been the capital of France since the 12th century"
))

geography_quiz.add_question(Question(
    text="Which is the largest ocean?",
    options=["Atlantic", "Indian", "Arctic", "Pacific"],
    correct_answer="Pacific",
    explanation="The Pacific Ocean covers about 63 million square miles"
))

# Start the quiz
geography_quiz.start()

Advanced Example: Programming Quiz

from quizy import Quiz, Question

# Create a coding quiz
coding_quiz = Quiz("Python Programming Quiz")

# Add technical questions
coding_quiz.add_question(Question(
    text="What is the time complexity of list.append() in Python?",
    options=["O(1)", "O(log n)", "O(n)", "O(n²)"],
    correct_answer="O(1)",
    explanation="List append is amortized O(1) due to dynamic array implementation"
))

coding_quiz.add_question(Question(
    text="Which keyword is used to create a generator in Python?",
    options=["return", "yield", "generate", "async"],
    correct_answer="yield",
    explanation="The yield keyword creates a generator that can pause and resume execution"
))

coding_quiz.add_question(Question(
    text="What does the __init__ method do in Python classes?",
    options=[
        "Deletes an object",
        "Initializes a new instance",
        "Imports a module",
        "Defines a static method"
    ],
    correct_answer="Initializes a new instance",
    explanation="__init__ is the constructor method called when creating new class instances"
))

# Run the quiz
coding_quiz.start()

Working with Quiz Data Programmatically

from quizy import Quiz, Question

# Create a quiz
my_quiz = Quiz("Math Quiz")
my_quiz.add_question(Question(
    text="What is 12 × 15?",
    options=["150", "180", "200", "175"],
    correct_answer="180"
))

# Inspect quiz contents
print(f"Title: {my_quiz.title}")
print(f"Questions: {len(my_quiz.get_questions())}")

# Iterate through questions
for i, question in enumerate(my_quiz.get_questions(), 1):
    print(f"{i}. {question.text}")
    print(f"   Answer: {question.correct_answer}")

CLI Usage

After installation, run quizzes directly from your terminal:

quizy

This launches an interactive menu where you can select from available quizzes.

📚 API Reference

Question

Creates a single quiz question with multiple choice answers.

Question(text, options, correct_answer, explanation=None)

Parameters:

• text (str): The question text
• options (list): List of possible answers (strings)
• correct_answer (str): The correct answer (must be in options)
• explanation (str, optional): Explanation shown after answering

Methods:

• check_answer(user_answer) - Returns True if the answer is correct

Example:

q = Question(
    text="What is 2 + 2?",
    options=["3", "4", "5", "6"],
    correct_answer="4",
    explanation="Basic arithmetic: 2 plus 2 equals 4"
)

Quiz

Creates a quiz containing multiple questions.

Quiz(title, questions=None)

Parameters:

• title (str): Quiz title displayed to users
• questions (list, optional): Initial list of Question objects

Methods:

• add_question(question) - Add a Question to the quiz
• start() - Launch interactive quiz session
• get_questions() - Return list of all questions
• clear() - Remove all questions and reset score

Attributes:

• title - Quiz title
• questions - List of Question objects
• score - Current score (after running quiz)
• total - Total number of questions

Example:

quiz = Quiz("Science Quiz")
quiz.add_question(Question(...))
quiz.add_question(Question(...))
quiz.start()  # Runs interactively

print(f"Final Score: {quiz.score}/{quiz.total}")

🏗️ Project Structure

quizy/
├── pyproject.toml       # Package configuration
├── README.md            # This file
├── LICENSE              # MIT License
└── quizy/
    ├── __init__.py      # Package exports
    ├── core.py          # Quiz and Question classes
    ├── quiz_101.py      # Sample: Python Basics
    ├── quiz_102.py      # Sample: Data Structures
    └── main.py          # CLI entry point

🛠️ Development

Local Development Setup

# Clone the repository
git clone https://github.com/yourusername/quizy.git
cd quizy

# Install in editable mode
pip install -e .

# Test your changes
python -c "import quizy; print(quizy.__version__)"

Building the Package

# Install build tools
pip install build

# Build distribution packages
python -m build

# Output: dist/quizy-0.1.0.tar.gz and dist/quizy-0.1.0-py3-none-any.whl

Publishing to PyPI

# Install twine
pip install twine

# Upload to PyPI (requires PyPI account)
twine upload dist/*

# Or upload to TestPyPI first
twine upload --repository testpypi dist/*

🎓 Use Cases

• Education: Create interactive learning materials for students
• Training: Build corporate training quizzes and assessments
• Interviews: Develop technical screening questions
• Self-Study: Create personal study aids for exam preparation
• Gamification: Add quiz elements to your applications

🤝 Contributing

Contributions are welcome! Here are some ways you can help:

• 🐛 Report bugs and issues
• 💡 Suggest new features
• 📝 Improve documentation
• 🔧 Submit pull requests

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built with ❤️ for educators, students, and developers who believe in the power of interactive learning.

---

Happy Quizzing! 🎉

For questions, issues, or suggestions, please visit GitHub Issues.