Client¶
- class vitap_vtop_client.client.VtopClient(registration_number, password, max_login_retries=3, captcha_retries=5, user_agent=None)[source]¶
Bases:
objectAn asynchronous client for interacting with the VIT-AP VTOP portal.
- Parameters:
- get_cookie()[source]¶
Returns this session’s cookies as a Cookie header value.
Lets something outside this client reuse the authenticated session — an in-app VTOP WebView, for example — without logging in again. The consumer is advised to send the same User-Agent (see user_agent) so the session keeps one consistent identity, though VTOP was not observed to require it.
- Return type:
- Returns:
str – e.g. “JSESSIONID=…; other=…”, empty if there are none.
- Raises:
VtopSessionError – If the client is not logged in yet.
- property session: RestorableSession¶
Everything needed to rebuild this client elsewhere.
Pair this with VtopClient.restore. Handing these three values to another process lets it act on the same VTOP session without logging in again, which matters because VTOP’s login is captcha gated and may demand an OTP the user has to read from their email.
- Returns:
RestorableSession –
- The cookie, the post-login CSRF token, the
registration number and the User-Agent this session uses.
- Raises:
VtopSessionError – If the client is not logged in yet.
- property otp_challenge: OtpChallenge¶
The pending OTP challenge, in a form another process can finish.
Pair this with VtopClient.restore_otp_challenge. A web service raises the challenge while answering one request and receives the OTP on the next, by which point this client is long gone — so the challenge has to be carried rather than held.
- Returns:
OtpChallenge –
- The cookie, the OTP page’s CSRF token, the
registration number and the User-Agent this session uses.
- Raises:
VtopSessionError – If no OTP challenge is pending.
- classmethod restore_otp_challenge(registration_number, cookie, csrf_token, user_agent=None)[source]¶
Rebuilds a client that is mid-way through an OTP challenge.
Credentials and captcha were already accepted when the challenge was raised, so the returned client needs only the OTP: call verify_login_otp, or resend_login_otp if it has expired.
The client is deliberately not authenticated. _ensure_logged_in still refuses to fetch data until the OTP is verified, so a caller cannot accidentally use a half-finished login.
- Parameters:
registration_number (
str) – The student the challenge belongs to.cookie (
str) – The Cookie header value from otp_challenge.csrf_token (
str) – The OTP page’s CSRF token, from otp_challenge or from VtopLoginOtpRequiredError.csrf_token.user_agent (
str|None) – The agent the challenge was created with.
- Return type:
- Returns:
VtopClient – A client awaiting verify_login_otp.
- Raises:
VtopSessionError – If any of the three values is missing.
- classmethod restore(registration_number, cookie, csrf_token, user_agent=None)[source]¶
Rebuilds a client from a session exported by session.
VTOP keeps its session server side against the JSESSIONID cookie, so a client holding that cookie and the post-login CSRF token can make data requests without logging in — verified against live VTOP from a process that had never authenticated.
This is what lets a caller be stateless. A web service can log in once, hand these values back to its own client, and take them again on the next request, instead of keeping a live VtopClient in memory and losing every session when it restarts.
The returned client has no password. If the session has expired it cannot log back in, and raises VtopSessionError instead.
- Parameters:
registration_number (
str) – The student the session belongs to.cookie (
str) – The Cookie header value from get_cookie().csrf_token (
str) – The post_login_csrf_token from session.user_agent (
str|None) – The agent the session was created with. Advisory — VTOP was not observed to enforce it — but passing it keeps one identity across the whole session.
- Return type:
- Returns:
VtopClient – A client ready to make data requests.
- Raises:
VtopSessionError – If any of the three values is missing.
- async login()[source]¶
Logs in to VTOP explicitly.
VTOP requires an OTP after a period of inactivity or when logging in from a new IP address. When that happens this raises VtopLoginOtpRequiredError; collect the OTP from the user and pass it to verify_login_otp to finish authenticating.
- Return type:
- Returns:
LoggedInStudent – The authenticated session details.
- Raises:
VtopLoginOtpRequiredError – If VTOP requires an OTP to continue.
VtopLoginError – If the credentials are rejected.
- async verify_login_otp(otp)[source]¶
Completes a login that VTOP interrupted with an OTP challenge.
- Parameters:
otp (
str) – The OTP entered by the user.- Return type:
- Returns:
LoggedInStudent – The authenticated session details.
- Raises:
VtopSessionError – If no OTP challenge is currently pending.
VtopLoginOtpIncorrectError – If the OTP is wrong.
VtopLoginOtpExpiredError – If the OTP has expired.
- async resend_login_otp()[source]¶
Asks VTOP to send a fresh login OTP.
- Raises:
VtopSessionError – If no OTP challenge is currently pending.
VtopLoginError – If VTOP declines to resend the OTP.
- Return type:
- async get_semesters()[source]¶
Fetches the semesters available to the student.
The ids returned here are what every semester scoped method expects. Take them from this call rather than storing them, because VTOP does not reject an unknown semester id – it answers with a normal, empty result. A stale id from a previous term therefore looks exactly like a semester in which the student has no data, and nothing downstream can tell the difference.
Semester scoped methods check the shape of an id (AP and seven digits) and reject a typo, but a well formed id that is simply wrong cannot be caught here. Choosing a real one from this list is the caller’s responsibility.
- Return type:
- Returns:
SemesterData – The available semesters and the time they were read.
- async get_attendance(sem_sub_id)[source]¶
Fetches attendance data for the given semester subject ID.
- Parameters:
sem_sub_id (
str) – The semester subject ID (e.g., “AP2023242”).- Return type:
- Returns:
A list containing the parsed attendance data(AttendanceModel).
- async get_attendance_detail(sem_sub_id, course_id, course_type)[source]¶
Fetches the per class attendance detail for a single course.
- Parameters:
- Return type:
- Returns:
A list containing one AttendanceDetailModel per class held.
- async get_capstone_attendance(sem_sub_id)[source]¶
Fetches capstone/SDP attendance for the given semester.
This is deliberately separate from get_attendance: capstone attendance is per semester rather than per course, and counts present / on duty / absent instead of attended / total, so it does not fit AttendanceModel. VTOP returns the tally and the day-by-day calendar together, so both arrive in one call.
- Parameters:
sem_sub_id (
str) – The semester subject ID (e.g., “AP2026272”).- Return type:
- Returns:
The CapstoneAttendanceModel, or None when the student has no capstone registered for that semester.
- async get_calendar_class_groups(sem_sub_id)[source]¶
Fetches the calendar class groups available for a semester.
Class groups are semester dependent, so they cannot be hardcoded. Usually “COMB” (All Class Group Combined) and one or more specific groups.
- Parameters:
sem_sub_id (
str) – The semester subject ID (e.g., “AP2026272”).- Return type:
- async get_calendar_months(sem_sub_id, class_group_id='COMB')[source]¶
Fetches the months a semester’s calendar covers.
Each entry carries the cal_date that get_calendar_month expects.
- Parameters:
- Return type:
- async get_calendar_month(sem_sub_id, cal_date, class_group_id='COMB')[source]¶
Fetches one month of the academic calendar.
VTOP renders the month as a week grid; this returns it as a flat, date-ordered list of days, since the grid is a display concern.
- Parameters:
- Return type:
- async get_academic_calendar(sem_sub_id, class_group_id='COMB')[source]¶
Fetches a semester’s whole academic calendar.
Convenience over the three calls above: it opens the page, reads the month list, fetches every month, and flattens them into one date-ordered list of days. That is one request per month — six for a typical semester — so prefer get_calendar_month for a single month.
- Parameters:
- Return type:
- async get_biometric(date)[source]¶
Fetches biometric data for the given date.
- Parameters:
date (
str) – The date for which the biometric log is requested, in ‘dd/mm/yyyy’ format.- Return type:
- Returns:
A list containing the parsed biometric data(AttendanceModel).
- async get_timetable(sem_sub_id)[source]¶
Fetches timetable data for the given semester.
- Parameters:
sem_sub_id (
str) – The semester subject ID (e.g., “AP2023242”).- Return type:
- Returns:
A TimetableModel containing the parsed timetable details.
- async get_grade_view(sem_sub_id)[source]¶
Fetches the graded courses for a semester.
Grades appear only once a semester has ended; the current semester returns nothing until results are published. Each course carries a course_id for get_grade_view_detail.
- Parameters:
sem_sub_id (
str) – The semester subject ID (e.g., “AP2025264”).- Return type:
- Returns:
A list of GradeViewCourse, one per graded course.
- async get_grade_view_detail(sem_sub_id, course_id)[source]¶
Fetches the mark breakdown and class statistics for one course.
This is the data behind an expandable tile on the grade view page: the per-component marks (CAT, FAT, quizzes) plus the class mean, standard deviation and grade cutoffs.
- Parameters:
- Return type:
- Returns:
The GradeViewDetail for the course.
- async get_grade_history()[source]¶
Fetches grade history for the given registration_number.
- Return type:
- Returns:
A GradeHistoryModel containing the parsed grade history details.
- async get_mentor()[source]¶
Fetches mentor data for the given registration_number.
- Return type:
- Returns:
A MentorModel containing the parsed mentor data.
- async get_profile(include_grade_history=True, include_mentor=True)[source]¶
Fetches profile data for the given registration_number.
The profile page does not carry the grade history or the mentor, so each of those is a further request. They are fetched concurrently.
Grade history is the largest response the client fetches anywhere, around 137KB. If you only need the profile itself, turn it off.
- Parameters:
- Return type:
- Returns:
A StudentProfileModel containing the parsed student details. Anything not requested is left at its model default.
- async get_exam_schedule(sem_sub_id)[source]¶
Fetches all exam schedules for the given semester.
- Return type:
- Returns:
A ExamScheduleModel containing the parsed exam schedule details.
- Parameters:
sem_sub_id (str)
- async get_marks(sem_sub_id)[source]¶
Fetches all marks for the given semester.
- Return type:
- Returns:
A MarksModel containing the parsed mark details.
- Parameters:
sem_sub_id (str)
- async get_weekend_outing_requests()[source]¶
Fetches all the previously submitted Weekend Outing requests.
- Return type:
- Returns:
A WeekendOutingModel containing the previously submitted Weekend Outing details.
- async get_general_outing_requests()[source]¶
Fetches all the previously submitted Genneral Outing requests.
- Return type:
- Returns:
A GeneralOutingModel containing the previously submitted General Outing details.
- async get_pending_payments()[source]¶
Fetches a list of pending payments.
- Return type:
- Returns:
A list of PendingPayment if found or an empty list.
- async get_payment_receipts()[source]¶
Fetches a list of previously made payment receipts.
- Return type:
- Returns:
A list of PaymentReceipt if found or an empty list.
- async init_course_page()[source]¶
Opens the course page.
VTOP requires this before it will answer get_course_page_courses and get_course_page_slots.
- Return type:
- Returns:
The course page markup.
- async get_course_page_courses(sem_sub_id)[source]¶
Fetches the courses selectable on the course page for a semester.
Call init_course_page first.
- Parameters:
sem_sub_id (
str) – The semester subject ID (e.g., “AP2023242”).- Return type:
- Returns:
The selectable courses.
- async get_course_page_slots(sem_sub_id, class_id)[source]¶
Fetches the slots and class rows for a course.
- Parameters:
- Return type:
- Returns:
The selectable slots and the class rows.
- async get_course_detail(sem_sub_id, erp_id, class_id)[source]¶
Fetches a course’s detail page, with lectures and material links.
- Parameters:
- Return type:
- Returns:
The course summary, lectures and download paths.
- async download_course_material(download_path)[source]¶
Downloads a course material, syllabus or bundled material archive.
- async download_course_plan(sem_sub_id, class_id)[source]¶
Downloads a course plan as an Excel workbook.
- async submit_general_outing(out_place, purpose_of_visit, outing_date, out_time, in_date, in_time)[source]¶
Submits a general outing request.
- Parameters:
- Return type:
- Returns:
VTOP’s response message.
- async submit_weekend_outing(out_place, purpose_of_visit, outing_date, out_time, contact_number)[source]¶
Submits a weekend outing request.
- Parameters:
- Return type:
- Returns:
VTOP’s response message.
- async download_general_outing_pass(leave_id)[source]¶
Downloads the leave pass PDF for a general outing request.
- async download_weekend_outing_form(booking_id)[source]¶
Downloads the outing form PDF for a weekend outing request.
- async download_payment_receipt(receipt_no, application_number)[source]¶
Downloads the printable document for a paid receipt.
VTOP serves this as an HTML page rather than a PDF.
- async get_digital_assignments(sem_sub_id)[source]¶
Fetches every course’s assignments for the given semester.
This issues one additional request per course, since VTOP serves the course list and the per course assignments separately.
- Parameters:
sem_sub_id (
str) – The semester subject ID (e.g., “AP2023242”).- Return type:
- Returns:
A list of DigitalAssignmentModel with details populated.
- async get_course_assignments(class_id)[source]¶
Fetches the assignments for a single course.
- Parameters:
class_id (
str) – The class id, from DigitalAssignmentModel.class_id.- Return type:
- Returns:
A list of AssignmentRecordModel, one per assignment.
- async download_assignment_file(download_url)[source]¶
Downloads an assignment question paper or a submitted assignment file.
- async upload_assignment(class_id, mcode, file_name, file_bytes)[source]¶
Uploads a file as the submission for one assignment.
VTOP may hold the upload pending an OTP mailed to the student, in which case this raises VtopDigitalAssignmentUploadOtpRequiredError; follow up with verify_assignment_upload_otp.
- Parameters:
- Return type:
- Returns:
VTOP’s response message, “Uploaded successfully” on success.
- async verify_assignment_upload_otp(otp)[source]¶
Confirms a held assignment upload with the OTP VTOP mailed.
- async search_faculty(search_term)[source]¶
Searches for a faculty member and returns the first match.
- Parameters:
search_term (
str) – A faculty name or employee id to search for.- Return type:
- Returns:
The first matching FacultyModel, or an empty model when there are no matches.
- async get_all_faculty()[source]¶
Fetches the full faculty directory.
- Return type:
- Returns:
A list of FacultyModel, one per faculty member.