Skip to content

pytoledo is a Python library to interact with the common virtual learning environment for the Association KU Leuven (Toledo).

License

Notifications You must be signed in to change notification settings

DaanVervacke/pytoledo

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

47 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

pytoledo

GitHub release (latest by date) GitHub code size in bytes GitHub Repo stars

pytoledo is a Python library to interact with the common virtual learning environment for the Association KU Leuven a.k.a Toledo.

v3.0.0 adds support for KU Leuven Authenticator, which is now mandatory for all students

v3.1.0 adds the ability to query Vives Plus endpoints, please note that this might not work for Luca, Odisee, Thomas More and UCLL students!

Motivation

My goal was to provide an easy way to interact with the various KU Leuven API endpoints.

This library reproduces the Toledo portal login flow and returns a requests Session object that keeps track of your cookies and headers.

With this basic session object you can query these endpoints:

  • Enrollments
  • Upcoming courses
  • Events (messages and updates)

Optionally:

  1. Extend this basic session with kuloket cookies. This allows you to query the following endpoints:
    • Schedule
  2. Extend this basic session with toledo dashboard cookies. This allows you to query the following endpoints:
    • Todo (tasks and tests)
  3. Create a Vives Plus session. This allows you to query the following endpoints:
    • Schedule (dynamic)
    • Student information
    • Notices
    • Dashboard

Good to know:

  • Bypassing KU Leuven Authenticator prompts is possible by exporting and re-using your Vives Plus authorization token.
  • Data will always be returned as JSON via stdout. You can redirect the output to any file using '>'.
  • Teacher accounts (u) are not supported!

Installation

pip

Use the package manager pip to install pytoledo.

pip install pytoledo --upgrade

Usage

As a package

Toledo
from toledo import portal
from toledo import kuloket
from toledo import dashboard
from toledo import api

# Create a portal session object 
portal_session = portal.create_session_object(
    user='',
    password=''
)

# Optionally extend the portal session with kuloket cookies
extendend_session = kuloket.extend_session(
    portal_session=portal_session
)
# and/or dashboard cookies
extendend_session = dashboard.extend_session(
    portal_session=portal_session
)

# Create an api object
toledo_api = api.create_api_object(
    session=extended_session
)
Vives Plus
from toledo import vivesplus
from toledo import api

# Create a Vives Plus session object from username & password
vivesplus_session = vivesplus.create_vivesplus_session_object(
    user='',
    password='',
)

# or from authorization token or file
vivesplus_session = vivesplus.create_vivesplus_session_object(
    authorization=''
)

# Create an api object
vivesplus_api = api.create_vivesplus_api_object(
    session=vivesplus_session
)

Examples

Toledo
Enrollments/courses
# returns all your courses in JSON
toledo_api.get_enrollments()
Upcoming courses
# returns your upcoming courses (for today) in JSON
toledo_api.get_upcoming()
Events (messages & updates)
# returns your messages in JSON
toledo_api.get_events(type='message')

# returns your updates in JSON
toledo_api.get_events(type='update')
Todo (tasks & tests)
# returns your tasks in JSON
toledo_api.get_to_do(type='task')

# returns your tests in JSON
toledo_api.get_to_do(type='test')
Schedule
# returns your schedule in JSON
toledo_api.get_schedule()
Vives Plus
Export and re-use authorization token
# login using username and password
vivesplus_session = vivesplus.create_vivesplus_session_object(
    user='',
    password='',
)
# Create an api object
vivesplus_api = api.create_vivesplus_api_object(
    session=vivesplus_session
)
# returns your authorization token in JSON
authorization = vivesplus_api.get_authorization_token()

# login using your authorization token
vivesplus_session = vivesplus.create_vivesplus_session_object(
    authorization=authorization['token']
)
Schedule
# returns your schedule in JSON
vivesplus_api.get_schedule(
    start_date='2023-06-14',
    end_date='2023-06-22'
)
Student information
# returns your student information in JSON
vivesplus_api.get_student_info()
Dashboard
# returns your dashboard in JSON
vivesplus_api.get_dashboard()
Notices
# returns your notices in JSON
vivesplus_api.get_notices()

As a script

Toledo
optional arguments:
  -h, --help            show this help message and exit

  --enrollments, -en    retrieve all your enrollments

  --todo {task,test}, -td {task,test}
                        retrieve your to-do list (tasks or tests)

  --upcoming, -up       retrieve your upcoming courses

  --events {message,update}, -ev {message,update}
                        retrieve your recent events (messages or updates)

  --schedule, -sc       retrieve your schedule

  --rnumber RNUMBER, -rn RNUMBER
                        your personal rnumber

  --password PASSWORD, -pw PASSWORD
                        your password

  --silent, -s          surpress output
Vives Plus
optional arguments:
  -h, --help            show this help message and exit

  --schedule, -sc       retrieve your schedule

  --student-info, -si   retrieve your student information

  --dashboard, -db      retrieve your dashboard

  --notices, -no        retrieve your notices

  --get-authorization-token, -gat 
                        retrieve your vives plus authorization token as a JSON file

  --set-authorization-token JSON TOKEN FILE, -sat JSON TOKEN FILE
                        set your vives plus authorization token by providing a JSON file

  --rnumber RNUMBER, -rn RNUMBER
                        your personal rnumber

  --password PASSWORD, -pw PASSWORD
                        your password

  --silent, -s          surpress output

Examples

Toledo
Enrollments/courses
python -m toledo toledo --enrollments --rnumber yourrrnumber --password yourpassword
Upcoming courses
python -m toledo toledo --upcoming --rnumber yourrrnumber --password yourpassword
Events (messages & updates)
# Messages
python -m toledo toledo --events message --rnumber yourrrnumber --password yourpassword
# Updates
python -m toledo toledo --events update --rnumber yourrrnumber --password yourpassword
Todo (tasks & tests)
# Tasks
python -m toledo toledo --todo task --rnumber yourrrnumber --password yourpassword
# Tests
python -m toledo toledo --todo test --rnumber yourrrnumber --password yourpassword
Schedule
python -m toledo toledo --schedule --rnumber yourrrnumber --password yourpassword
Vives Plus
Export and re-use authorization token
# Export
python -m toledo vivesplus --get-authorization-token --rnumber yourrrnumber --password yourpassword
# Re-use
python -m toledo vivesplus --set-authorization-token vivesplus_authorization_token_<yourrnumber>.json ... any other option
Schedule
python -m toledo vivesplus --set-authorization-token vivesplus_authorization_token_<yourrnumber>.json --schedule '2023-06-14' '2023-06-22'
Student information
python -m toledo vivesplus --set-authorization-token vivesplus_authorization_token_<yourrnumber>.json --student-info
Dashboard
python -m toledo vivesplus --set-authorization-token vivesplus_authorization_token_<yourrnumber>.json --dashboard
Notices
python -m toledo vivesplus --set-authorization-token vivesplus_authorization_token_<yourrnumber>.json --notices

TODO

  • Documentation
  • Tests

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

GNU GPLv3

About

pytoledo is a Python library to interact with the common virtual learning environment for the Association KU Leuven (Toledo).

Topics

Resources

License

Stars

Watchers

Forks

Languages