sislib

A clean, synchronous Python library for automating access to the CUHK-Shenzhen Student Information System (SIS), which runs on Oracle PeopleSoft Campus Solutions (sis.cuhk.edu.cn, portal node csprd).

Goals

• Interactive login through the university ADFS SSO, with encrypted, reusable session credentials (no plaintext passwords or cookies on disk).
• Elegant session state management and reuse: log in once, reuse the saved session for later operations.
• Convenient, high-level operations:
  • log in and persist credentials
  • view the weekly course schedule
  • list available terms
  • list selectable courses per term, with enrollment requirements
  • review your course history (grades and progress)
  • download your unofficial transcript as a PDF

Status

Early development, but the core read-only flows are working end-to-end: login + credential persistence, the weekly schedule, term and class search (with optional enrollment requirements), course history, and unofficial-transcript download. See docs/ for the architecture and the live observations of the SIS / ADFS / PeopleSoft mechanism, and AGENTS.md for the working protocol that keeps human and agent contributors consistent.

Try it out

sislib ships a small CLI. Set it up, log in once, then read your schedule and browse classes from the saved session.

1. Install

uv sync
uv run playwright install chromium   # or set SISLIB_CHROMIUM_PATH=/usr/bin/chromium

2. Log in once

A browser opens for the university ADFS sign-in. On success, an encrypted session is written to disk (no plaintext password or cookies). You are prompted for a session passphrase that encrypts that session at rest — remember it, you will need it for every later command.

uv run sislib login                  # prompts for username, password, passphrase
uv run sislib status                 # confirm a session is saved

To avoid re-typing the passphrase, export it for the shell session:

export SISLIB_PASSPHRASE='your-passphrase'

If you are in headless environment, you can also set SISLIB_HEADLESS=true in shell and enter password interactively.

3. Use the saved session

uv run sislib schedule               # weekly calendar grid for the current term
uv run sislib terms                  # every academic term you can search
uv run sislib classes -t 2550 -s CSC # classes for a term + subject
uv run sislib history                # your course history (grades and progress)
uv run sislib transcript             # download your unofficial transcript PDF

classes accepts:

Flag	Meaning
-t, --term	Term code (required) — pick one from sislib terms.
-s, --subject	Subject code such as CSC, or all (default) to scan every subject.
--open-only	Hide sections that are already full.
--exclude-conflicts	Hide sections that clash with your current weekly schedule.
--with-requirements	Also fetch each course's enrollment requirements (one extra request per course; slower).

For example, find every still-open class in a term that fits around your timetable:

uv run sislib classes -t 2550 -s all --open-only --exclude-conflicts

transcript defaults to the English unofficial transcript (UE01); pick another type or destination, or list what is available:

uv run sislib transcript --list                 # show the available transcript types
uv run sislib transcript -t UC01 -o mine.pdf    # Chinese transcript to a chosen path

When you are done, drop the saved session:

uv run sislib logout

Run uv run sislib --help (or sislib <command> --help) for the full reference. The same operations are available programmatically through SisClient — see the usage guide and the API reference.

Tech stack

• Python (sync core), uv for environment management
• Playwright for the interactive ADFS login (robust against SSO/JS)
• httpx for lightweight session reuse
• loguru for logging, pydantic for typed models/config
• cryptography (Fernet) for at-rest cookie encryption
• selectolax for HTML parsing

Layout

src/sislib/
  config.py        # pydantic-settings configuration
  exceptions.py    # typed exception hierarchy
  logging.py       # loguru setup
  transport/       # auth, session, encrypted cookie storage
  peoplesoft/      # PeopleSoft ICAction navigation (schedule, courses, history, transcript)
  features/        # schedule, terms, courses, history, transcript
  models/          # pydantic data models
  client.py        # public facade (SisClient)

Documentation

API docs are generated with Sphinx (autodoc + napoleon, furo theme) from the Sphinx-style docstrings in src/. The narrative guides under docs/ are included via MyST. Build them with:

uv run sphinx-build -W -b html docs docs/_build/html
# or: cd docs && uv run make html

The result lands in docs/_build/html/index.html.