Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/developers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<canvas course id>/`. 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/<canvas course id>/`. 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 <canvas id> <key> "<name>"`, run from the repository root against that database.

Expand Down
168 changes: 137 additions & 31 deletions server/state.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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/<canvas course id>/.
bp = Blueprint("offering", __name__, url_prefix=OFFERING_URL_PREFIX)
Expand Down Expand Up @@ -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()]
),
Expand Down Expand Up @@ -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):
Expand Down
71 changes: 55 additions & 16 deletions src/AdminPage.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -237,13 +246,14 @@ export default function AdminPage(): React.ReactNode {
<h1 className="h2">Admin Settings</h1>
<Row>
<Col>
<Tabs defaultActiveKey="general">
<Tabs defaultActiveKey="general" className="mb-3">
<Tab eventKey="general" title="General">
<div className="mb-3">
Welcome message:
<InputGroup>
<FormControl
as="textarea"
rows={4}
placeholder="Write a short welcome message for students"
value={message}
onChange={(e) => setMessage(e.target.value)}
Expand Down Expand Up @@ -289,37 +299,63 @@ export default function AdminPage(): React.ReactNode {
</Alert>
) : null}
</div>

{/* Line 1: Import Buttons */}
</Tab>
<Tab eventKey="roster" title="Roster Management">
<p className="mb-1">At the start of the semester, start by:</p>
<ol>
<li>syncing the bCourses student roster,</li>
<li>importing sections,</li>
<li>importing section assignments.</li>
</ol>
<p>
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).
</p>
<p>
<Button variant="secondary" onClick={() => setShowSyncBcoursesModal(true)}>
Sync bCourses Students
</Button>{" "}
<Button variant="secondary" onClick={() => setShowImportSectionsModal(true)}>
Import Sections
</Button>{" "}
<Button variant="secondary" onClick={() => setShowImportEnrollmentModal(true)}>
Import Section Assignments
</Button>{" "}
<Button variant="secondary" onClick={() => setShowSyncBcoursesModal(true)}>
Sync bCourses
</Button>
</p>

{/* Line 2: Export Buttons */}
<StudentSearch />

<p>
<Button variant="secondary" onClick={() => exportRosters({})}>
Export Rosters
Export Section Assignments
</Button>{" "}
<Button variant="secondary" onClick={() => exportAttendance({})}>
Export Full Attendances
</Button>{" "}
<Button variant="secondary" onClick={() => exportStudents({})}>
Export Students
</Button>
</p>
<ul className="text-muted small">
<li>
&ldquo;Export Section Assignments&rdquo; (CSV) has one row per student per section, in the format
&ldquo;Import Section Assignments&rdquo; reads, so you can export, edit the spreadsheet, and import
it back. Students with no section assignments aren&rsquo;t in it.
</li>
<li>
&ldquo;Export Full Attendances&rdquo; (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.
</li>
<li>
&ldquo;Export Students&rdquo; (CSV) has one row per student in the offering, with their section of
each type, or &ldquo;Floating&rdquo; if they have no lab or discussion section. Run &ldquo;Sync
bCourses Students&rdquo; first so it includes students who&rsquo;ve just joined and leaves out
those who&rsquo;ve dropped.
</li>
</ul>

{/* Line 3: Description Text */}
<p>
The following will obtain emails of students who have at least one unexcused absence
or 3 excused absences in their enrolled tutoring section.
</p>

{/* Line 4: Copy Students to Drop */}
<p>
<Button variant="secondary" onClick={() => fetchToDrop()}>
Copy Students To Drop (Tutoring)
Expand All @@ -334,8 +370,11 @@ export default function AdminPage(): React.ReactNode {
onClose={() => setRemovingTutoring(false)}
/>
</p>
<p className="text-muted small">
&ldquo;Copy Students To Drop (Tutoring)&rdquo; copies the emails of students who have at least one
unexcused absence or 3 excused absences in their tutoring section.
</p>

{/* Line 5: Admin Management Actions */}
{currentUser?.isAdmin && (
<p>
<Button variant="danger" onClick={() => setRemoving(true)}>
Expand Down
2 changes: 1 addition & 1 deletion src/ApiKeysTab.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ export default function ApiKeysTab() {
};

return (
<div className="mt-3">
<div>
<p>
An API key lets a script call this course&rsquo;s Sections API as you, or as anyone in this
course. It works only in this course, only while you&rsquo;re an admin here in bCourses, and
Expand Down
Loading
Loading