diff --git a/docs/developers.md b/docs/developers.md index 3f5841a..a304028 100644 --- a/docs/developers.md +++ b/docs/developers.md @@ -21,7 +21,7 @@ The commands below are for macOS and Linux. On Windows, use [WSL](https://learn. ## Authentication -One deployment serves every bCourses course, with the same routes as seating. Users log in through Canvas OAuth (`/login/`, which returns to `/authorized/`), and `/offerings` lists their courses. Each course offering lives under `/offerings//`. Roles come from each Canvas enrollment at sign-in: Teachers and TAs are staff, and Teachers and Lead TAs are admins. Members of the `ADMIN_OVERRIDE_CANVAS_COURSE_ID` course are staff and admin everywhere. Someone added to a course after signing in needs to sign out and in again. Students are also added when an admin syncs the course with bCourses ("Sync bCourses" on the Admin page), which adds everyone on the course's bCourses roster, including students who haven't accepted their invitation, and removes students no longer on it from the course and its sections, keeping their attendance records. +One deployment serves every bCourses course, with the same routes as seating. Users log in through Canvas OAuth (`/login/`, which returns to `/authorized/`), and `/offerings` lists their courses. Each course offering lives under `/offerings//`. Roles come from each Canvas enrollment at sign-in: Teachers and TAs are staff, and Teachers and Lead TAs are admins. Members of the `ADMIN_OVERRIDE_CANVAS_COURSE_ID` course are staff and admin everywhere. Someone added to a course after signing in needs to sign out and in again. Students are also added when an admin syncs the course with bCourses ("Sync bCourses Students" on the Admin page's Roster Management tab), which adds everyone on the course's bCourses roster, including students who haven't accepted their invitation, and removes students no longer on it from the course and its sections, keeping their attendance records. Course staff set up Sections for a course with "Import courses from Canvas" (`/offerings/new`). Offerings moved from the monorepo store their data under an old key (`cs61a`, `data8`, ...) and have been already linked to their Canvas courses. If one ever needs relinking, run `flask --app server.main link-offering ""`, run from the repository root against that database. diff --git a/server/state.py b/server/state.py index 73e3d0e..ef5268c 100644 --- a/server/state.py +++ b/server/state.py @@ -10,7 +10,7 @@ from urllib.parse import urlparse from typing import List, Optional, Union from zoneinfo import ZoneInfo -from server.import_sheet import parse_section_times +from server.import_sheet import DAYS, parse_section_times import flask from flask import Blueprint, abort, g, jsonify, render_template, request, current_app @@ -159,6 +159,68 @@ def add_student_helper(student: User, target_section: Section): # SQLAlchemy 2.0 no longer cascades new objects into the session through backrefs. db.session.add(student) + +SECTION_TYPE_ORDER = {"Lab": 0, "Discussion": 1, "Tutoring": 2} +# Every student is expected to be in one of each of these; tutoring is opt-in. +FLOATING_TYPES = {"Lab", "Discussion"} +FLOATING = "Floating" +STUDENT_SEARCH_LIMIT = 25 + + +def section_day_and_start(section: Section) -> tuple[str, str]: + """The section's weekday ("M", "Th") and start time ("08:00a") in Berkeley.""" + if not isinstance(section.start_time, (int, float)): + return "", str(section.start_time or "") + try: + dt = datetime.fromtimestamp(section.start_time, tz=ZoneInfo("America/Los_Angeles")) + except (OverflowError, OSError, ValueError): + return "", str(section.start_time) + day = DAYS[dt.weekday()] if dt.weekday() < len(DAYS) else "" + return day, dt.strftime("%I:%M%p").lower().replace("m", "") + + +def describe_section(section: Section) -> str: + """e.g. "Alice Smith, Th 08:00a, Soda 271" """ + day, start = section_day_and_start(section) + parts = [section.staff.name if section.staff else "No TA", f"{day} {start}".strip(), section.location or ""] + return ", ".join(part for part in parts if part) + + +def csv_safe(value) -> str: + """The value as a CSV cell that a spreadsheet won't run as a formula: one + that starts with =, +, -, @, a tab or a carriage return gets a leading + apostrophe (OWASP's advice for CSV injection), so it opens as text.""" + text = "" if value is None else str(value) + if text[:1] in ("=", "+", "-", "@", "\t", "\r"): + return "'" + text + return text + + +def term_slug(start_at: str | None) -> str: + """e.g. "fa26" for a term starting 2026-08-19: Berkeley's spring starts in + January, summer in May or June, and fall in August. "" if unknown.""" + match = re.match(r"(\d{2})(\d{2})-(\d{2})", start_at or "") + if match is None: + return "" + month = int(match.group(3)) + season = "sp" if month <= 4 else "su" if month <= 7 else "fa" + return season + match.group(2) + + +def export_file_name(name: str) -> str: + """e.g. "cs61a-fa26-rosters.csv" for CS 61A in Fall 2026: the course code, + lowercased with anything but letters and digits dropped, then the term, so + exports from different courses and semesters don't overwrite each other in + a downloads folder.""" + course = re.sub(r"[^a-z0-9]", "", get_course_name().lower()) + prefix = "-".join(part for part in (course, term_slug(g.offering.start_at)) if part) + return f"{prefix}-{name}" if prefix else name + + +def write_csv_row(writer, row) -> None: + writer.writerow([csv_safe(cell) for cell in row]) + + def create_state_client(app: flask.Flask): # Every offering page and API lives under /offerings//. bp = Blueprint("offering", __name__, url_prefix=OFFERING_URL_PREFIX) @@ -929,7 +991,7 @@ def export_helper(): return { **refresh_state(), "custom": { - "fileName": "attendances.json", + "fileName": export_file_name("attendances.json"), "attendances": stringify( [{"type": k, "attendances": v} for k, v in attendances.items()] ), @@ -1002,42 +1064,86 @@ def export_rosters(): for section in Section.query.filter_by(course=get_course()).all(): staff_email = section.staff.email if section.staff else "" - location = section.location or "" - day = "" - start = "" - - DAY_MAP = { - 0: "M", - 1: "T", - 2: "W", - 3: "Th", - 4: "F", - } - - try: - - if isinstance(section.start_time, (int, float)): - # Interpret stored UNIX timestamps in America/LA timezones - tz = ZoneInfo("America/Los_Angeles") - dt = datetime.fromtimestamp(section.start_time, tz=tz) - day = DAY_MAP.get(dt.weekday(), "") # e.g. "M", "Tu" - start = dt.strftime("%I:%M%p").lower().replace('m', '') # e.g. "08:00a" - else: - # fallback: output as-is (just as a string) - start = str(section.start_time or "") - except Exception: - day = "" - start = str(section.start_time or "") - + day, start = section_day_and_start(section) for student in section.students: - writer.writerow([student.email, staff_email, location, day, start, section.name or ""]) + write_csv_row(writer, [student.email, staff_email, section.location or "", day, start, + section.name or ""]) csv_text = out.getvalue() return { **refresh_state(), - "custom": {"fileName": "rosters.csv", "rosters": csv_text}, + "custom": {"fileName": export_file_name("rosters.csv"), "rosters": csv_text}, } + @api + @admin_required + def export_students(): + """Every student in the offering, with their section of each type, or + "Floating" for a lab or discussion they aren't in.""" + course = get_course() + sections = Section.query.filter_by(course=course).all() + types = sorted({section.name for section in sections if section.name}, + key=lambda name: (SECTION_TYPE_ORDER.get(name, len(SECTION_TYPE_ORDER)), name)) + students = ( + User.query.filter(set_contains(User.student_offerings, course)) + .options(joinedload(User.sections).joinedload(Section.staff)) + .all() + ) + + out = StringIO() + writer = csv.writer(out) + writer.writerow(["Name", "Email", *types]) + for student in sorted(students, key=lambda student: (student.name.lower(), student.email.lower())): + by_type = {} + for section in student.sections_in(course): + by_type.setdefault(section.name, []).append(describe_section(section)) + write_csv_row(writer, [ + student.name, + student.email, + *("; ".join(by_type[name]) if name in by_type + else FLOATING if name in FLOATING_TYPES else "" + for name in types), + ]) + + return {"custom": {"fileName": export_file_name("students.csv"), "students": out.getvalue()}} + + @api + @staff_required + def search_students(query: str): + """Students in the offering whose name or email contains `query`, with + their sections here.""" + query = query.strip().lower() + if not query: + return [] + course = get_course() + students = ( + User.query.filter(set_contains(User.student_offerings, course)) + .filter(func.lower(User.name).contains(query, autoescape=True) + | func.lower(User.email).contains(query, autoescape=True)) + .options(joinedload(User.sections).joinedload(Section.staff)) + .order_by(User.name, User.email) + .limit(STUDENT_SEARCH_LIMIT) + .all() + ) + return [ + { + **student.identity_json, + "sections": [ + { + "id": str(section.id), + "name": section.name, + "startTime": section.start_time, + "endTime": section.end_time, + "location": section.location, + "staff": section.staff.identity_json if section.staff is not None else None, + } + for section in sorted(student.sections_in(course), + key=lambda section: SECTION_TYPE_ORDER.get(section.name, 99)) + ], + } + for student in students + ] + @api @staff_required def fetch_user(user_id: str): diff --git a/src/AdminPage.tsx b/src/AdminPage.tsx index 0997377..a234295 100644 --- a/src/AdminPage.tsx +++ b/src/AdminPage.tsx @@ -20,8 +20,10 @@ import type { CourseConfig } from "./models"; import StateContext from "./StateContext"; import ToggleSwitch from "./ToggleSwitch"; import useAPI from "./useStateAPI"; +import useBareAPI from "./useAPI"; import AddStudentModal from "./AddStudentModal"; import ResetSectionsModal from "./ResetSectionsModal"; +import StudentSearch from "./StudentSearch"; import SyncBcoursesModal from "./SyncBcoursesModal"; import MessageContext from "./MessageContext"; @@ -161,6 +163,13 @@ export default function AdminPage(): React.ReactNode { } downloadText(rosters, fileName); }); + // Doesn't change the state, so no need to refresh it. + const exportStudents = useBareAPI( + "export_students", + useCallback(({ custom: { students, fileName } }: { custom: { students: string; fileName: string } }) => { + downloadText(students, fileName); + }, []) + ); const fetchToDrop = useAPI("fetch_to_drop", ({ custom: { students } }) => { if (students == null) { return; @@ -237,13 +246,14 @@ export default function AdminPage(): React.ReactNode {

Admin Settings

- +
Welcome message: setMessage(e.target.value)} @@ -289,37 +299,63 @@ export default function AdminPage(): React.ReactNode { ) : null}
- - {/* Line 1: Import Buttons */} +
+ +

