Download app/worksheets.py from wzender/mathly: direct link, hf CLI and curl.
- Browser
- Download file 35 kB
-
https://huggingface.co/spaces/wzender/mathly/resolve/main/app/worksheets.py
- Command line
-
hf download hf://spaces/wzender/mathly/app/worksheets.py
-
curl -L -o worksheets.py https://huggingface.co/spaces/wzender/mathly/resolve/main/app/worksheets.py
35 kB
| """Worksheets: a PDF or photos a class teacher attaches to an assignment, and the students' photographed solutions. | |
| A worksheet (Supabase `math_worksheets`) belongs to one class. The teacher uploads it first, then saves an assignment | |
| with a `{"kind": "worksheet", "id"}` item (app/assignments.py). A worksheet that no assignment uses is deleted after a | |
| day by the hourly cleanup (app/answer_cleanup.py), and one dropped from an assignment, or whose assignment is deleted, | |
| goes at once, with its submissions. | |
| A PDF is rendered to page images here, so every phone shows it the same way; the PDF itself is kept to download. | |
| Photos, the teacher's and the students', go through `clean_image` (re-encoded, metadata dropped). | |
| A student hands in 1 to 10 photos with an optional note to the teacher (`math_worksheet_submissions`), and may replace | |
| them until the teacher checks. The teacher's check is a time, an optional score (0-100) and an optional comment. The | |
| teacher may instead return the submission for a fix, with a comment and maybe a new due date: the student's next | |
| hand-in is a new version, and the earlier ones stay to look back at. The current submission is the highest version. | |
| Files live in the private `mathly-worksheets` bucket. Only the server reads or writes rows and files, with the service | |
| key; the browser never sees a storage path. | |
| """ | |
| from __future__ import annotations | |
| import io | |
| import json | |
| import logging | |
| import time | |
| import urllib.error | |
| import urllib.parse | |
| import urllib.request | |
| import uuid | |
| from datetime import date, datetime, timedelta, timezone | |
| from fastapi import Depends, File, Form, HTTPException, UploadFile | |
| from fastapi.responses import JSONResponse, Response | |
| from starlette.concurrency import run_in_threadpool | |
| from .access import has_permission | |
| from . import ai_usage | |
| from .answer_routes import grading_key, open_ended_locked | |
| from .answer_scans import MAX_IMAGE, ScanError, clean_image | |
| from .auth import AuthUnavailable, ClassConflict | |
| from .homework_grading import HomeworkGrader | |
| from .math_photo import PhotoUnavailable | |
| from .teacher_ai import LimitReached, MESSAGE as TEACHER_AI_MESSAGE | |
| log = logging.getLogger("mathly.worksheets") | |
| MIGRATION = "supabase/migrations/20261105090000_math_worksheets.sql" | |
| BUCKET = "mathly-worksheets" | |
| MAX_PDF = 10_000_000 | |
| MAX_PAGES = 10 | |
| MAX_TITLE = 80 | |
| MAX_COMMENT = 1000 | |
| PAGE_WIDTH = 1600 # a rendered PDF page, in pixels | |
| RENDER_BUDGET = 30.0 # seconds for all the pages of one PDF | |
| UNUSED_AGE = timedelta(hours=24) | |
| W_FIELDS = "id,class_id,title,source,pages,original_key,page_keys,byte_size,created_by_email,created_at" | |
| S_FIELDS = ("id,worksheet_id,student_id,student_email,page_keys,submitted_at,checked_at,score,comment,checked_by_email," | |
| "version,state,note,returned_at,return_comment,return_due_on,ai_score,ai_comment,ai_readable,ai_checked_at") | |
| OLD_S_FIELDS = "id,worksheet_id,student_id,student_email,page_keys,submitted_at,checked_at,score,comment,checked_by_email" | |
| NEW_COLUMNS = ("version", "state", "note", "returned_at", "return_comment", "return_due_on") | |
| AI_COLUMNS = ("ai_score", "ai_comment", "ai_readable", "ai_checked_at") # the AI-batches migration | |
| AI_FIELDS = ",ai_score,ai_comment,ai_readable,ai_checked_at" | |
| MAX_NOTE = 300 | |
| class WorksheetsUnavailable(RuntimeError): | |
| pass | |
| class Worksheets: | |
| """Rows through the service key (auth._admin), files in the private bucket.""" | |
| legacy = False # True once the versions migration was found missing | |
| no_ai = False # True once the AI-batches migration was found missing | |
| def __init__(self, auth): | |
| self.auth = auth | |
| self._warned = False | |
| def configured(self) -> bool: | |
| return bool(self.auth is not None and getattr(self.auth, "secret", None)) | |
| # ---- rows | |
| def _rest(self, path: str, method: str = "GET", body=None, prefer: str = "return=representation"): | |
| if not self.configured: | |
| raise WorksheetsUnavailable("worksheets_unavailable") | |
| if "math_worksheet_submissions" in path: | |
| if self.legacy: # before versions: the table as it was (no AI columns either) | |
| path, body = legacy(path, body) | |
| if self.no_ai or self.legacy: | |
| path = path.replace(AI_FIELDS, "") | |
| body = {k: v for k, v in body.items() if k not in AI_COLUMNS} if isinstance(body, dict) else body | |
| try: | |
| return self.auth._admin(path, method, body, prefer) or [] | |
| except ClassConflict as exc: | |
| raise WorksheetsUnavailable("worksheets_unavailable") from exc | |
| except AuthUnavailable as exc: | |
| if "math_worksheet_submissions" in path and any(c in str(exc) for c in AI_COLUMNS) and not self.no_ai: | |
| log.warning("worksheet submissions have no AI suggestions yet; apply the AI-batches migration") | |
| self.no_ai = True | |
| return self._rest(path, method, body, prefer) | |
| if "math_worksheet_submissions" in path and any(c in str(exc) for c in NEW_COLUMNS) and not self.legacy: | |
| # the versions migration is not applied yet: hand-ins and checks work as before, returns do not | |
| log.warning("worksheet submissions have no versions yet; apply %s", VERSIONS_MIGRATION) | |
| self.legacy = True | |
| return self._rest(path, method, body, prefer) | |
| if "answered 404" in str(exc) and not self._warned: | |
| log.warning("the worksheet tables are missing; apply %s", MIGRATION) | |
| self._warned = True | |
| raise WorksheetsUnavailable("worksheets_unavailable") from exc | |
| def add(self, row: dict) -> dict: | |
| return self._rest(f"/rest/v1/math_worksheets?select={W_FIELDS}", "POST", row)[0] | |
| def get(self, worksheet_id: str) -> dict | None: | |
| rows = self._rest(f"/rest/v1/math_worksheets?select={W_FIELDS}&id=eq.{worksheet_id}") | |
| return rows[0] if rows else None | |
| def of_class(self, class_id: int) -> list[dict]: | |
| return self._rest(f"/rest/v1/math_worksheets?select={W_FIELDS}&class_id=eq.{int(class_id)}&order=created_at.asc") | |
| def by_ids(self, ids) -> list[dict]: | |
| ids = sorted(set(ids)) | |
| if not ids: | |
| return [] | |
| return self._rest(f"/rest/v1/math_worksheets?select={W_FIELDS}&id=in.({','.join(ids)})") | |
| def older_than(self, cutoff: datetime) -> list[dict]: | |
| at = urllib.parse.quote(cutoff.astimezone(timezone.utc).isoformat()) | |
| return self._rest(f"/rest/v1/math_worksheets?select={W_FIELDS}&created_at=lt.{at}") | |
| def remove(self, worksheet_id: str) -> None: | |
| self._rest(f"/rest/v1/math_worksheets?id=eq.{worksheet_id}", "DELETE") | |
| def submissions(self, worksheet_ids, student_id: str | None = None) -> list[dict]: | |
| ids = sorted(set(worksheet_ids)) | |
| if not ids: | |
| return [] | |
| who = f"&student_id=eq.{student_id}" if student_id else "" | |
| return self._rest(f"/rest/v1/math_worksheet_submissions?select={S_FIELDS}&worksheet_id=in.({','.join(ids)}){who}") | |
| def submission(self, submission_id: str) -> dict | None: | |
| rows = self._rest(f"/rest/v1/math_worksheet_submissions?select={S_FIELDS}&id=eq.{submission_id}") | |
| return rows[0] if rows else None | |
| def add_submission(self, row: dict) -> dict: | |
| """A new version of the student's submission (the first, or the one after a return).""" | |
| return self._rest(f"/rest/v1/math_worksheet_submissions?select={S_FIELDS}", "POST", row)[0] | |
| def check(self, submission_id: str, fields: dict) -> dict | None: | |
| rows = self._rest(f"/rest/v1/math_worksheet_submissions?id=eq.{submission_id}&select={S_FIELDS}", "PATCH", fields) | |
| return rows[0] if rows else None | |
| # ---- files | |
| def _storage(self, path: str, method: str = "GET", data: bytes | None = None, content_type: str | None = None) -> bytes: | |
| if not self.configured: | |
| raise WorksheetsUnavailable("worksheets_unavailable") | |
| headers = {"Authorization": "Bearer " + self.auth.secret, "apikey": self.auth.secret, "User-Agent": "mathly/1.0"} | |
| if content_type: | |
| headers["Content-Type"] = content_type | |
| request = urllib.request.Request(self.auth.url + path, data=data, method=method, headers=headers) | |
| try: | |
| with urllib.request.urlopen(request, timeout=60) as response: | |
| return response.read() | |
| except (urllib.error.URLError, TimeoutError, OSError) as exc: | |
| # never pass keys or storage paths on to the browser | |
| log.warning("worksheet storage failed: %s", getattr(exc, "code", type(exc).__name__)) | |
| raise WorksheetsUnavailable("worksheets_unavailable") from exc | |
| def put(self, key: str, data: bytes, content_type: str = "image/jpeg") -> None: | |
| self._storage(f"/storage/v1/object/{BUCKET}/{urllib.parse.quote(key, safe='/')}", "POST", data, content_type) | |
| def read(self, key: str) -> bytes: | |
| return self._storage(f"/storage/v1/object/authenticated/{BUCKET}/{urllib.parse.quote(key, safe='/')}") | |
| def delete(self, keys: list[str]) -> None: | |
| keys = [k for k in keys if k] | |
| if keys: | |
| self._storage(f"/storage/v1/object/{BUCKET}", "DELETE", json.dumps({"prefixes": keys}).encode(), "application/json") | |
| # ---- files in | |
| def render_pdf(data: bytes) -> list[bytes]: | |
| """The pages of a PDF as JPEGs; HTTPException 400/413 when it is not one we take.""" | |
| if len(data) > MAX_PDF: | |
| raise HTTPException(413, "pdf_too_large") | |
| if not data.startswith(b"%PDF-"): | |
| raise HTTPException(415, "not_a_pdf") | |
| import pypdfium2 as pdfium | |
| try: | |
| doc = pdfium.PdfDocument(data) | |
| except pdfium.PdfiumError as exc: | |
| raise HTTPException(400, "unreadable_pdf") from exc | |
| try: | |
| if len(doc) < 1: | |
| raise HTTPException(400, "unreadable_pdf") | |
| if len(doc) > MAX_PAGES: | |
| raise HTTPException(400, "too_many_pages") | |
| started, pages = time.monotonic(), [] | |
| for page in doc: | |
| if time.monotonic() - started > RENDER_BUDGET: | |
| raise HTTPException(400, "pdf_too_slow") | |
| width, height = page.get_size() | |
| if width <= 0 or height <= 0: | |
| raise HTTPException(400, "unreadable_pdf") | |
| scale = min(PAGE_WIDTH / width, 2400 / height) # at most 1600 wide and 2400 high | |
| image = page.render(scale=scale).to_pil().convert("RGB") | |
| image.thumbnail((PAGE_WIDTH, 2400)) # rendering rounds up a pixel | |
| out = io.BytesIO() | |
| image.save(out, "JPEG", quality=82, optimize=True) | |
| pages.append(out.getvalue()) | |
| return pages | |
| except pdfium.PdfiumError as exc: | |
| raise HTTPException(400, "unreadable_pdf") from exc | |
| finally: | |
| doc.close() | |
| async def read_upload(upload: UploadFile, limit: int) -> bytes: | |
| data = await upload.read(limit + 1) | |
| if len(data) > limit: | |
| raise HTTPException(413, "file_too_large") | |
| return data | |
| async def clean_photos(files: list[UploadFile]) -> list[bytes]: | |
| if not 1 <= len(files) <= MAX_PAGES: | |
| raise HTTPException(400, "too_many_pages" if files else "no_files") | |
| out = [] | |
| for upload in files: | |
| data = await read_upload(upload, MAX_IMAGE) | |
| try: | |
| out.append(await run_in_threadpool(clean_image, data, upload.content_type or "")) | |
| except ScanError as exc: | |
| raise HTTPException(exc.status, exc.code) from exc | |
| return out | |
| # ---- what the browser sees | |
| VERSIONS_MIGRATION = "supabase/migrations/20261106110000_math_worksheet_versions.sql" | |
| def legacy(path: str, body): | |
| """A request for the table as it was before versions.""" | |
| path = path.replace(S_FIELDS, OLD_S_FIELDS) | |
| if isinstance(body, dict): | |
| body = {k: v for k, v in body.items() if k not in NEW_COLUMNS} | |
| return path, body | |
| def current(rows: list[dict]) -> list[dict]: | |
| """The current submission of each student and worksheet (its highest version), with the earlier ones under | |
| `earlier`, newest first.""" | |
| groups: dict[tuple, list[dict]] = {} | |
| for row in rows: | |
| groups.setdefault((row.get("worksheet_id"), row.get("student_id")), []).append(row) | |
| out = [] | |
| for versions in groups.values(): | |
| versions.sort(key=lambda r: r.get("version") or 1, reverse=True) | |
| out.append({**versions[0], "earlier": versions[1:]}) | |
| return out | |
| def worksheet_public(row: dict) -> dict: | |
| return {k: row.get(k) for k in ("id", "class_id", "title", "source", "pages", "created_at")} | |
| def submission_public(row: dict, teacher: bool = False) -> dict: | |
| """A submission without its storage paths (the student's and the teacher's view), with its earlier versions. The | |
| AI's suggestion is the teacher's only: the student sees the check the teacher saves.""" | |
| state = row.get("state") or ("checked" if row.get("checked_at") else "submitted") | |
| out = {"id": row.get("id"), "worksheet_id": row.get("worksheet_id"), "pages": len(row.get("page_keys") or []), | |
| "submitted_at": row.get("submitted_at"), "checked_at": row.get("checked_at"), "score": row.get("score"), | |
| "comment": row.get("comment") or "", "version": row.get("version") or 1, "state": state, | |
| "note": row.get("note") or "", "returned_at": row.get("returned_at"), | |
| "return_comment": row.get("return_comment") or "", "return_due_on": row.get("return_due_on")} | |
| if "earlier" in row: | |
| out["earlier"] = [submission_public(e, teacher) for e in row["earlier"]] | |
| if teacher and row.get("ai_checked_at"): | |
| out["ai"] = {"score": row.get("ai_score"), "comment": row.get("ai_comment") or "", "readable": row.get("ai_readable"), | |
| "checked_at": row.get("ai_checked_at")} | |
| return out | |
| def worksheet_ids(items) -> list[str]: | |
| return [i["id"] for i in items or [] if isinstance(i, dict) and i.get("kind") == "worksheet" and i.get("id")] | |
| def uuid_or_404(value: str, what: str = "worksheet") -> str: | |
| try: | |
| return str(uuid.UUID(str(value))) | |
| except ValueError as exc: | |
| raise HTTPException(404, f"{what} not found") from exc | |
| def drop(store: Worksheets, rows: list[dict]) -> None: | |
| """Deletes worksheets with their submissions (cascade) and every file of both.""" | |
| for row in rows: | |
| keys = list(row.get("page_keys") or []) + [row.get("original_key")] | |
| try: | |
| keys += [k for s in store.submissions([row["id"]]) for k in s.get("page_keys") or []] | |
| except WorksheetsUnavailable: | |
| log.warning("a deleted worksheet's submission images may stay in storage") | |
| store.remove(row["id"]) | |
| try: | |
| store.delete(keys) | |
| except WorksheetsUnavailable: | |
| log.warning("a deleted worksheet's files stayed in storage") | |
| def drop_ids(store: Worksheets, ids) -> int: | |
| """Deletes these worksheets (see drop); the number deleted.""" | |
| rows = store.by_ids(ids) | |
| drop(store, rows) | |
| return len(rows) | |
| def cleanup_unused(store: Worksheets, assignments, now: datetime | None = None) -> int: | |
| """Deletes worksheets older than a day that no assignment of their class uses; the number deleted.""" | |
| now = now or datetime.now(timezone.utc) | |
| old = store.older_than(now - UNUSED_AGE) | |
| if not old: | |
| return 0 | |
| classes = sorted({r["class_id"] for r in old}) | |
| used = {wid for r in assignments.for_classes(classes) for wid in worksheet_ids(r.get("items"))} | |
| unused = [r for r in old if r["id"] not in used] | |
| drop(store, unused) | |
| return len(unused) | |
| def install_worksheet_routes(app, signed_in): | |
| if not hasattr(app.state, "worksheets"): | |
| app.state.worksheets = Worksheets(app.state.auth) | |
| def store() -> Worksheets: | |
| return app.state.worksheets | |
| async def call(fn, *args): | |
| try: | |
| return await run_in_threadpool(fn, *args) | |
| except WorksheetsUnavailable as exc: | |
| raise HTTPException(503, "worksheets_unavailable") from exc | |
| def reply(value, status=200): | |
| return JSONResponse(value, status_code=status, headers={"Cache-Control": "no-store"}) | |
| def image(data: bytes, media_type: str = "image/jpeg", filename: str | None = None): | |
| headers = {"Cache-Control": "private, max-age=3600", "X-Content-Type-Options": "nosniff"} | |
| if filename: | |
| headers["Content-Disposition"] = f"attachment; filename*=UTF-8''{urllib.parse.quote(filename)}" | |
| return Response(data, media_type=media_type, headers=headers) | |
| def record(user, kind, label): | |
| actions = getattr(app.state, "actions", None) | |
| if actions is not None: | |
| actions.record(user, kind, label) | |
| def classes() -> list[dict]: | |
| try: | |
| return app.state.auth.classes() | |
| except AuthUnavailable as exc: | |
| raise HTTPException(503, str(exc)) from exc | |
| def need_user(user): | |
| if not user or not user.get("id"): | |
| raise HTTPException(401, "sign in required") | |
| return user | |
| def teaches(user, row) -> bool: | |
| return str(user.get("email", "")).lower() in row.get("teachers", ()) or has_permission(user, "management.access") | |
| def class_row(class_id: int, user: dict) -> dict: | |
| """The class, if this account is its teacher or a manager.""" | |
| need_user(user) | |
| row = next((r for r in classes() if r.get("id") == class_id), None) | |
| if row is None: | |
| raise HTTPException(404, "class not found") | |
| if not teaches(user, row): | |
| raise HTTPException(403, "only the class's teacher can do this") | |
| return row | |
| async def worksheet_of(class_id: int, wid: str) -> dict: | |
| found = await call(store().get, uuid_or_404(wid)) | |
| if not found or found.get("class_id") != class_id: | |
| raise HTTPException(404, "worksheet not found") | |
| return found | |
| async def readable(user: dict, wid: str) -> tuple[dict, dict]: | |
| """The worksheet and its class, when the account is in that class, teaches it, or is a manager; else 404.""" | |
| need_user(user) | |
| found = await call(store().get, uuid_or_404(wid)) | |
| row = next((r for r in classes() if found and r.get("id") == found.get("class_id")), None) | |
| email = str(user.get("email", "")).lower() | |
| if not found or row is None or not (email in row.get("emails", ()) or teaches(user, row)): | |
| raise HTTPException(404, "worksheet not found") # of another class: as if it did not exist | |
| return found, row | |
| def page_index(n: int, count: int) -> int: | |
| if not 1 <= n <= count: | |
| raise HTTPException(404, "page not found") | |
| return n - 1 | |
| # ---- the class teacher | |
| async def add_worksheet(class_id: int, title: str = Form(""), files: list[UploadFile] = File(...), | |
| user=Depends(signed_in)): | |
| row = class_row(class_id, user) | |
| if not store().configured: | |
| raise HTTPException(503, "worksheets_unavailable") | |
| title = " ".join(title.split()) | |
| if not title or len(title) > MAX_TITLE: | |
| raise HTTPException(400, f"the title is required (up to {MAX_TITLE} characters)") | |
| pdfs = [f for f in files if (f.content_type or "") == "application/pdf" or (f.filename or "").lower().endswith(".pdf")] | |
| original = None | |
| if pdfs: | |
| if len(files) != 1: | |
| raise HTTPException(400, "one_pdf_or_photos") | |
| original = await read_upload(files[0], MAX_PDF) | |
| pages = await run_in_threadpool(render_pdf, original) | |
| else: | |
| pages = await clean_photos(files) | |
| wid = str(uuid.uuid4()) | |
| keys = [f"w/{wid}/{n + 1}.jpg" for n in range(len(pages))] | |
| original_key = f"w/{wid}/original.pdf" if original else None | |
| written = [] | |
| try: | |
| for key, data in zip(keys, pages): | |
| await call(store().put, key, data) | |
| written.append(key) | |
| if original_key: | |
| await call(store().put, original_key, original, "application/pdf") | |
| written.append(original_key) | |
| saved = await call(store().add, { | |
| "id": wid, "class_id": class_id, "title": title, "source": "pdf" if original else "images", | |
| "pages": len(pages), "original_key": original_key, "page_keys": keys, | |
| "byte_size": sum(map(len, pages)) + len(original or b""), | |
| "created_by_email": str(user.get("email", "")).lower()}) | |
| except HTTPException: | |
| try: | |
| await run_in_threadpool(store().delete, written) | |
| except WorksheetsUnavailable: | |
| pass # files without a row are never shown | |
| raise | |
| record(user, "worksheet_added", f"{row.get('name', '')}: {title}") | |
| return reply(worksheet_public(saved), 201) | |
| async def delete_worksheet(class_id: int, wid: str, user=Depends(signed_in)): | |
| """An upload the teacher took back before saving: only while no assignment uses it.""" | |
| class_row(class_id, user) | |
| found = await worksheet_of(class_id, wid) | |
| assignments = getattr(app.state, "assignments", None) | |
| try: | |
| used = {w for r in assignments.for_classes([class_id]) for w in worksheet_ids(r.get("items"))} if assignments else set() | |
| except Exception as exc: # AssignmentsUnavailable: cannot tell it is unused | |
| raise HTTPException(503, "assignments_unavailable") from exc | |
| if found["id"] in used: | |
| raise HTTPException(409, "worksheet_in_use") | |
| await call(drop, store(), [found]) | |
| return reply({"ok": True}) | |
| async def submission_page(class_id: int, wid: str, sid: str, n: int, user=Depends(signed_in)): | |
| class_row(class_id, user) | |
| found = await worksheet_of(class_id, wid) | |
| sub = await call(store().submission, uuid_or_404(sid, "submission")) | |
| if not sub or sub.get("worksheet_id") != found["id"]: | |
| raise HTTPException(404, "submission not found") | |
| keys = sub.get("page_keys") or [] | |
| return image(await call(store().read, keys[page_index(n, len(keys))])) | |
| async def check_submission(class_id: int, wid: str, sid: str, body: dict, user=Depends(signed_in)): | |
| row = class_row(class_id, user) | |
| found = await worksheet_of(class_id, wid) | |
| score, comment = body.get("score"), body.get("comment", "") | |
| if score is not None and (type(score) is not int or not 0 <= score <= 100): | |
| raise HTTPException(400, "the score is a whole number from 0 to 100") | |
| if not isinstance(comment, str) or len(comment.strip()) > MAX_COMMENT: | |
| raise HTTPException(400, f"the comment is up to {MAX_COMMENT} characters") | |
| sub = await call(store().submission, uuid_or_404(sid, "submission")) | |
| if not sub or sub.get("worksheet_id") != found["id"]: | |
| raise HTTPException(404, "submission not found") | |
| saved = await call(store().check, sub["id"], { | |
| "score": score, "comment": comment.strip(), "checked_by_email": str(user.get("email", "")).lower(), | |
| "checked_at": sub.get("checked_at") or datetime.now(timezone.utc).isoformat(), "state": "checked"}) | |
| if not saved: | |
| raise HTTPException(404, "submission not found") | |
| record(user, "worksheet_checked", f"{row.get('name', '')}: {found['title']}") | |
| return reply(submission_public(saved, teacher=True)) | |
| async def return_submission(class_id: int, wid: str, sid: str, body: dict, user=Depends(signed_in)): | |
| """Sends the current submission back to the student for a fix, with a comment and maybe a new due date. It is | |
| no longer waiting for a check; the student's next hand-in is the next version.""" | |
| row = class_row(class_id, user) | |
| found = await worksheet_of(class_id, wid) | |
| comment = body.get("comment") | |
| if not isinstance(comment, str) or not comment.strip() or len(comment.strip()) > MAX_COMMENT: | |
| raise HTTPException(400, f"the comment is required (up to {MAX_COMMENT} characters)") | |
| due = body.get("due_on") | |
| if due is not None: | |
| try: | |
| due = date.fromisoformat(str(due)).isoformat() | |
| except ValueError as exc: | |
| raise HTTPException(400, "the due date must be a date (YYYY-MM-DD)") from exc | |
| sub = await call(store().submission, uuid_or_404(sid, "submission")) | |
| if not sub or sub.get("worksheet_id") != found["id"]: | |
| raise HTTPException(404, "submission not found") | |
| if store().legacy: | |
| raise HTTPException(503, "returns_unavailable") | |
| latest = current(await call(store().submissions, [found["id"]], sub["student_id"])) | |
| if not latest or latest[0]["id"] != sub["id"]: | |
| raise HTTPException(409, "not_the_current_version") | |
| saved = await call(store().check, sub["id"], { | |
| "state": "returned", "returned_at": datetime.now(timezone.utc).isoformat(), | |
| "return_comment": comment.strip(), "return_due_on": due, | |
| "checked_by_email": str(user.get("email", "")).lower()}) | |
| if not saved: | |
| raise HTTPException(404, "submission not found") | |
| record(user, "worksheet_returned", f"{row.get('name', '')}: {found['title']}") | |
| return reply(submission_public(saved, teacher=True)) | |
| def ai_suggest(sub: dict, found: dict | None = None) -> dict: | |
| """The AI's check of a submission against its worksheet, kept on the submission as a suggestion for the | |
| teacher's review form (nothing reaches the student until the teacher saves). PhotoUnavailable when the AI | |
| could not answer. Used for one submission (below) and for a batch (app/ai_batches.py).""" | |
| if open_ended_locked(): | |
| raise PhotoUnavailable("讛讘讚讬拽讛 讛讗讜讟讜诪讟讬转 住讙讜专讛 讻专讙注.", "open_ended_locked") | |
| key = grading_key() | |
| grader = getattr(app.state, "homework_grader", None) | |
| if not key and grader is None: | |
| raise PhotoUnavailable("讛讘讚讬拽讛 讛讗讜讟讜诪讟讬转 讗讬谞讛 讝诪讬谞讛.", "missing_key") | |
| found = found or store().get(sub["worksheet_id"]) | |
| sheet = [store().read(k) for k in found.get("page_keys") or []] | |
| solution = [store().read(k) for k in sub.get("page_keys") or []] | |
| result = (grader or HomeworkGrader(key)).grade(found["title"], sheet, solution) | |
| ai_usage.record(app.state.auth, None, "grading", result.pop("usage", None)) | |
| try: | |
| store().check(sub["id"], {"ai_score": result["score"], "ai_comment": result["comment"][:MAX_COMMENT], | |
| "ai_readable": result["readable"], "ai_checked_at": datetime.now(timezone.utc).isoformat()}) | |
| except WorksheetsUnavailable: | |
| log.warning("an AI suggestion was not kept on its submission") | |
| return result | |
| app.state.worksheet_ai_suggest = ai_suggest | |
| async def ai_check(class_id: int, wid: str, sid: str, user=Depends(signed_in)): | |
| """The AI's check of a submission, as a suggestion (score and comment) for the teacher, kept on the submission. | |
| One check from the class's daily budget (app/ai_batches.py), or, without one, one of the teacher's daily AI | |
| requests (app/teacher_ai.py); given back when the AI could not answer or read the photo.""" | |
| row = class_row(class_id, user) | |
| found = await worksheet_of(class_id, wid) | |
| sub = await call(store().submission, uuid_or_404(sid, "submission")) | |
| if not sub or sub.get("worksheet_id") != found["id"]: | |
| raise HTTPException(404, "submission not found") | |
| if open_ended_locked(): | |
| raise HTTPException(403, "open_ended_locked") | |
| if not grading_key() and getattr(app.state, "homework_grader", None) is None: | |
| raise HTTPException(503, "grading_unavailable") | |
| cls = None | |
| if hasattr(app.state, "class_take_one"): | |
| try: | |
| cls = await run_in_threadpool(app.state.class_take_one, sub.get("student_email", "")) | |
| except ScanError as exc: | |
| raise HTTPException(exc.status, exc.code) from exc | |
| quota = None | |
| if cls is None: | |
| try: | |
| quota = app.state.teacher_ai.take(user) | |
| except LimitReached as exc: | |
| raise HTTPException(429, "teacher_ai_limit") from exc | |
| def give_back(): | |
| if cls is not None: | |
| app.state.class_give_one(cls) | |
| else: | |
| app.state.teacher_ai.give_back(quota) | |
| try: | |
| result = await run_in_threadpool(ai_suggest, sub, found) | |
| except PhotoUnavailable as exc: | |
| give_back() | |
| raise HTTPException(503, f"ai_check_failed|{exc.reason or 'provider_error'}") from exc | |
| except WorksheetsUnavailable as exc: | |
| give_back() | |
| raise HTTPException(503, "worksheets_unavailable") from exc | |
| except Exception: | |
| give_back() | |
| raise | |
| if not result["readable"]: | |
| give_back() # a photo the AI could not read is not counted | |
| record(user, "worksheet_ai_checked", f"{row.get('name', '')}: {found['title']}") | |
| return reply({"score": result["score"], "comment": result["comment"], "readable": result["readable"], | |
| "left": app.state.teacher_ai.left(user), "class_budget": cls is not None}) | |
| # ---- the class: the worksheet itself | |
| async def worksheet_page(wid: str, n: int, user=Depends(signed_in)): | |
| found, _ = await readable(user, wid) | |
| keys = found.get("page_keys") or [] | |
| return image(await call(store().read, keys[page_index(n, len(keys))])) | |
| async def worksheet_original(wid: str, user=Depends(signed_in)): | |
| found, _ = await readable(user, wid) | |
| if not found.get("original_key"): | |
| raise HTTPException(404, "this worksheet has no PDF") | |
| return image(await call(store().read, found["original_key"]), "application/pdf", f"{found['title']}.pdf") | |
| # ---- the student: their own submission | |
| async def member_worksheet(user: dict, wid: str) -> tuple[dict, dict]: | |
| """A worksheet of an assignment of one of the student's classes; else 404.""" | |
| found, row = await readable(user, wid) | |
| if str(user.get("email", "")).lower() not in row.get("emails", ()): | |
| raise HTTPException(404, "worksheet not found") | |
| assignments = getattr(app.state, "assignments", None) | |
| try: | |
| used = {w for r in assignments.for_classes([row["id"]]) for w in worksheet_ids(r.get("items"))} if assignments else set() | |
| except Exception as exc: | |
| raise HTTPException(503, "assignments_unavailable") from exc | |
| if found["id"] not in used: | |
| raise HTTPException(404, "worksheet not found") | |
| return found, row | |
| app.state.member_worksheet = member_worksheet # the answer routes' worksheet photos (app/answer_routes.py) | |
| async def own_submission(user: dict, wid: str) -> dict | None: | |
| """The student's current submission (highest version), with the earlier ones under `earlier`.""" | |
| rows = current(await call(store().submissions, [wid], user["id"])) | |
| return rows[0] if rows else None | |
| async def hand_in(wid: str, files: list[UploadFile] = File(...), note: str = Form(""), user=Depends(signed_in)): | |
| found, row = await member_worksheet(user, wid) | |
| note = " ".join(note.split()) if note else "" | |
| if len(note) > MAX_NOTE: | |
| raise HTTPException(400, "note_too_long") | |
| old = await own_submission(user, found["id"]) | |
| state = (old or {}).get("state") or ("checked" if (old or {}).get("checked_at") else "submitted") | |
| if old and state == "checked": | |
| raise HTTPException(409, "already_checked") | |
| pages = await clean_photos(files) | |
| base = f"s/{found['id']}/{user['id']}/{uuid.uuid4().hex}" | |
| keys = [f"{base}/{n + 1}.jpg" for n in range(len(pages))] | |
| written = [] | |
| try: | |
| for key, data in zip(keys, pages): | |
| await call(store().put, key, data) | |
| written.append(key) | |
| fields = {"page_keys": keys, "submitted_at": datetime.now(timezone.utc).isoformat(), "note": note} | |
| if old and state == "submitted": # not checked yet: the new photos replace this version | |
| saved = await call(store().check, old["id"], fields) | |
| else: # the first hand-in, or the next version after a return | |
| saved = await call(store().add_submission, { | |
| **fields, "worksheet_id": found["id"], "student_id": user["id"], | |
| "student_email": str(user.get("email", "")).lower(), | |
| "version": (old.get("version") or 1) + 1 if old else 1, "state": "submitted"}) | |
| except HTTPException: | |
| try: | |
| await run_in_threadpool(store().delete, written) | |
| except WorksheetsUnavailable: | |
| pass | |
| raise | |
| if old and state == "submitted": # a returned version keeps its pages: the student and teacher look back at it | |
| try: | |
| await run_in_threadpool(store().delete, [k for k in old.get("page_keys") or [] if k not in keys]) | |
| except WorksheetsUnavailable: | |
| log.warning("a replaced submission's images stayed in storage") | |
| record(user, "worksheet_submitted", f"{row.get('name', '')}: {found['title']}") | |
| mine = await own_submission(user, found["id"]) | |
| return reply(submission_public(mine or saved)) | |
| async def own_page(wid: str, n: int, version: int | None = None, user=Depends(signed_in)): | |
| found, _ = await readable(user, wid) | |
| sub = await own_submission(user, found["id"]) | |
| if sub and version is not None and version != (sub.get("version") or 1): | |
| sub = next((e for e in sub.get("earlier") or [] if (e.get("version") or 1) == version), None) | |
| if not sub: | |
| raise HTTPException(404, "submission not found") | |
| keys = sub.get("page_keys") or [] | |
| return image(await call(store().read, keys[page_index(n, len(keys))])) | |