otterden-lms-interface 0.7.3__tar.gz

otterden_lms_interface-0.7.3/.githooks/pre-commit

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# If pyproject version changes, ensure uv.lock is staged in the same commit.
+if git diff --cached -- pyproject.toml | grep -Eq '^[+-][[:space:]]*version[[:space:]]*='; then
+  if ! git diff --cached --name-only | grep -qx 'uv.lock'; then
+    echo "ERROR: pyproject version changed but uv.lock is not staged."
+    echo "Run: uv lock && git add uv.lock"
+    exit 1
+  fi
+fi

otterden_lms_interface-0.7.3/.github/pull_request_template.md

@@ -0,0 +1,34 @@
+# 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 -->

otterden_lms_interface-0.7.3/.github/workflows/release.yml

@@ -0,0 +1,81 @@
+name: Build And Publish Release Artifacts
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build Distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Verify tag matches project version
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          project_version="$(sed -n 's/^version = "\(.*\)"/\1/p' pyproject.toml | head -n 1)"
+          if [[ "${tag_version}" != "${project_version}" ]]; then
+            echo "Tag version (${tag_version}) does not match pyproject version (${project_version})."
+            exit 1
+          fi
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        run: uv publish
+
+  release:
+    name: Create GitHub Release
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish release with artifacts
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          generate_release_notes: true
+          files: dist/*

otterden_lms_interface-0.7.3/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+.idea/
+.DS_Store
+*.zip
+.env
+.envrc
+.venv/
+*.pyc
+*.pyo
+*.pyd
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+CLAUDE.md
+*.so
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/

otterden_lms_interface-0.7.3/AGENTS.md

@@ -0,0 +1,37 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+`lms_interface/` contains the library code. Key modules include `canvas_interface.py` (Canvas API integration), `backends.py`/`interfaces.py` (backend abstraction), `privacy.py` (FERPA-friendly redaction), and `helpers.py` (CLI helpers such as `cleanup-missing`).
+
+Tests live in `lms_interface/tests/` and mirror module behavior (`test_canvas_interface.py`, `test_helpers.py`, `test_privacy.py`). Keep new tests in this directory so vendoring stays clean.
+
+Repository utilities live in `scripts/`:
+- `install_git_hooks.sh` installs local hooks and `git bump`.
+- `git_bump.sh` bumps version, runs tests, updates `uv.lock`, and commits.
+- `vendor_into_project.py` vendors this package into downstream tools.
+
+## Build, Test, and Development Commands
+- `uv sync --dev`: install runtime and dev dependencies from `pyproject.toml`/`uv.lock`.
+- `uv run pytest -q`: run the full test suite (default `testpaths` is `lms_interface/tests`).
+- `uv run ruff check lms_interface lms_interface/tests`: run lint/import-order checks.
+- `uv run black lms_interface lms_interface/tests`: format code (88-char lines).
+- `bash scripts/install_git_hooks.sh`: enable repo hooks (`.githooks/pre-commit`).
+- `uv lock`: regenerate lockfile after dependency or version updates.
+
+## Coding Style & Naming Conventions
+Use Python 3.12 and 4-space indentation. Follow Black formatting (`line-length = 88`) and keep imports Ruff-clean (`I` rules enabled). Use `snake_case` for functions/variables, `PascalCase` for classes, and `test_*.py` for test modules.
+
+Prefer small, focused functions and explicit names around LMS concepts (`CanvasCourse`, `PrivacyBackend`, etc.).
+
+## Testing Guidelines
+Use `pytest` for all tests. Add regression tests for bug fixes and behavior changes, especially for Canvas request/response handling and privacy redaction paths.
+
+Name tests clearly by behavior (for example, `test_cleanup_missing_skips_future_due_assignments`). Run `uv run pytest -q` before opening a PR.
+
+## Commit & Pull Request Guidelines
+Commit messages in this repo are short, imperative, and task-focused (for example, `Add LMS backend abstractions`, `Bump to version 0.4.4`).
+
+PRs should follow `.github/pull_request_template.md`: include a clear description, change type, testing performed, and any relevant screenshots/notes. If `pyproject.toml` version changes, stage `uv.lock` in the same commit (enforced by pre-commit hook).
+
+## Security & Configuration Tips
+Store Canvas credentials in environment variables (`CANVAS_API_URL`, `CANVAS_API_KEY`, plus optional `_prod` variants). Never commit secrets or real student-identifying data.

otterden_lms_interface-0.7.3/CODEOWNERS

@@ -0,0 +1 @@
+* @samogden

otterden_lms_interface-0.7.3/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.5
+Name: otterden-lms-interface
+Version: 0.7.3
+Summary: LMS interface library for teaching tools
+Author-email: Sam Ogden <samuel.s.ogden@gmail.com>
+Requires-Python: >=3.12
+Requires-Dist: canvasapi<4,>=3.2
+Requires-Dist: python-dotenv<2,>=1
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: requests<3,>=2.32.4
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: flake8; extra == 'dev'
+Requires-Dist: jsonschema; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'

otterden_lms_interface-0.7.3/README.md

@@ -0,0 +1,286 @@
+# LMSInterface
+
+Lightweight LMS abstraction focused on Canvas. This repo is primarily used
+as a vendored dependency in teaching tools.
+
+## Usage
+
+Set Canvas credentials in `~/.env` (or pass `env_path` to `CanvasInterface`):
+
+- `CANVAS_API_URL`
+- `CANVAS_API_KEY`
+
+For production, use:
+
+- `CANVAS_API_URL_prod`
+- `CANVAS_API_KEY_prod`
+
+## Tests
+
+Run:
+
+```bash
+pytest
+```
+
+Tests live in `lms_interface/tests/` so they vendor cleanly.
+
+## Cleanup Missing Helper
+
+Use `cleanup-missing` to normalize Canvas late-policy status for unsubmitted work:
+
+- Past due: set to `missing`
+- Future due: set to `none`
+
+The helper can also clear stale placeholder grades (`Incomplete`/`0`) on future-due,
+contentless placeholder submissions.
+
+When run in an interactive terminal, the helper now shows a live progress view
+with the current assignment and a running results table. Use `--plain-output` if
+you want the older plain text behavior.
+
+Run via module:
+
+```bash
+python -m lms_interface.helpers cleanup-missing --course-id <COURSE_ID> --dry-run
+```
+
+Or via script entry point:
+
+```bash
+lms-interface-helper cleanup-missing --course-id <COURSE_ID> --dry-run
+```
+
+Useful flags:
+
+- `--assignment-id <ID>`: scope to one assignment
+- `--clear-placeholder-grade`: clear stale placeholder grades
+- `--include-unpublished`: include unpublished assignments
+- `--debug`: verbose per-student logs
+
+Recommended rollout:
+
+1. Run `--dry-run` on one assignment.
+2. Run live on one assignment and verify in Canvas UI.
+3. Run course-wide with `--dry-run`.
+4. Run course-wide live.
+
+## Manual Grade Test Harness
+
+Use `test.py` for one-off grading against a real Canvas submission while you
+are validating rubric behavior or feedback formatting.
+
+Example:
+
+```bash
+python test.py grade \
+  --course-id <COURSE_ID> \
+  --assignment-id <ASSIGNMENT_ID> \
+  --student-id <STUDENT_ID> \
+  --score 8 \
+  --comments "Well done." \
+  --rubric-assessment '{"criterion 1": 5, "crit2": {"points": 3, "rating_id": "rat3"}}'
+```
+
+Useful notes:
+
+- `--rubric-assessment` accepts either inline JSON/YAML or a path to a file
+  containing an object.
+- Rubric keys should be the exact criterion names shown in Canvas, such as
+  `criterion 1` and `crit2` in the example above.
+- If you omit `--score`, the Canvas wrapper derives the posted grade from the
+  rubric points total.
+- This command posts feedback to an existing assignment. It does not create or
+  attach rubrics to assignments.
+
+## Course Plan Helper
+
+Generate a student-facing calendar (HTML + JSON) from a course plan YAML and
+optionally publish it to Canvas as a page.
+
+Dry-run / local generation only:
+
+```bash
+lms-interface-helper plan-course --yaml-path course_plans/cst334_compact.yaml --output-dir build/cst334
+```
+
+Publish to Canvas:
+
+```bash
+lms-interface-helper plan-course --yaml-path course_plans/cst334_compact.yaml --course-id <COURSE_ID> --publish
+```
+
+Useful flags:
+
+- `--dry-run`: show Canvas actions without writing when `--publish` is used
+- `--page-title`: override published page title
+- `--module-name`: module to place schedule page link in (default: `Course Schedule`)
+- `--publish-weekly-slides`: create/reuse `Week XX` modules and add slide URL links
+- `--weekly-module-template`: override week module naming (default from plan: `Week {week_number}`)
+
+Plan hint:
+
+- Set `sync.topics_per_meeting: 2` (or higher) when a single class session covers multiple topic blocks.
+- Set `duration_hours` on a topic when it needs extra in-class time (for example `duration_hours: 3`).
+- Use reusable placeholders to insert spacer blocks without redefining `tbd-*` topics each term.
+- Define `resource_defaults.lecture_slides_base_url` to avoid repeating full slide URLs in each topic.
+
+Example:
+
+```yaml
+resource_defaults:
+  lecture_slides_base_url: https://github.com/CSUMB-SCD-instructors/CST334/tree/main/slides/pdfs
+
+topics:
+  - id: process-scheduling-os7
+    lecture_slides:
+      - OSTEP 07.pdf
+```
+
+Reusable placeholder example:
+
+```yaml
+placeholders:
+  tbd:
+    title: Buffer / TBD
+    new_material: false
+
+topics:
+  - id: mlfq
+    duration_hours: 3
+  - placeholder: tbd
+    duration_hours: 1
+```
+
+Validate a plan file against the schema:
+
+```bash
+python scripts/validate_course_plan.py course_plans/cst334_compact.yaml
+```
+
+## Parallel Uploads
+
+Question uploads support multi-threading to speed up large quizzes. The default
+behavior uses a small worker pool and limits in-flight requests.
+
+Defaults:
+
+- `max_workers = 4`
+- `max_in_flight = 8`
+
+If any worker receives a Canvas `429`, all workers respect a shared backoff
+window before continuing.
+
+You can override these via `CanvasCourse.create_question(...)` or by calling
+the lower-level `_upload_question_payloads(...)`.
+
+## Backend Abstraction (LTI-Ready)
+
+New tools should depend on the LMS-agnostic interfaces and adapters instead
+of Canvas directly. This makes it easier to add an LTI backend later.
+
+Recommended entry points:
+
+- `CanvasBackend` for the current Canvas API
+- `PrivacyBackend` to enforce FERPA-friendly anonymization
+- `CanvasInterface(privacy_mode="id_only")` for quick ID-only redaction
+
+By default, student names are redacted. To request real names, pass
+`include_names=True` to:
+
+- `CanvasCourse.get_students(...)`
+- `CanvasAssignment.get_submissions(...)`
+- `CanvasQuiz.get_quiz_submissions(...)`
+
+Example:
+
+```python
+from lms_interface.backends import CanvasBackend
+from lms_interface.privacy import PrivacyBackend
+
+backend = CanvasBackend(prod=False)
+backend = PrivacyBackend(backend, salt="my-course-salt", mode="pseudonymous")
+
+course = backend.get_course(12345)
+students = course.get_students()
+```
+
+Privacy modes:
+
+- `pseudonymous`: hashed IDs (requires `LMS_PRIVACY_SALT`)
+- `id_only`: uses the real Canvas ID but redacts names (`Student <id>`)
+
+## Vendoring
+
+Use the shared script to vendor into another project:
+
+```bash
+python scripts/vendor_into_project.py /path/to/target --top-level
+```
+
+## GitHub Release Artifacts
+
+This repo can publish wheel/sdist artifacts to GitHub Releases on tag pushes.
+
+Flow:
+
+1. Bump version and publish commit/tag in one step (for example via `git bump patch`).
+2. GitHub Actions builds `dist/*` and attaches artifacts to that release.
+
+Default one-command option:
+
+```bash
+git bump patch
+```
+
+Optional local-only bump (no push/tag):
+
+```bash
+git bump patch --no-tag --no-push
+```
+
+Tag/version contract:
+
+- Tag `vX.Y.Z` must match `project.version = "X.Y.Z"` in `pyproject.toml`.
+- The release workflow fails if they do not match.
+
+Downstream projects can pin to a release artifact instead of vendoring:
+
+```toml
+dependencies = [
+  "lms-interface @ https://github.com/<org>/LMSInterface/releases/download/v0.4.5/lms_interface-0.4.5-py3-none-any.whl",
+]
+```
+
+## Peer-Review Surveys
+
+Create one restricted Canvas graded survey per PDF, with a shared YAML rubric and
+randomized student assignments:
+
+```bash
+lms-interface-helper peer-review --course-id <COURSE_ID> \
+  --yaml-path example_files/peer-review-questions.yaml --dry-run
+```
+
+Remove `--dry-run` to create the surveys. The beta deliberately creates a new
+batch on every live run. The YAML requires `unlock_at`, `due_at`, and `lock_at`;
+`points_possible` defaults to 1, `published` defaults to `false`, and
+`reviews_per_student` is a per-reviewer cap (default 3). Each PDF receives at least
+three reviews by default, and every eligible reviewer receives at least one distinct
+PDF when possible. Configure `min_reviews_per_submission` and
+`min_reviews_per_student` to override those minimums.
+
+For submitted reports, use the source assignment instead of the `pdfs` list:
+
+```bash
+lms-interface-helper peer-review --course-id <COURSE_ID> \
+  --source-assignment-id <ASSIGNMENT_ID> --yaml-path peer-review.yaml
+```
+
+The helper takes the first PDF attachment from each source submission and never
+assigns a student their own submission. Local `pdfs` remain available for debug
+runs. Use `--seed` to reproduce a randomized allocation.
+
+Peer-review YAML ignores legacy section `note` fields. Use `instructions` on the
+rubric (shown above the PDF) or on a section (shown under that section heading)
+for student-facing guidance.