Building QM2: A Modern, Dockerized CLI Quiz Engine with 330+ Tests

QM2 - Modern Python CLI Quiz Maker application main menu featuring ASCII art and interactive terminal UI on a green gradient background

The Mission

Most quiz applications are web-based, but I wanted something that lives where I spend most of my time: the terminal. I built QM2 — a robust, interactive quiz engine designed for developers and power users who value speed, efficiency, and a clean “brutalist” UI.

The Tech Stack

To make a CLI feel like a professional product, I relied on some of the best libraries in the Python ecosystem:

Rich: For the beautiful, colored interface and real-time feedback.
Questionary: To handle complex interactive prompts and menus.
Platformdirs: Ensuring data is stored correctly whether you are on Windows, macOS, or Linux.
Docker: For those who want to run the engine in a completely isolated environment.

QM2 - Modern Python CLI Quiz Maker application main menu featuring ASCII art and interactive terminal UI on a green gradient background

Engineered for Reliability

As a developer, I believe that if it’s not tested, it’s broken.

330 Individual Tests: Ensuring the core logic remains rock-solid as the project grows.
86% Coverage: Backed by a strict CI/CD pipeline.
OIDC Publishing: Secure, token-less deployment to PyPI via GitHub Actions.

QM2 - Modern Python CLI Quiz Maker application - passing 330 tests

Key Features

4 Question Types: Multiple Choice, True/False, Fill-in-the-blank, and Matching.
Flashcards Mode: Stress-free learning without the pressure of a timer.
Data Portability: Full support for bidirectional CSV ↔ JSON conversion. You can even import quizzes directly from a URL!
Category Management: Organize your learning into hierarchical structures (e.g., programming/python/basics).

QM2 - Modern Python CLI Quiz Maker application main menu featuring ASCII art and interactive terminal UI on a green gradient background

Installation & Quick Start

You can get up and running in seconds:

Terminal

UTF-8

bash

pip install qm2
qm2

Or via Docker to keep your system clean:

Terminal

UTF-8

bash

docker build -t qm2 .
docker run -it -v qm2_data:/root/.local/share/qm2 qm2

Deep Dive into Data

I designed the question format to be as human-readable as possible. Whether you prefer JSON for precision or CSV for bulk editing in Excel, QM2 handles both:

JSON

quiz-schema.json

UTF-8

json

[
    {
        "type": "multiple",
        "question": "What is the capital of France?",
        "correct": "Paris",
        "wrong_answers": ["Rome", "Berlin", "Madrid"]
    },
    {
        "type": "truefalse",
        "question": "Python is a programming language.",
        "correct": "True",
        "wrong_answers": ["False"]
    },
    {
        "type": "fillin",
        "question": "The capital of Japan is ______.",
        "correct": "Tokyo",
        "wrong_answers": []
    },
    {
        "type": "match",
        "question": "Match programming languages with their types",
        "pairs": {
            "left": ["Python", "JavaScript", "C++"],
            "right": ["Interpreted", "Web scripting", "Compiled"],
            "answers": { "a": "1", "b": "2", "c": "3" }
        }
    }
]

CSV

quiz-schema.csv

UTF-8

csv

type,question,correct,wrong_answers,left,right,answers
multiple,What is the capital of France?,Paris,"Rome,Berlin,Madrid",,,
truefalse,The Sun is a star.,True,False,,,
fillin,The capital of Japan is ______.,Tokyo,,,,
match,Match technologies,,,Python|HTML,Programming language|Markup language,"a:1,b:2"