Exam Models

Purpose and Scope

This document describes the data models used for representing exam-related information in pyjiit. The primary model is the ExamEvent class, which encapsulates information about examination events (such as mid-semester exams, end-semester exams, etc.) for a given semester.

For information about attendance-related models, see Attendance Models. For registration and subject enrollment models, see Registration Models. For overall API usage patterns, see Webportal Class.

ExamEvent Class

The ExamEvent class is a dataclass that represents a single examination event. It is defined in pyjiit/exam.py4-20 and contains metadata about an exam period including its code, description, and associated identifiers.

Fields

Instantiation

The ExamEvent class provides a static factory method from_json(resp: dict) pyjiit/exam.py13-20 that deserializes API response data into an ExamEvent object. This method maps the following JSON keys:

• exameventcode → exam_event_code
• eventfrom → event_from
• exameventdesc → exam_event_desc
• registrationid → registration_id
• exameventid → exam_event_id

Sources: pyjiit/exam.py1-23

Exam Data Retrieval Flow

The exam system in pyjiit follows a three-step hierarchical retrieval pattern:

Sources: pyjiit/wrapper.py273-328

API Methods

get_semesters_for_exam_events()

Located at pyjiit/wrapper.py273-289 this method retrieves all semesters for which exam event data is available for the authenticated student.

Endpoint: /studentcommonsontroller/getsemestercode-withstudentexamevents

Payload Structure:

{
    "clientid": session.clientid,
    "instituteid": session.instituteid,
    "memberid": session.memberid
}

Returns: List[Semester] - List of semester objects that have associated exam events

Raises: APIError for generic API failures

Sources: pyjiit/wrapper.py273-289

get_exam_events(semester: Semester)

Located at pyjiit/wrapper.py292-308 this method retrieves all exam events for a specific semester.

Endpoint: /studentcommonsontroller/getstudentexamevents

Payload Structure:

{
    "instituteid": session.instituteid,
    "registationid": semester.registration_id  # Note: API typo "registationid"
}

Parameters:

• semester - A Semester object obtained from get_semesters_for_exam_events() or similar methods

Returns: List[ExamEvent] - List of exam events for the specified semester

Raises: APIError for generic API failures

Implementation Details: The method deserializes the API response by iterating over resp["response"]["eventcode"]["examevent"] and calling ExamEvent.from_json() for each item pyjiit/wrapper.py308

Sources: pyjiit/wrapper.py292-308

get_exam_schedule(exam_event: ExamEvent)

Located at pyjiit/wrapper.py311-328 this method retrieves the detailed examination schedule for a specific exam event.

Endpoint: /studentsttattview/getstudent-examschedule

Payload Structure:

{
    "instituteid": session.instituteid,
    "registrationid": exam_event.registration_id,
    "exameventid": exam_event.exam_event_id
}

Parameters:

• exam_event - An ExamEvent object obtained from get_exam_events()

Returns: dict - Raw dictionary containing exam schedule data including dates, times, subjects, and venues

Raises: APIError for generic API failures

Note: The method returns the raw resp["response"] dictionary pyjiit/wrapper.py328 without additional parsing, as the schedule structure can vary.

Sources: pyjiit/wrapper.py311-328

Data Model Relationships

The following diagram illustrates how ExamEvent relates to other data models and API methods:

Sources: pyjiit/wrapper.py273-328 pyjiit/exam.py1-23

JSON Deserialization

The ExamEvent.from_json() method performs field mapping from the JIIT API's JSON response format:

The API response structure for get_exam_events() follows this hierarchy:

response
  └── eventcode
      └── examevent (array)
          ├── exameventcode: str
          ├── eventfrom: int
          ├── exameventdesc: str
          ├── registrationid: str
          └── exameventid: str

Sources: pyjiit/exam.py13-20 pyjiit/wrapper.py308

Usage Example Pattern

The typical usage pattern for retrieving exam information follows this sequence:

Each step in this flow requires authentication via the @authenticated decorator pyjiit/wrapper.py272 pyjiit/wrapper.py291 pyjiit/wrapper.py310 which ensures a valid session exists before making API calls.

Sources: pyjiit/wrapper.py273-328

Implementation Notes

Authentication Requirement

All exam-related methods require authentication and are decorated with @authenticated pyjiit/wrapper.py272 pyjiit/wrapper.py291 pyjiit/wrapper.py310 Calling these methods without an active session will raise NotLoggedIn exception. See Exception Handling for details on exception types.

Payload Encryption

Methods that retrieve exam events and schedules use serialize_payload() pyjiit/wrapper.py285 pyjiit/wrapper.py304 pyjiit/wrapper.py324 to encrypt request payloads before sending to the API. See Encryption System for details on the encryption mechanism.

Data Immutability

ExamEvent is implemented as a dataclass pyjiit/exam.py4 making instances immutable by default. This ensures exam event data cannot be accidentally modified after retrieval from the API.

Sources: pyjiit/wrapper.py273-328 pyjiit/exam.py1-23