mcqpy 0.4.0

Umbrella CLI package for MCQPy

mcqpy

Generate and grade interactive multiple-choice quiz PDF documents. Rendered documents with

• LaTeX formatting - including for math/equations.
• Include figures from files or from links.
• Code snippets with highlighted code.
• Headers and footers.

Easily grade hundreds of quizzes with grades exported to .xlsx or .csv while obtaining question-level statistics.

mcqpy is now the umbrella CLI package. Python runtime APIs live in:

• mcqpy_core: question models, manifest, grading, and web bundle/token utilities
• mcqpy_pdf: PDF build/parse/reporting utilities
• mcqpy_shiny: Shiny app and embed tooling

Example

The simplest way to use mcqpy is through the command line interface (CLI). A project can be initialized like so

mcqpy init <PROJECT_NAME>

Which will create a directory <PROJECT_NAME> containing the following:

• config.yaml: Overall configuration of the project, including author, document name, header, footer and preface options.
• questions/: A directory where the project expects question .yaml files to be located.
• output/: Where the built documents will be put.
• submissions/: A directory where submitted quizzes should be put for grading.

For a quiz to be interesting it needs questions, the template structure of a question can be created using

mcqpy question init <QUESTION_PATH>

where <QUESTION_PATH> could be questions/q1.yaml. Once the desired number of questions have been written the quiz can be compiled using

mcqpy build 

Which produces a number of files in the output/ directory the important ones being

• <NAME>.pdf: The quiz document
• <NAME>_solution.pdf: A human readable solution key to all questions contained in the quiz.
• <NAME>_manifest.json: Quiz key used by mcqpy to grade quizzes.

The <NMAE>.pdf document can be distributed to quiz takers through any means and once returned and placed in the submissions/ directory be graded by the program. A number of test submissions can be created using

mcqpy test-autofill -n 50 

Which here generates 50 randomly filled quizzes. To grade run

mcqpy grade -a 

Which will produce the files <NAME>_grades.xlsx containing the grades of all submissions and analysis/<NAME>_analysis.pdf containing statistics about overall point distributions as well as question level statistics.

Installation

mcqpy requires Python, a small number of Python packages and a working LaTeX installation.

Installing mcqpy in a venv.

If you have a working Python installation we recommend installing mcqpy in a suitable virtual environment (venv) using pip

pip install git+https://github.com/au-mbg/mcqpy.git

Installing Python & mcqpy.

If you do not have a suitable Python version, uv can be recommended for installing and managing Python, see Installing uv. With uv installed you can create a venv with mcqpy using

uv venv
source .venv/bin/activate  # On Mac/Linux
uv pip install git+https://github.com/au-mbg/mcqpy.git

Install LaTeX

You will also need a working LaTeX installation, once mcqpy is installed you can check for that using

mcqpy check-latex

Which will output the versions of pdflatex and latexmk if they are installed, if not you should install an OS appropriate LaTeX distribution for example from one of these sources:

• macOS: MacTeX
• Windows: TeX Live or MiKTeX
• Linux: TeX Live (usually available through your package manager, e.g., sudo apt install texlive-full on Ubuntu/Debian)

Python imports

Use the owner packages directly in Python code:

from mcqpy_core.question import Question
from mcqpy_core.web import build_web_quiz_bundle
from mcqpy_pdf.grader import grade_pdf

Do not import runtime APIs from mcqpy; that package is reserved for the CLI surface.