At the start of the semester, start by:

+
    +
  1. syncing the bCourses student roster,
  2. +
  3. importing sections,
  4. +
  5. importing section assignments.
  6. +

+ It is safe to run any of these steps again. For example, if you want to drop students from sections + who have dropped your course, re-run the bCourses sync. You can also add more sections after your + initial setup, and assign students in multiple rounds (like if they added the course late). +

+

+ {" "} {" "} {" "} -

- {/* Line 2: Export Buttons */} + +

{" "} {" "} +

+
    +
  • + “Export Section Assignments” (CSV) has one row per student per section, in the format + “Import Section Assignments” reads, so you can export, edit the spreadsheet, and import + it back. Students with no section assignments aren’t in it. +
  • +
  • + “Export Full Attendances” (JSON) has every attendance record, by section type and + student. All students who have had attendance recorded are included in this export, even if the + student has been removed from a section or this course offering. +
  • +
  • + “Export Students” (CSV) has one row per student in the offering, with their section of + each type, or “Floating” if they have no lab or discussion section. Run “Sync + bCourses Students” first so it includes students who’ve just joined and leaves out + those who’ve dropped. +
  • +
- {/* Line 3: Description Text */} -

- The following will obtain emails of students who have at least one unexcused absence - or 3 excused absences in their enrolled tutoring section. -

