esprit-py 0.7.1
A fast, lightweight Python library for interacting with data from esprit-tn.com
Keywords: python, api


# esprit-py

![PyPI - Version](https://img.shields.io/pypi/v/esprit-py)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/esprit-py?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/esprit-py)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/esprit-py?period=monthly&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads+monthly)](https://pepy.tech/projects/esprit-py)
> [!NOTE]
> Please note that this library is not an official API provided by Esprit and is intended for educational and personal use only.

## Features

- **Fast & Lightweight**: 5-10x faster than previous versions (no Selenium/browser required)
- Get your exact timetable pdf *not 300 pages pdf*
- **Grades**:
  - Regular session grades (released one by one during semester)
  - Principal session final results (end of year verdict)
  - Rattrapage (retake) session grades
  - Rattrapage session final results
  - Calculate your total semester average
- Get your absences
- Get your credits
- Get your language proficiency levels (French & English)
- Get your ranking across past academic years
- **New**: Logout functionality for proper session management

## Installation

```bash
pip install --upgrade esprit-py
```

## Examples

### Get regular grades and calculate average:

```python
from esprit import Esprit

# Replace with your actual ID and password
id = 'ID'
password = 'PASSWORD'

grades = None

# Keep trying to get grades until it is successful cuz esprit use garabage servers
while grades is None:
    try:
        # Create an Esprit object
        esprit = Esprit()

        # Attempt to log in
        esprit.login(id, password)

        # Get regular grades (released one by one during semester)
        grades = esprit.get_regular_grades()

    except Exception as e:
        print(f"An error occurred: {e}. Retrying...")

if grades is not None:
    for grade in grades:
        print(grade)
    
    # Calculate average
    esprit.calculate_average(grades)
else:
    print("Failed to get grades.")

# Logout when done
esprit.logout()
```

### Get all grade-related data:

```python
from esprit import Esprit

esprit = Esprit()
id = 'ID'
password = 'PASSWORD'

if esprit.login(id, password):
    # Regular session grades (released during semester)
    regular_grades = esprit.get_regular_grades()
    if regular_grades:
        print("Regular Grades:", regular_grades)
    
    # Principal session final result (end of year)
    principal_result = esprit.get_principal_result()
    if principal_result:
        print("Principal Result:", principal_result)
    
    # Rattrapage session grades (retakes)
    rattrapage_grades = esprit.get_rattrapage_grades()
    if rattrapage_grades:
        print("Rattrapage Grades:", rattrapage_grades)
    
    # Rattrapage session final result
    rattrapage_result = esprit.get_rattrapage_result()
    if rattrapage_result:
        print("Rattrapage Result:", rattrapage_result)
    
    # Language proficiency levels
    language_levels = esprit.get_language_levels()
    if language_levels:
        print("Language Levels:", language_levels)
    
    # Academic ranking across years
    ranking = esprit.get_ranking()
    if ranking:
        print("Ranking:", ranking)
    
    esprit.logout()
```

### Get absences:

```python
from esprit import Esprit

# Create an Esprit object
esprit = Esprit()

# Replace with your actual ID and password
id = 'ID'
password = 'PASSWORD'

# Attempt to log in
if esprit.login(id, password):
    print("Login successful.")
else:
    print("Login failed.")

# Get absences
absences = esprit.get_absences()
if absences is not None:
    for absence in absences:
        print(absence)
else:
    print("Failed to get absences.")

# Logout when done
esprit.logout()
```

More examples can be found in the [examples folder](examples)