Class Models

Overview

Classes in ESP are represented by two primary models:

ClassSubject: The class itself with title, description, and teachers
ClassSection: A specific meeting time/instance of a class

A single ClassSubject can have multiple ClassSections for different times or parallel offerings. Source: esp/esp/program/models/class_.py

ClassSubject Model

Represents a class/course offered in a program.

Core Fields

parent_program

ForeignKey

required

Program this class belongs to

Links to: Program
Required field

Size and Capacity

class_size_min

IntegerField

Minimum number of students needed for class to run

class_size_max

IntegerField

Maximum number of students allowed in class

class_size_optimal

IntegerField

Ideal class size as specified by teacher

allowable_class_size_ranges

ManyToManyField

Acceptable size ranges for this class

Links to: ClassSizeRange

Teacher Fields

teachers

ManyToManyField

Teachers/instructors for this class

Links to: ESPUser
Can have multiple co-teachers

allow_lateness

BooleanField

Whether students can join after class starts

Default: False
If True, allows 20-minute grace period

Content Fields

prereqs

TextField

Prerequisites for taking this class

Text description of required background

grade_min

IntegerField

Minimum grade level for students

grade_max

IntegerField

Maximum grade level for students

hardness_rating

CharField

Difficulty level indicator

ClassSection Model

Represents a specific offering/time slot of a class. Source: esp/esp/program/models/class_.py:293

Core Fields

parent_class

ForeignKey

required

The ClassSubject this section belongs to

Links to: ClassSubject
Related name: sections

status

IntegerField

Section-specific status

Choices: Same as ClassSubject
Default: UNREVIEWED (0)

registration_status

IntegerField

Whether registration is open for this section

Choices: OPEN (0), CLOSED (10)
Default: OPEN (0)

duration

DecimalField

Length of section in hours

Max digits: 5
Decimal places: 2
Example: 1.5 for 90 minutes

meeting_times

ManyToManyField

Time blocks when this section meets

Links to: Event
Can span multiple time blocks

max_class_capacity

IntegerField

Override capacity for this specific section

If not set, uses parent class capacity

moderators

ManyToManyField

Non-teacher moderators for this section

Links to: ESPUser
Separate from main teachers

registrations

ManyToManyField

Students registered for this section

Links to: ESPUser
Through model: StudentRegistration

ClassSection Methods

Scheduling Methods

start_time()

Event

Returns the first meeting time for this sectionReturns: Event object or None if not scheduledExample:

section = ClassSection.objects.get(id=123)
start = section.start_time()
if start:
    print(f"Class starts at {start.start}")

end_time()

Event

Returns the last meeting time for this sectionReturns: Event object with latest end time, or None

isScheduled()

bool

Checks if section has assigned meeting timesReturns: True if meeting_times exist

assign_start_time(first_event)

Schedules the class starting at given eventParameters:

first_event (Event): Starting time block

Behavior:

Automatically extends to cover class duration
Clears existing rooms
Attempts to reassign same rooms if available

assign_meeting_times(event_list)

Manually set all meeting times for sectionParameters:

event_list (list): List of Event objects

Behavior:

Clears existing meeting times
Adds all events in list

Room Assignment

classrooms()

QuerySet

Returns assigned classroom resourcesReturns: QuerySet of Resource objects with res_type=“Classroom”Example:

section = ClassSection.objects.get(id=123)
rooms = section.classrooms()
for room in rooms:
    print(f"Room: {room.name} (capacity: {room.num_students})")

assign_room(base_room, clear_others=False, allow_partial=False, lock=0)

tuple

Assign a classroom to this sectionParameters:

base_room (Resource): Classroom resource to assign
clear_others (bool): Remove other room assignments first
allow_partial (bool): Allow partial time block coverage
lock (int): Lock level for scheduling (0=unlocked)

Returns: Tuple of (success: bool, errors: list)Example:

from esp.resources.models import Resource

room = Resource.objects.get(name='Room 123')
success, errors = section.assign_room(room)
if not success:
    for error in errors:
        print(f"Error: {error}")

clearRooms()

Removes all classroom assignments from this section

prettyrooms()

list

Returns list of room namesReturns: List of strings (room names) or empty list if unscheduled

Student Management

students(verbs=['Enrolled'])

QuerySet

Returns students with specified relationship to sectionParameters:

verbs (list): Registration types (e.g., [‘Enrolled’, ‘Interested’])

Returns: QuerySet of ESPUser objectsExample:

# Get enrolled students
enrolled = section.students()

# Get students who expressed interest
interested = section.students(verbs=['Interested'])

num_students(verbs=['Enrolled'])

int

Count of students in sectionParameters:

verbs (list): Registration types to count

Returns: Integer countCached: Yes

students_checked_in()

QuerySet

Returns students currently checked in to this sectionReturns: QuerySet of ESPUser objects

isFull(webapp=False)

bool

Checks if section is at capacityReturns: True if num_students >= capacity

