Attendance Models

Purpose and Scope

This page documents the data models used to represent attendance-related information in pyjiit. These models provide structured access to attendance metadata returned by the JIIT Webportal API, including student headers, semester information, and attendance records.

For information about how these models are used in API calls, see Webportal Class. For other data models in the library, see Exam Models, Registration Models, and Tokens and Captcha.

Sources: pyjiit/attendance.py1-53 docs/usage.rst71-108

Overview

The attendance system in pyjiit uses three primary data models to structure API responses:

These models are defined in pyjiit/attendance.py1-53 and work together to facilitate the two-step attendance retrieval process: first fetching metadata via Webportal.get_attendance_meta(), then querying specific attendance records via Webportal.get_attendance().

Sources: pyjiit/attendance.py1-53

Class Hierarchy and Relationships

Sources: pyjiit/attendance.py4-51

AttendanceHeader Class

The AttendanceHeader class represents student identification and program information required for attendance API calls. It is an immutable dataclass created from API response data.

Structure

pyjiit/attendance.py4-20

Factory Method

The class provides a static factory method from_json() at pyjiit/attendance.py13-20 that constructs an AttendanceHeader instance from a dictionary response. This method directly maps JSON keys to dataclass fields:

• resp['branchdesc'] → branchdesc
• resp['name'] → name
• resp['programdesc'] → programdesc
• resp['stynumber'] → stynumber

Usage Pattern

AttendanceHeader instances are not typically created directly by users. Instead, they are automatically constructed when calling Webportal.get_attendance_meta(), which returns an AttendanceMeta object containing a list of headers.

Sources: pyjiit/attendance.py4-20 docs/usage.rst78-79

Semester Class

The Semester class represents a semester registration with its associated identifiers. Like AttendanceHeader, it is an immutable dataclass.

Structure

pyjiit/attendance.py23-36

Factory Method

The from_json() static method at pyjiit/attendance.py31-36 constructs a Semester from API response data:

• resp['registrationid'] → registration_id
• resp['registrationcode'] → registration_code

Multiple Uses

The Semester class is used in multiple contexts:

• In AttendanceMeta for attendance queries
• As input to Webportal.get_registered_subjects_and_faculties() (see Registration Models)

Sources: pyjiit/attendance.py23-36 docs/usage.rst118-119

AttendanceMeta Class

The AttendanceMeta class is a container that holds attendance metadata returned by Webportal.get_attendance_meta(). It processes the raw API response and provides structured access to headers and semesters.

Structure

pyjiit/attendance.py40-51

Initialization

The constructor at pyjiit/attendance.py41-44 takes a raw API response dictionary and:

1. Stores the entire response in raw_response
2. Constructs a list of AttendanceHeader objects from resp["headerlist"]
3. Constructs a list of Semester objects from resp["semlist"]

Convenience Methods

latest_header()

pyjiit/attendance.py46-47

Returns the first AttendanceHeader from the headers list. The API response is ordered with the most recent header first, making this method a convenient way to access current student information.

latest_semester()

pyjiit/attendance.py49-50

Returns the first Semester from the semesters list. Like headers, semesters are ordered with the most recent first, allowing easy access to the current semester.

Sources: pyjiit/attendance.py40-51 docs/usage.rst78-103

Data Flow and Transformation

Sources: pyjiit/attendance.py40-51 docs/usage.rst78-83

Typical Usage Flow

The standard pattern for retrieving attendance data follows this sequence:

Step 1: Fetch Metadata

meta = w.get_attendance_meta()

This returns an AttendanceMeta instance populated with all available headers and semesters from pyjiit/attendance.py40-44

Step 2: Select Header and Semester

header = meta.latest_header()
sem = meta.latest_semester()

The convenience methods at pyjiit/attendance.py46-50 return the first (most recent) items from the respective lists. Alternatively, users can access specific items:

header = meta.headers[1]  # Second header
sem = meta.semesters[0]    # First semester

Step 3: Query Attendance

attendance_data = w.get_attendance(header, sem)

The header and sem objects are passed to Webportal.get_attendance(), which uses their fields to construct the API request. The method returns a dictionary with attendance records (see Webportal Class for details).

Sources: docs/usage.rst78-96

API Response Structure

The following table shows the mapping between API JSON structure and the model classes:

Sources: pyjiit/attendance.py13-36

Model Integration with Webportal

Sources: pyjiit/attendance.py4-51 docs/usage.rst78-96

Design Rationale

Dataclasses vs. Regular Classes

AttendanceHeader and Semester use the @dataclass decorator pyjiit/attendance.py3-4 because:

1. Immutability: These represent fixed data from API responses
2. Automatic methods: Dataclasses provide __init__, __repr__, and __eq__ automatically
3. Type hints: Field types are explicitly declared for better IDE support

AttendanceMeta as Regular Class

AttendanceMeta at pyjiit/attendance.py40 is implemented as a regular class rather than a dataclass because:

1. Complex initialization: The constructor performs list comprehensions and data transformation
2. Convenience methods: latest_header() and latest_semester() add business logic beyond simple data storage
3. Mutable container: Users might want to filter or modify the lists

Factory Method Pattern

Both dataclasses implement the static from_json() factory method pattern pyjiit/attendance.py13-36 to:

1. Encapsulate construction: JSON parsing logic is contained within the model
2. Type safety: Return type is explicitly the class type
3. Consistency: All models follow the same construction pattern

Sources: pyjiit/attendance.py1-53

Raw Response Access

The AttendanceMeta.raw_response attribute at pyjiit/attendance.py42 provides access to the complete, unprocessed API response. This is useful for:

• Accessing fields not exposed by the model classes
• Debugging API response structure
• Future-proofing if the API adds new fields

Users can access any additional fields from the original response:

meta = w.get_attendance_meta()
custom_field = meta.raw_response.get("someNewField")

Sources: pyjiit/attendance.py42

Error Handling

The attendance models themselves do not implement error handling. They assume valid input from the API. Error handling occurs at the Webportal level:

• NotLoggedIn exception if get_attendance_meta() is called without authentication (see Exception Handling)
• SessionExpired if the session token is invalid
• APIError if the API returns an error response

Sources: docs/usage.rst139-142

Performance Considerations

Attendance Query Latency

As documented in docs/usage.rst105-107 calls to Webportal.get_attendance() may take over 10 seconds to complete. This is server-side latency from the JIIT API, not related to the model classes themselves. Users should:

1. Cache AttendanceMeta results when making multiple attendance queries
2. Avoid unnecessary calls to get_attendance_meta()
3. Consider implementing asynchronous patterns for UI responsiveness

List Ordering

Both headers and semesters lists are ordered with most recent items first pyjiit/attendance.py43-44 This ordering is preserved from the API response, making latest_header() and latest_semester() O(1) operations.

Sources: docs/usage.rst105-107 pyjiit/attendance.py43-50