- - {/* Line 4: Copy Students to Drop */}

+ + + {results != null && + (results.students.length === 0 ? ( +

+ No students match “{results.query}”. +

+ ) : ( + + + + + + + + + + {results.students.map((student) => { + const floating = expectedTypes.filter( + (type) => + !student.sections.some((section) => section.name === type), + ); + return ( + + + + + + ); + })} + +
StudentEmailSections
+ {student.name} + + {student.email} + {student.sections.map((section) => ( +
+ +
+ ))} + {floating.map((type) => ( +
{type}: Floating
+ ))} +
+ ))} + + ); +} diff --git a/src/SyncBcoursesModal.tsx b/src/SyncBcoursesModal.tsx index 9b5fc17..24e1700 100644 --- a/src/SyncBcoursesModal.tsx +++ b/src/SyncBcoursesModal.tsx @@ -79,7 +79,7 @@ export default function SyncBcoursesModal({ show, onClose }: Props) { return ( - Sync bCourses + Sync bCourses Students

diff --git a/src/models.tsx b/src/models.tsx index 8cf30e2..9d193db 100644 --- a/src/models.tsx +++ b/src/models.tsx @@ -127,7 +127,7 @@ export function getEnrollmentCount(section: Section): number { return section.enrollmentCount ?? section.students.length; } -export function nextSessionStartTime(section: Section, dayOffset: number = 0) { +export function nextSessionStartTime(section: Pick, dayOffset: number = 0) { const time = moment.unix(section.startTime).tz(TZ); while (time.isBefore(moment().add(dayOffset, "days"))) { time.add(7, "days"); @@ -145,7 +145,7 @@ export function sessionStartTimes(section: Section) { return out; } -export function sectionInterval(section: Section): React.ReactElement { +export function sectionInterval(section: Pick): React.ReactElement { const isPT = moment.tz.guess() === TZ; const useLocalString = document.cookie .split("; ") diff --git a/tests/e2e/test_admin.py b/tests/e2e/test_admin.py index 09c3b4d..8ffa97f 100644 --- a/tests/e2e/test_admin.py +++ b/tests/e2e/test_admin.py @@ -57,7 +57,8 @@ def test_admin_syncs_students_with_bcourses(site, database): session.commit() site.visit(f"{OFFERING}/admin", TEACHER) - site.click("Sync bCourses") + site.click("Roster Management", site.find('//*[@role="tablist"]')) + site.click("Sync bCourses Students") dialog = site.find('//*[@role="dialog"]') # The fake Canvas lists three students in the course; Jimmy Xu is already here. site.wait(lambda: "This will add 2 and remove 1 students." in dialog.text) @@ -120,3 +121,23 @@ def test_admin_makes_uses_rotates_and_revokes_an_api_key(site): site.wait(lambda: site.has_text("No one has an API key for this course.")) status, body = call_api(site, new_key, "refresh_state") assert status == 401 + + +def test_admin_finds_a_students_sections(site): + site.visit(f"{OFFERING}/admin", TEACHER) + site.click("Roster Management", site.find('//*[@role="tablist"]')) + field = site.find('//input[@id="student-search"]') + field.send_keys("jimmy") + site.click("Search", field.find_element(By.XPATH, "..")) + site.wait(lambda: site.has_text("jimmyxu@example.com")) + row = site.find('//tr[contains(., "jimmyxu@example.com")]') + # In Yu Long's lab, and in no discussion yet. + assert "Lab: Yu Long" in row.text + assert "Soda 271" in row.text + assert "Discussion: Floating" in row.text + assert "Tutoring" not in row.text + + field.clear() + field.send_keys("nobody") + site.click("Search", field.find_element(By.XPATH, "..")) + site.wait(lambda: site.has_text("No students match “nobody”.")) diff --git a/tests/unit/test_student_export_search.py b/tests/unit/test_student_export_search.py new file mode 100644 index 0000000..099fe2e --- /dev/null +++ b/tests/unit/test_student_export_search.py @@ -0,0 +1,151 @@ +"""Exporting every student with their sections, and finding a student's sections.""" + +import csv +import unittest +from io import StringIO + +from server.models import Section, User, db +from server.state import csv_safe, term_slug +from tests.unit.support import DATA8, CourseTestCase, canvas_course + +# 2026-08-20 15:00 UTC is Thursday 08:00 in Berkeley. +THURSDAY_8AM = 1787238000 + + +def discussion(course, location="Disc Room"): + return Section(course=course, name="Discussion", location=location, description="", + capacity=30, can_self_enroll=True, start_time=THURSDAY_8AM, end_time=THURSDAY_8AM + 3600) + + +class StudentExportTests(CourseTestCase): + def setUp(self): + super().setUp() + self.make_staff_admin() + + def export(self): + body = self.api("export_students").get_json() + self.assertTrue(body["success"], body) + custom = body["data"]["custom"] + self.assertEqual(custom["fileName"], "cs61a-students.csv") + return list(csv.reader(StringIO(custom["students"]))) + + def test_lists_each_students_sections_or_floating(self): + known = db.session.get(User, self.known_id) + staff = db.session.get(User, self.staff_id) + disc = discussion("cs61a") + disc.staff = staff + floater = User(email="floater@test", name="Floater") + floater.set_role("cs61a", is_staff=False) + known.sections.extend([db.session.get(Section, self.section_id), disc]) + db.session.add_all([disc, floater]) + db.session.commit() + + rows = self.export() + self.assertEqual(rows[0], ["Name", "Email", "Lab", "Discussion"]) + self.assertEqual(rows[1:], [ + ["Floater", "floater@test", "Floating", "Floating"], + ["Known", "known@test", "Staff, W 04:00p, Room", "Staff, Th 08:00a, Disc Room"], + ]) + + def test_leaves_staff_and_other_offerings_out(self): + self.enroll_known_in_data8() + rows = self.export() + # Only known is a cs61a student; data8's lab isn't a column of its own. + self.assertEqual(rows, [["Name", "Email", "Lab"], ["Known", "known@test", "Floating"]]) + + def test_tutoring_isnt_floating(self): + tutoring = Section(course="cs61a", name="Tutoring", location="T", description="", + capacity=5, can_self_enroll=True, start_time=0, end_time=3600) + db.session.add(tutoring) + db.session.commit() + self.assertEqual(self.export()[1], ["Known", "known@test", "Floating", ""]) + + def test_neutralizes_formulas(self): + known = db.session.get(User, self.known_id) + known.name = "=HYPERLINK(\"http://evil\",\"x\")" + db.session.commit() + self.assertEqual(self.export()[1][0], "'=HYPERLINK(\"http://evil\",\"x\")") + + +class StudentExportPermissionTests(CourseTestCase): + def test_admins_only(self): + body = self.api("export_students").get_json() # signed in as staff, not admin + self.assertFalse(body["success"]) + self.assertIn("Only course admins", body["message"]) + + +class RosterExportFormulaTests(CourseTestCase): + def test_roster_export_neutralizes_formulas(self): + self.make_staff_admin() + section = db.session.get(Section, self.section_id) + section.location = "@SUM(A1)" + section.students.append(db.session.get(User, self.known_id)) + db.session.commit() + custom = self.api("export_rosters").get_json()["data"]["custom"] + self.assertEqual(custom["fileName"], "cs61a-rosters.csv") + rosters = custom["rosters"] + self.assertEqual(list(csv.reader(StringIO(rosters)))[1][2], "'@SUM(A1)") + + +class ExportFileNameTests(CourseTestCase): + def test_named_for_the_course_code_and_term(self): + # DATA 8's offering has a Canvas code and a term starting 2026-08-19; + # CS 61A's has only a name, so its files have no term. + self.make_staff_admin() + known = self.enroll_known_in_data8() + known.canvas_courses = {**known.canvas_courses, str(DATA8): canvas_course("DATA 8", admin=True, staff=True)} + known.set_role(str(DATA8), is_staff=True, is_admin=True) + db.session.commit() + self.sign_in(known) + body = self.api("export_attendance", canvas_course_id=DATA8).get_json() + self.assertEqual(body["data"]["custom"]["fileName"], "data8-fa26-attendances.json") + + +class TermSlugTests(unittest.TestCase): + def test_term_slug(self): + for start_at, expected in [("2026-01-20T08:00:00Z", "sp26"), ("2026-05-26T07:00:00Z", "su26"), + ("2026-06-22", "su26"), ("2026-08-19T07:00:00Z", "fa26"), + (None, ""), ("", ""), ("soon", "")]: + self.assertEqual(term_slug(start_at), expected, start_at) + + +class CsvSafeTests(CourseTestCase): + def test_csv_safe(self): + for value, expected in [("=1+1", "'=1+1"), ("+1", "'+1"), ("-1", "'-1"), ("@x", "'@x"), + ("\tx", "'\tx"), ("\rx", "'\rx"), ("a=b", "a=b"), ("", ""), (None, "")]: + self.assertEqual(csv_safe(value), expected) + + +class StudentSearchTests(CourseTestCase): + def search(self, query): + body = self.api("search_students", query=query).get_json() + self.assertTrue(body["success"], body) + return body["data"] + + def test_finds_by_name_or_email_with_sections(self): + known = db.session.get(User, self.known_id) + known.sections.append(db.session.get(Section, self.section_id)) + db.session.commit() + + for query in ("KNO", "known@", " now "): + results = self.search(query) + self.assertEqual([r["email"] for r in results], ["known@test"], query) + [section] = results[0]["sections"] + self.assertEqual((section["id"], section["name"], section["location"], section["staff"]["name"]), + (str(self.section_id), "Lab", "Room", "Staff")) + + def test_only_this_offerings_students_and_sections(self): + self.enroll_known_in_data8() + self.assertEqual(self.search("staff"), []) # staff aren't students + self.assertEqual(self.search("known")[0]["sections"], []) # their data8 lab isn't here + + def test_wildcards_are_literal(self): + self.assertEqual(self.search("%"), []) + self.assertEqual(self.search("_"), []) + self.assertEqual(self.search(""), []) + + def test_students_cant_search(self): + self.sign_in(db.session.get(User, self.known_id)) + body = self.api("search_students", query="known").get_json() + self.assertFalse(body["success"]) + self.assertIn("Only staff", body["message"])