cannotAdd(user, checkFull=True)

string or False

Checks if user can register for this sectionParameters:

user (ESPUser): User attempting to register
checkFull (bool): Check capacity limits

Returns: Error message string if cannot add, False if can addExample:

error = section.cannotAdd(student)
if error:
    print(f"Cannot register: {error}")
else:
    # Proceed with registration
    pass

Cancellation

cancel(email_students=True, email_teachers=True, explanation=None, unschedule=False)

Cancels the section and optionally notifies participantsParameters:

email_students (bool): Send cancellation email to students
email_teachers (bool): Send email to teachers
explanation (str): Reason for cancellation
unschedule (bool): Remove time and room assignments

Behavior:

Sets status to CANCELLED
Clears student registrations
Sends notification emails
Optionally removes scheduling

Properties

capacity

int

Effective capacity of the sectionCalculation:

Uses max_class_capacity if set
Otherwise uses min of: class_size_max, room capacity
Applies program-specific multipliers if configured

Cached: Yes

emailcode()

string

Unique identifier for this sectionFormat: {parent_class_emailcode}s{section_index}Example: “E1234s1” for first section of class E1234

title()

string

Returns parent class title

index()

int

Section number within parent classReturns: 1-indexed position (first section = 1)

Usage Examples

Creating a Class with Sections

from esp.program.models import Program, ClassSubject, ClassSection, ClassCategories
from esp.users.models import ESPUser

# Get program and teacher
program = Program.objects.get(url='Splash/2024')
teacher = ESPUser.objects.get(username='jdoe')
category = ClassCategories.objects.get(symbol='M')  # Math

# Create the class subject
subject = ClassSubject.objects.create(
    parent_program=program,
    category=category,
    title='Introduction to Calculus',
    class_info='Learn the fundamentals of differential and integral calculus.',
    class_size_max=25,
    grade_min=10,
    grade_max=12
)
subject.teachers.add(teacher)

# Create a section
section = ClassSection.objects.create(
    parent_class=subject,
    duration=1.5,  # 90 minutes
    max_class_capacity=20
)

Scheduling a Section

from esp.cal.models import Event
from esp.resources.models import Resource

section = ClassSection.objects.get(id=123)

# Get time blocks
timeslots = Event.objects.filter(
    program=section.parent_program,
    start__gte='2024-03-01 09:00:00'
)

# Assign meeting times
section.assign_meeting_times(list(timeslots[:2]))  # Use first 2 blocks

# Assign a classroom
room = Resource.objects.get(name='Room 4-237')
success, errors = section.assign_room(room)

Checking Registration Eligibility

student = ESPUser.objects.get(username='student123')
section = ClassSection.objects.get(id=456)

# Check if student can register
error = section.cannotAdd(student, checkFull=True)

if error:
    print(f"Registration blocked: {error}")
else:
    # Create registration (see Registration model docs)
    from esp.program.models import StudentRegistration, RegistrationType
    
    reg_type = RegistrationType.objects.get(name='Enrolled')
    StudentRegistration.objects.create(
        section=section,
        user=student,
        relationship=reg_type
    )

Getting Class Information

section = ClassSection.objects.get(id=789)

print(f"Class: {section.title()}")
print(f"Code: {section.emailcode()}")
print(f"Capacity: {section.capacity}")
print(f"Enrolled: {section.num_students()}")
print(f"Rooms: {', '.join(section.prettyrooms())}")

if section.isScheduled():
    print(f"Starts: {section.start_time().start}")
    print(f"Ends: {section.end_time().end}")

Program - Parent program containing classes
User - Teachers and students
Registration - Student enrollments
Resources - Classrooms and equipment

Models

Program Modules

Controllers

Overview

ClassSubject Model

Core Fields

Size and Capacity

Teacher Fields

Content Fields

ClassSection Model

Core Fields

ClassSection Methods

Scheduling Methods

Room Assignment

Student Management

Cancellation

Properties

Usage Examples

Creating a Class with Sections

Scheduling a Section

Checking Registration Eligibility

Getting Class Information

Build docs developers (and LLMs) love

Models

Program Modules

Controllers

​Overview

​ClassSubject Model

​Core Fields

​Size and Capacity

​Teacher Fields

​Content Fields

​ClassSection Model

​Core Fields

​ClassSection Methods

​Scheduling Methods

​Room Assignment

​Student Management

​Cancellation

​Properties

​Usage Examples

​Creating a Class with Sections

​Scheduling a Section

​Checking Registration Eligibility

​Getting Class Information

​Related Models

Build docs developers (and LLMs) love

Overview

ClassSubject Model

Core Fields

Size and Capacity

Teacher Fields

Content Fields

ClassSection Model

Core Fields

ClassSection Methods

Scheduling Methods

Room Assignment

Student Management

Cancellation

Properties

Usage Examples

Creating a Class with Sections

Scheduling a Section

Checking Registration Eligibility

Getting Class Information

Related Models