Getting Started

• docs/usage.rst
• poetry.lock
• pyproject.toml

This page provides an overview of how to install pyjiit, understand its core components, and make your first API calls to the JIIT Webportal. It introduces the basic workflow and concepts needed to use the library effectively.

For detailed installation instructions and dependency management, see Installation. For a comprehensive walkthrough with complete code examples, see Quick Start Guide. For in-depth coverage of the authentication process, see Authentication Flow.

Overview

The pyjiit library provides a Python interface to the JIIT Webportal APIs, enabling programmatic access to student information including attendance, exam schedules, registration data, and account management. The library handles the complex encryption requirements of the webportal API automatically.

What you'll accomplish in this section:

Prerequisites

Before installing pyjiit, ensure your system meets the following requirements:

The library uses Poetry for dependency management, but end users install via pip from PyPI.

Sources: pyproject.toml8-12

Installation Overview

Install pyjiit from PyPI using pip:

pip install pyjiit

This installs the library and its two core dependencies:

• requests: HTTP client for API communication
• pycryptodome: AES-CBC encryption for secure payload transmission

The package is distributed through PyPI and can be installed in any Python 3.9+ environment. For detailed installation options, virtual environment setup, and troubleshooting, see Installation.

Sources: docs/usage.rst6-13 pyproject.toml1-12

Basic Usage Workflow

The following diagram illustrates the typical workflow from installation to making authenticated API calls:

User Journey: Installation to First API Call

Sources: docs/usage.rst16-44

Your First API Call

Here's a minimal working example demonstrating the core workflow:

from pyjiit import Webportal
from pyjiit.default import CAPTCHA

# Step 1: Instantiate the Webportal client

w = Webportal()

# Step 2: Authenticate with credentials

session = w.student_login(
username="your_enrollment_number",
password="your_password",
captcha=CAPTCHA # Pre-filled captcha object
)

# Step 3: Verify session is active

print(f"Client ID: {w.session.clientid}") # Output: JAYPEE

# Step 4: Make an authenticated API call

meta = w.get_attendance_meta()
print(f"Available semesters: {[s.value for s in meta.semesters]}")

This example demonstrates:

1. Instantiation: Creating a Webportal instance at pyjiit/wrapper.py157-164
2. Authentication: Calling student_login() which returns a WebportalSession at pyjiit/wrapper.py166-246
3. Session verification: Accessing the session attribute populated after login
4. Data retrieval: Calling authenticated methods that return structured data models

Sources: docs/usage.rst30-44 docs/usage.rst71-108

Core Components and Their Roles

Understanding the key classes and modules helps you navigate the library effectively:

Component Architecture Map

Key Classes:

Sources: pyproject.toml1-12 docs/usage.rst19-28

Key Concepts

Sessions and Authentication

Authentication in pyjiit involves a two-phase process:

1. Pre-token check: Validates credentials and captcha
2. Token generation: Creates session tokens and establishes connection

After successful authentication, the Webportal.session attribute contains a WebportalSession instance with:

• clientid: Institution identifier (typically "JAYPEE")
• token: Authentication token for subsequent requests
• refreshToken: Token for session renewal

All authenticated methods use the @authenticated decorator to verify an active session before execution.

See Authentication Flow for detailed coverage of the authentication process.

Encrypted Communication

All API requests and responses are encrypted using AES-CBC with daily key rotation:

• Encryption key: Generated daily at 00:00 IST using generate_key() at pyjiit/encryption.py28-35
• IV (Initialization Vector): Fixed value b'dcek9wb8frty1pnm' at pyjiit/encryption.py26
• LocalName header: Unique per-request identifier at pyjiit/encryption.py79-95

The encryption is transparent to users; all serialization/deserialization happens automatically within the Webportal class.

Data Models

API responses are parsed into typed data model objects for structured access:

# Example: Attendance metadata
meta = w.get_attendance_meta()
# Returns: AttendanceMeta instance with .headers and .semesters attributes

# Example: Exam schedule
exams = w.get_exam_schedule()
# Returns: List[ExamEvent] with .subject_code, .exam_date, etc.

Each data model provides convenient methods like latest_header() and latest_semester() for common operations.

Exception Handling

The library defines a hierarchy of exceptions for fine-grained error handling:

from pyjiit.exceptions import LoginError, SessionExpired, NotLoggedIn

try:
    session = w.student_login(username, password, captcha)
except LoginError as e:
    print(f"Authentication failed: {e}")

try:
    attendance = w.get_attendance(header, semester)
except SessionExpired:
    # Re-authenticate
    w.student_login(username, password, captcha)
except NotLoggedIn:
    # Login required before this call
    w.student_login(username, password, captcha)

For comprehensive exception documentation, see Exception Handling.

Sources: docs/usage.rst138-142 pyjiit/exceptions.py1-34

Method Categories

The Webportal class provides methods organized by functionality:

All authenticated methods will raise NotLoggedIn if called before student_login().

Sources: pyjiit/wrapper.py157-803

Quick Reference: Common Operations

Retrieve Attendance

meta = w.get_attendance_meta()
header = meta.latest_header()
semester = meta.latest_semester()
attendance_data = w.get_attendance(header, semester)

Note: The get_attendance() call may take >10 seconds due to server-side processing.

Get Exam Schedule

exams = w.get_exam_schedule()
for exam in exams:
    print(f"{exam.subject_desc}: {exam.exam_date} at {exam.exam_time}")

Get Registered Subjects

semesters = w.get_registered_semesters()
registrations = w.get_registered_subjects_and_faculties(semesters[0])
print(f"Total credits: {registrations.total_credits}")
for subject in registrations.subjects:
    print(f"{subject.subject_code}: {subject.subject_desc}")

Sources: docs/usage.rst71-133

Next Steps

Now that you understand the basic workflow, proceed to:

• Installation - Detailed installation instructions, virtual environments, and dependency management
• Quick Start Guide - Complete walkthrough with multiple examples and best practices
• Authentication Flow - Deep dive into the two-phase authentication process and session management

For comprehensive API documentation, see:

• Webportal Class - Complete method reference
• Data Models - Detailed documentation of all data structures
• Exception Handling - Exception hierarchy and error handling patterns

Sources: docs/usage.rst1-145 pyproject.toml1-28