QuizGenerator 0.9.0__tar.gz → 0.10.0__tar.gz

quizgenerator-0.10.0/.github/pull_request_template.md

@@ -0,0 +1,36 @@
+# Pull Request
+
+## Description
+<!-- Provide a brief description of what this PR accomplishes -->
+
+## Changes Made
+<!-- List the key changes made in this PR -->
+- 
+- 
+- 
+
+## Type of Change
+<!-- Mark the appropriate option with an [x] -->
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Refactoring (no functional changes)
+
+## Testing Done
+<!-- Describe the testing you've done to verify your changes -->
+
+## Checklist
+<!-- Mark the appropriate options with an [x] -->
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have updated the documentation accordingly
+- [ ] My changes generate no new warnings
+- [ ] Any dependent changes have been merged and published
+
+## Screenshots (if applicable)
+<!-- Add screenshots here if they help explain your changes -->
+
+## Notes
+<!-- Any additional notes or context about the PR -->

quizgenerator-0.10.0/.github/workflows/release.yaml

@@ -0,0 +1,146 @@
+name: Release on version bump
+
+on:
+  push:
+    branches:
+      - main    # change if your default branch is different
+  workflow_dispatch:    # allows manual triggering from GitHub Actions UI
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      contents: write   # create tags & releases
+      id-token: write   # PyPI trusted publishing
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0   # need history to read previous version
+
+      - name: Set up Python for tooling
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Get previous version (from parent commit)
+        id: prev_version
+        run: |
+          BEFORE="${{ github.event.before }}"
+
+          # First commit / no parent? treat as "no previous version"
+          if [ "$BEFORE" = "0000000000000000000000000000000000000000" ] || [ -z "$BEFORE" ]; then
+            echo "No previous commit; setting previous version empty."
+            echo "version=" >> "$GITHUB_OUTPUT"
+          else
+            if git show "$BEFORE":pyproject.toml > pyproject_prev.toml 2>/dev/null; then
+              VERSION=$(python -c "import tomllib, pathlib; d = tomllib.loads(pathlib.Path('pyproject_prev.toml').read_text()); print(d['project']['version'])")
+              echo "previous version: $VERSION"
+              echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+            else
+              echo "No previous pyproject.toml found; setting previous version empty."
+              echo "version=" >> "$GITHUB_OUTPUT"
+            fi
+          fi
+
+      - name: Get current version
+        id: curr_version
+        run: |
+          VERSION=$(python -c "import tomllib, pathlib; d = tomllib.loads(pathlib.Path('pyproject.toml').read_text()); print(d['project']['version'])")
+          echo "current version: $VERSION"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Decide whether this is a release commit
+        id: decision
+        run: |
+          PREV="${{ steps.prev_version.outputs.version }}"
+          CURR="${{ steps.curr_version.outputs.version }}"
+          MSG="${{ github.event.head_commit.message }}"
+
+          echo "Previous version: '$PREV'"
+          echo "Current version:  '$CURR'"
+          echo "Commit message:   '$MSG'"
+
+          SHOULD_RELEASE=false
+
+          # Release whenever the version changes
+          if [ -n "$CURR" ] && [ "$CURR" != "$PREV" ]; then
+            echo "Version changed from '$PREV' to '$CURR'; triggering release."
+            SHOULD_RELEASE=true
+          else
+            echo "Version did not change; not releasing."
+          fi
+
+          echo "release=$SHOULD_RELEASE" >> "$GITHUB_OUTPUT"
+
+      - name: Stop if not a release
+        if: steps.decision.outputs.release != 'true'
+        run: |
+          echo "Not a release commit; skipping remaining steps."
+          exit 0
+
+      - name: Ensure tag does not already exist
+        if: steps.decision.outputs.release == 'true'
+        run: |
+          VERSION="${{ steps.curr_version.outputs.version }}"
+          TAG="v${VERSION}"
+
+          echo "Checking for existing tag $TAG"
+          if git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "Tag $TAG already exists. Aborting."
+            exit 1
+          fi
+
+      - name: Create and push tag
+        if: steps.decision.outputs.release == 'true'
+        run: |
+          VERSION="${{ steps.curr_version.outputs.version }}"
+          TAG="v${VERSION}"
+
+          echo "Creating tag $TAG at $GITHUB_SHA"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          git tag "$TAG" "$GITHUB_SHA"
+          git push origin "$TAG"
+
+      - name: Install uv
+        if: steps.decision.outputs.release == 'true'
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install Python 3.13 for build
+        if: steps.decision.outputs.release == 'true'
+        run: uv python install 3.13
+
+      - name: Build
+        if: steps.decision.outputs.release == 'true'
+        run: uv build
+
+      - name: Upload dist artifacts
+        if: steps.decision.outputs.release == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        if: steps.decision.outputs.release == 'true'
+        run: uv publish
+
+      - name: Create GitHub Release
+        if: steps.decision.outputs.release == 'true'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.curr_version.outputs.version }}
+          name: v${{ steps.curr_version.outputs.version }}
+          body: |
+            Release v${{ steps.curr_version.outputs.version }}
+
+            - Version bumped in pyproject.toml
+            - Built with uv and published to PyPI.
+            - Artifacts attached below.
+          files: dist/*

{quizgenerator-0.9.0 → quizgenerator-0.10.0}/.gitignore

@@ -11,5 +11,4 @@ debug.*
 .claude
 *.log
 dist/
-*.md
-*.yaml
+agent_notes/

quizgenerator-0.10.0/AGENTS.md

@@ -0,0 +1,58 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+- `QuizGenerator/` is the main Python package (question types, quiz generation, Canvas integration).
+- `quizgen` provides the CLI entry point; the package also exposes `quizregen`.
+- `documentation/` contains user guides and configuration references.
+- `example_files/` and `examples/` hold sample YAML configs and outputs.
+- `scripts/` includes maintenance utilities (see `scripts/README.md`).
+- `out/` is the default output directory for generated PDFs and artifacts.
+
+## Build, Test, and Development Commands
+
+- `pip install -e .` — install the package in editable mode for local development.
+- `quizgen --help` — show CLI options.
+- `quizgen --yaml example_files/example_exam.yaml --num_pdfs 3` — generate PDFs in `out/` (Typst is the default renderer).
+- `quizgen --latex --num_pdfs 3` — force LaTeX rendering when needed.
+- `python scripts/vendor_lms_interface.py --dry-run` — preview LMSInterface vendoring changes.
+
+## Coding Style & Naming Conventions
+
+- Python 3.12+; follow PEP 8 with 4-space indentation.
+- Use `snake_case` for functions/variables, `PascalCase` for classes, and `UPPER_SNAKE_CASE` for constants.
+- Keep modules focused; new question types belong under `QuizGenerator/premade_questions/` or a custom module referenced in YAML.
+
+## Question Authoring Pattern
+
+- Implement `_build_context`, `_build_body`, and `_build_explanation` on every question class.
+- `_build_context` should seed and return a `QuestionContext`; use `context.rng` (or `context["rng"]`) for deterministic randomness.
+- Add extra data via `context["key"] = value` (stored in `context.data`); keep instance state immutable.
+- `_build_body` and `_build_explanation` take `context` and should avoid mutating instance state.
+- Do not implement or call `refresh()`; it has been removed.
+
+## Testing Guidelines
+
+- No dedicated test suite is currently committed.
+- For changes, run a manual smoke check by generating a small quiz:
+  - `quizgen --yaml example_files/example_exam.yaml --num_pdfs 1`
+- If adding tests, prefer `tests/` with filenames like `test_<area>.py` and document how to run them.
+
+## Commit & Pull Request Guidelines
+
+- Commit messages in this repo are short, sentence-case summaries (e.g., “Fixing rounding in round robin”).
+- Keep commits focused and explain *why* when the change is non-obvious.
+- PRs should include:
+  - A brief description of the change and rationale.
+  - Example output or screenshots for rendering/formatting changes.
+  - Any new CLI flags or YAML options documented in `documentation/`.
+
+## Security & Configuration Tips
+
+- Canvas credentials are read from `~/.env` (`CANVAS_API_URL`, `CANVAS_API_KEY`).
+- PDF generation uses Typst by default; LaTeX is legacy and may be removed.
+- Avoid committing generated files in `out/` or local secrets.
+
+## Agent Notes Policy
+
+- Store any agent-generated Markdown notes in `agent_notes/` at the repo root.

quizgenerator-0.10.0/CLAUDE.md

@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Python-based teaching tools project focused on quiz generation and Canvas LMS integration. The main entry point is `generate_quiz.py`, which generates quizzes in both PDF format and Canvas variations based on YAML configuration files.
+
+## Architecture
+
+### Core Modules
+- **QuizGenerator/**: Main quiz generation engine
+  - `quiz.py`: Core Quiz class that loads from YAML and generates output
+  - `question.py`: Question classes and registry system for different question types
+  - `premade_questions/`: Collection of specialized question generators (memory, processes, persistence, etc.)
+  - `misc.py`: Utilities for output formats and content handling
+
+- **lms_interface/**: Canvas LMS integration (submodule)
+  - `canvas_interface.py`: CanvasInterface and CanvasCourse classes for API interaction
+  - `classes.py`: Data models for LMS objects
+
+### Question System
+The project uses a plugin-based question system where question types are defined as classes in `premade_questions/` and registered dynamically. Questions are defined in YAML files that specify the class name and parameters.
+
+### Configuration Files
+Quiz configurations are stored in `example_files/` as YAML files. The default configuration is `exam_generation.yaml`, which defines question types, point values, and organization.
+
+## Development Commands
+
+### Environment Setup
+```bash
+# The project uses uv for dependency management
+uv sync
+source .venv/bin/activate
+```
+
+### Running the Main Script
+```bash
+# Generate PDFs only
+python generate_quiz.py --num_pdfs 3
+
+# Generate Canvas quizzes (requires course_id)
+python generate_quiz.py --num_canvas 5 --course_id 12345
+
+# Use production Canvas instance
+python generate_quiz.py --prod --num_canvas 2 --course_id 12345
+
+# Custom quiz configuration
+python generate_quiz.py --quiz_yaml example_files/custom_quiz.yaml --num_pdfs 2
+```
+
+### Quality Tools
+The project includes development dependencies for code quality:
+```bash
+# Code formatting
+black .
+
+# Linting
+flake8
+
+# Type checking
+mypy QuizGenerator/
+
+# Testing
+pytest
+```
+
+### LaTeX Dependencies
+PDF generation requires LaTeX with `latexmk`. Generated PDFs are output to the `out/` directory.
+
+## Key Files and Patterns
+
+- Quiz configurations follow the pattern in `example_files/exam_generation.yaml`
+- New question types should extend base classes in `question.py` and be placed in `premade_questions/`
+- The project uses logging extensively - check `teachingtools.log` for detailed output
+- Canvas integration requires environment variables for API keys (see `.env` symlink)
+
+## Testing Notes
+
+The project includes a test mode accessible via `python generate_quiz.py TEST`.

{quizgenerator-0.9.0 → quizgenerator-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: QuizGenerator
-Version: 0.9.0
+Version: 0.10.0
 Summary: Generate randomized quiz questions for Canvas LMS and PDF exams
 Project-URL: Homepage, https://github.com/OtterDen-Lab/QuizGenerator
 Project-URL: Documentation, https://github.com/OtterDen-Lab/QuizGenerator/tree/main/documentation
@@ -19,9 +19,7 @@ Classifier: Topic :: Education :: Testing
 Requires-Python: >=3.12
 Requires-Dist: canvasapi==3.2.0
 Requires-Dist: cryptography>=41.0.0
-Requires-Dist: graphviz>=0.21
 Requires-Dist: jinja2==3.1.3
-Requires-Dist: keras>=3.12.0
 Requires-Dist: markdown>=3.9
 Requires-Dist: matplotlib
 Requires-Dist: pylatex>=1.4.2
@@ -32,7 +30,10 @@ Requires-Dist: pyyaml==6.0.1
 Requires-Dist: requests==2.32.2
 Requires-Dist: segno>=1.6.0
 Requires-Dist: sympy>=1.14.0
-Requires-Dist: tensorflow>=2.20.0
+Provides-Extra: cst463
+Requires-Dist: graphviz>=0.21; extra == 'cst463'
+Requires-Dist: keras>=3.12.0; extra == 'cst463'
+Requires-Dist: tensorflow>=2.20.0; extra == 'cst463'
 Provides-Extra: grading
 Requires-Dist: pillow>=10.0.0; extra == 'grading'
 Requires-Dist: pyzbar>=0.1.9; extra == 'grading'
@@ -60,18 +61,24 @@ pip install QuizGenerator
 ### System Requirements
 
 - Python 3.12+
-- LaTeX distribution with `latexmk` (for PDF generation)
-- Optional: [Typst](https://typst.app/) (alternative to LaTeX)
+- [Typst](https://typst.app/) (default PDF renderer)
+- Optional: LaTeX distribution with `latexmk` (if using `--latex`)
+- Recommended: [Pandoc](https://pandoc.org/) (for markdown conversion)
 
 ### Optional Dependencies
 
 ```bash
 # 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)
 
 ```yaml
@@ -94,7 +101,7 @@ questions:
 ### 2. Generate PDFs
 
 ```bash
-python -m generate_quiz --quiz_yaml my_quiz.yaml --num_pdfs 3
+quizgen --yaml my_quiz.yaml --num_pdfs 3
 ```
 
 PDFs will be created in the `out/` directory.
@@ -106,8 +113,8 @@ PDFs will be created in the `out/` directory.
 # CANVAS_API_URL=https://canvas.instructure.com
 # CANVAS_API_KEY=your_api_key_here
 
-python -m generate_quiz \
-  --quiz_yaml my_quiz.yaml \
+quizgen \
+  --yaml my_quiz.yaml \
   --num_canvas 5 \
   --course_id 12345
 ```
@@ -194,10 +201,9 @@ Notes:
 
 ## Documentation
 
-- [Getting Started Guide](documentation/getting_started.md) (coming soon)
+- [Getting Started Guide](documentation/getting_started.md)
 - [Custom Questions Guide](documentation/custom_questions.md)
-- [YAML Configuration Reference](documentation/yaml_config_guide.md) (coming soon)
-- [PyPI Release Plan](documentation/pypi_release_plan.md)
+- [YAML Configuration Reference](documentation/yaml_config_guide.md)
 
 ## Canvas Setup
 
@@ -216,25 +222,28 @@ CANVAS_API_KEY_prod=your_prod_api_key
 2. Use `--prod` flag for production Canvas instance:
 
 ```bash
-python -m generate_quiz --prod --num_canvas 5 --course_id 12345
+quizgen --prod --num_canvas 5 --course_id 12345
 ```
 
 ## Advanced Features
 
 ### Typst Support
 
-Use Typst instead of LaTeX for faster compilation:
+Typst is the default for faster compilation. Use `--latex` to force LaTeX:
 
 ```bash
-python -m generate_quiz --typst --num_pdfs 3
+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:
 
 ```bash
-python -m generate_quiz --seed 42 --num_pdfs 3
+quizgen --seed 42 --num_pdfs 3
 ```
 
 ### QR Code Regeneration
@@ -258,7 +267,7 @@ QuizGenerator/
 │   └── canvas/           # Canvas LMS integration
 ├── example_files/        # Example quiz configurations
 ├── documentation/        # User guides
-└── generate_quiz.py     # CLI entry point
+└── quizgen             # CLI entry point
 ```
 
 ## Contributing

quizgenerator-0.10.0/QuizGenerator/README.md

@@ -0,0 +1,5 @@
+
+
+## Installation
+
+Note, you will need to install `pandoc` prior to running since it is used to convert to HTML (for canvas) and Latex (for PDF)`

{quizgenerator-0.9.0 → quizgenerator-0.10.0}/QuizGenerator/canvas/canvas_interface.py

@@ -37,8 +37,12 @@ NUM_WORKERS = 4
 
 
 class CanvasInterface:
-  def __init__(self, *, prod=False):
-    dotenv.load_dotenv(os.path.join(os.path.expanduser("~"), ".env"))
+  def __init__(self, *, prod=False, env_path: str | None = None):
+    default_env = os.path.join(os.path.expanduser("~"), ".env")
+    if env_path and os.path.exists(env_path):
+      dotenv.load_dotenv(env_path)
+    elif os.path.exists(default_env):
+      dotenv.load_dotenv(default_env)
 
     self.prod = prod
     if self.prod:

{quizgenerator-0.9.0 → quizgenerator-0.10.0}/QuizGenerator/contentast.py

@@ -23,6 +23,21 @@ import numpy as np
 
 log = logging.getLogger(__name__)
 
+_PANDOC_OK = None
+
+
+def _ensure_pandoc() -> bool:
+  global _PANDOC_OK
+  if _PANDOC_OK is not None:
+    return _PANDOC_OK
+  try:
+    pypandoc.get_pandoc_version()
+    _PANDOC_OK = True
+  except Exception as exc:
+    _PANDOC_OK = False
+    log.warning(f"Pandoc not found or unusable: {exc}")
+  return _PANDOC_OK
+
 
 """
 Content Abstract Syntax Tree - The core content system for quiz generation.
@@ -221,6 +236,9 @@ class Leaf(Element):
           return html_output.strip()
         
         case _:
+          if not _ensure_pandoc():
+            log.warning(f"Pandoc unavailable; returning raw markdown for {output_format} output.")
+            return str_to_convert
           output = pypandoc.convert_text(
             str_to_convert,
             output_format,
@@ -549,16 +567,18 @@ class Question(Container):
           
           # Build extra_data dict with regeneration metadata if available
           extra_data = {}
-          if hasattr(self, 'question_class_name') and hasattr(self, 'generation_seed') and hasattr(
-              self, 'question_version'
-          ):
-            if self.question_class_name and self.generation_seed is not None and self.question_version:
+          if hasattr(self, 'question_class_name') and hasattr(self, 'generation_seed'):
+            if self.question_class_name and self.generation_seed is not None:
               extra_data['question_type'] = self.question_class_name
               extra_data['seed'] = self.generation_seed
-              extra_data['version'] = self.question_version
+              if hasattr(self, 'question_version') and self.question_version:
+                extra_data['version'] = self.question_version
               # Include question-specific configuration parameters if available
               if hasattr(self, 'config_params') and self.config_params:
                 extra_data['config'] = self.config_params
+              # Include context-derived extras if available
+              if hasattr(self, 'qr_context_extras') and self.qr_context_extras:
+                extra_data['context'] = self.qr_context_extras
           
           qr_path = QuestionQRCode.generate_qr_pdf(
             self.question_number,
@@ -615,16 +635,18 @@ class Question(Container):
         
         # Build extra_data dict with regeneration metadata if available
         extra_data = {}
-        if hasattr(self, 'question_class_name') and hasattr(self, 'generation_seed') and hasattr(
-            self, 'question_version'
-        ):
-          if self.question_class_name and self.generation_seed is not None and self.question_version:
+        if hasattr(self, 'question_class_name') and hasattr(self, 'generation_seed'):
+          if self.question_class_name and self.generation_seed is not None:
             extra_data['question_type'] = self.question_class_name
             extra_data['seed'] = self.generation_seed
-            extra_data['version'] = self.question_version
+            if hasattr(self, 'question_version') and self.question_version:
+              extra_data['version'] = self.question_version
             # Include question-specific configuration parameters if available
             if hasattr(self, 'config_params') and self.config_params:
               extra_data['config'] = self.config_params
+            # Include context-derived extras if available
+            if hasattr(self, 'qr_context_extras') and self.qr_context_extras:
+              extra_data['context'] = self.qr_context_extras
         
         # Generate QR code PNG
         qr_path = QuestionQRCode.generate_qr_pdf(