QuizGenerator 0.13.0

Generate randomized quiz questions for Canvas LMS and PDF exams

QuizGenerator

Generate randomized quiz questions for Canvas LMS and PDF exams with support for multiple question types, automatic variation generation, and QR code-based answer keys.

Features

• Multiple Output Formats: Generate PDFs (LaTeX or Typst) and Canvas LMS quizzes
• Automatic Variations: Create unique versions for each student
• Extensible: Plugin system for custom question types
• Built-in Question Library: Memory management, process scheduling, calculus, linear algebra, and more
• QR Code Answer Keys: Regenerate exact exam versions from QR codes
• Canvas Integration: Direct upload to Canvas with variation support

Installation

pip install QuizGenerator

Reproducible installs (recommended)

If you want a fully pinned environment for a semester, use the lockfile:

uv sync --locked

We keep dependency ranges in pyproject.toml for flexibility and rely on uv.lock to pin exact versions when you need reproducible builds.

System Requirements

• Python 3.12+
• Typst (default PDF renderer)
• Optional: LaTeX distribution with latexmk (if using --latex)
• Recommended: Pandoc (for markdown conversion)
• Optional (LaTeX + QR codes): Inkscape for SVG conversion

Optional Dependencies

# For QR code grading support
pip install "QuizGenerator[grading]"

# For CST463 machine learning questions
pip install "QuizGenerator[cst463]"

Quick Start

Need a 2‑minute setup? See documentation/quickstart.md.

1. Create a quiz configuration (YAML)

# my_quiz.yaml
name: "Midterm Exam"

questions:
  10:  # 10-point questions
    "Process Scheduling":
      class: FIFOScheduling

  5:   # 5-point questions
    "Memory Paging":
      class: PagingQuestion

    "Vector Math":
      class: VectorAddition

2. Generate PDFs

quizgen --yaml my_quiz.yaml --num_pdfs 3

PDFs will be created in the out/ directory.

3. Upload to Canvas

# Set up Canvas credentials in ~/.env first:
# CANVAS_API_URL=https://canvas.instructure.com
# CANVAS_API_KEY=your_api_key_here

quizgen \
  --yaml my_quiz.yaml \
  --num_canvas 5 \
  --course_id 12345

Creating Custom Questions

QuizGenerator supports two approaches for adding custom question types:

Option 1: Entry Points (Recommended for Distribution)

Create a pip-installable package:

# pyproject.toml
[project.entry-points."quizgenerator.questions"]
my_question = "my_package.questions:MyCustomQuestion"

After pip install, your questions are automatically available!

Option 2: Direct Import (Quick & Easy)

Add to your quiz YAML:

custom_modules:
  - my_questions  # Import my_questions.py

questions:
  10:
    "My Question":
      class: MyCustomQuestion

See documentation/custom_questions.md for complete guide.

Question Authoring Pattern (New)

All questions follow the same three‑method flow:

class MyQuestion(Question):
    @classmethod
    def _build_context(cls, *, rng_seed=None, **kwargs):
        context = super()._build_context(rng_seed=rng_seed, **kwargs)
        rng = context.rng
        context["value"] = rng.randint(1, 10)
        return context

    @classmethod
    def _build_body(cls, context):
        body = ca.Section()
        body.add_element(ca.Paragraph([f"Value: {context['value']}"]))
        body.add_element(ca.AnswerTypes.Int(context["value"], label="Value"))
        return body

    @classmethod
    def _build_explanation(cls, context):
        explanation = ca.Section()
        explanation.add_element(ca.Paragraph([f"Answer: {context['value']}"]))
        return explanation

Notes:

• Always use context.rng (or context["rng"]) for deterministic randomness.
• Avoid refresh(); it is no longer part of the API.

Built-in Question Types

Operating Systems (CST334)

• FIFOScheduling, SJFScheduling, RoundRobinScheduling
• PagingQuestion, TLBQuestion
• SemaphoreQuestion, MutexQuestion

Machine Learning / Math (CST463)

• VectorAddition, VectorDotProduct, VectorMagnitude
• MatrixAddition, MatrixMultiplication, MatrixTranspose
• DerivativeBasic, DerivativeChain
• GradientDescentStep

General

• FromText - Custom text questions
• FromGenerator - Programmatically generated questions (requires --allow_generator or QUIZGEN_ALLOW_GENERATOR=1)

Documentation

• Getting Started Guide
• Custom Questions Guide
• YAML Configuration Reference

Canvas Setup

1. Create a ~/.env file with your Canvas credentials:

# For testing/development
CANVAS_API_URL=https://canvas.test.instructure.com
CANVAS_API_KEY=your_test_api_key

# For production
CANVAS_API_URL_prod=https://canvas.instructure.com
CANVAS_API_KEY_prod=your_prod_api_key

2. Use --prod flag for production Canvas instance:

quizgen --prod --num_canvas 5 --course_id 12345

Advanced Features

Typst Support

Typst is the default for faster compilation. Use --latex to force LaTeX:

quizgen --latex --num_pdfs 3

Experimental: --typst_measurement uses Typst to measure question height for tighter layout. It can change pagination and ordering, so use with care on finalized exams.

Deterministic Generation

Use seeds for reproducible quizzes:

quizgen --seed 42 --num_pdfs 3

QR Code Regeneration

Each generated exam includes a QR code that stores:

• Question types and parameters
• Random seed
• Version information

Use the grading tools to scan QR codes and regenerate exact exam versions.

Security Considerations

FromGenerator Warning

The FromGenerator question type executes arbitrary Python code from your YAML configuration files. This is a powerful feature for creating dynamic questions, but it carries security risks:

• Only use FromGenerator with YAML files you completely trust
• Never run --allow_generator on YAML files from untrusted sources
• Be cautious when sharing question banks that contain generator code

FromGenerator is disabled by default. To enable it, use one of:

quizgen --allow_generator --yaml my_quiz.yaml
# or
QUIZGEN_ALLOW_GENERATOR=1 quizgen --yaml my_quiz.yaml

If you need dynamic question generation with untrusted inputs, consider writing a proper Question subclass instead, which provides better control and validation.

Project Structure

QuizGenerator/
├── QuizGenerator/           # Main package
│   ├── question.py         # Question base classes and registry
│   ├── quiz.py            # Quiz generation logic
│   ├── contentast.py      # Content AST for cross-format rendering
│   ├── premade_questions/ # Built-in question library
│   └── canvas/           # Canvas LMS integration
├── example_files/        # Example quiz configurations
├── documentation/        # User guides
└── quizgen             # CLI entry point

Contributing

Contributions welcome! Areas of interest:

• New question types
• Additional LMS integrations
• Documentation improvements
• Bug fixes

License

GNU General Public License v3.0 or later (GPLv3+) - see LICENSE file for details

Citation

If you use QuizGenerator in academic work, please cite:

@software{quizgenerator,
  author = {Ogden, Sam},
  title = {QuizGenerator: Automated Quiz Generation for Education},
  year = {2024},
  url = {https://github.com/OtterDen-Lab/QuizGenerator}
}

Support

• Issues: https://github.com/OtterDen-Lab/QuizGenerator/issues
• Documentation: https://github.com/OtterDen-Lab/QuizGenerator/tree/main/documentation

---

Note: This tool is designed for educational use. Ensure compliance with your institution's academic integrity policies when using automated quiz generation.