tju 0.3.0

TJU ^{The Python TJU client}

English | 简体中文

Beta. The API is functional; minor breaking changes may occur before v1.0.

tju is a Python library that logs into Tianjin University's SSO and EAMS systems and returns structured academic data. It handles CAS authentication, CAPTCHA solving (via ddddocr), and HTML parsing — so your code just calls methods and gets typed objects back.

Network requirement: All live API calls require an active connection to the TJU campus network or VPN (sso.tju.edu.cn / classes.tju.edu.cn).

Features

Installation

pip install tju

For the interactive terminal app (TUI):

pip install 'tju[tui]'

For the local MCP server (AI agent integration):

pip install 'tju[mcp]'

From source (recommended for development):

git clone https://github.com/tjuse/tju-python.git
cd tju-python
uv sync       # installs all dependencies into .venv

Quick start

Interactive TUI

tju          # launches the full-screen terminal app

Enter your student ID and password on first launch. Credentials are saved securely (username in ~/.config/tju/config.toml, password in the OS keyring).

MCP server (AI agent integration)

tju-mcp setup   # store credentials in the OS keyring once
tju-mcp         # start the stdio MCP server

Add to Claude Desktop:

{ "mcpServers": { "tju": { "command": "tju-mcp" } } }

Your password is never exposed to the agent. The server reads credentials from the OS keyring and acts as the confidentiality boundary — no tool accepts or returns a password, and profile PII is masked by default.

Python API

Set your credentials as environment variables (or put them in a .env file):

export TJU_USER=your_student_id
export TJU_PASS=your_password

from tju.client import create_client

client = create_client()   # reads TJU_USER / TJU_PASS from env
print(client.profile)
print(client.schedule(semester="24251"))

Runnable examples:

# Personal timetable — prints your courses and saves JSON
uv run --env-file .env python examples/fetch_schedule.py

# Full course library (UG + GS) — crawls all pages and saves JSON
uv run --env-file .env python examples/fetch_all_courses.py

Both scripts write output to examples/output/ (gitignored).

Usage

from tju import Session
from tju.client import Client

session = Session()                              # or: Session(username=..., password=...)
client  = Client(session=session)

# Identity
client.stu_id        # student ID string
client.stu_name      # name string
client.stu_type      # StuType.UNDERGRADUATE | StuType.GRADUATE
client.has_minor     # bool
client.semester      # current semester code, e.g. "24252"

# Data
client.profile
client.schedule(semester="24251")
client.query_courses(semester="24251")
client.query_course_info(lession_id="387248")
client.query_syllabus(lession_id="387248")
client.exam(semester="24251")
client.score()
client.exp_score(semester="20211")
client.free_classrooms(date_begin="2025-10-08", campus_id=3)

Semester codes follow the EAMS convention, e.g. "24251" = 2024–2025 first term, "24252" = 2024–2025 second term. See src/tju/consts.py for the full SEMESTER map.

Development

uv sync          # install runtime + dev dependencies
uv run pytest    # run the offline test suite (70 tests, no network required)

See CONTRIBUTING.md for architecture details and the fixture privacy rule. See AGENTS.md for AI-agent contributor guidance.

Documentation

Full API reference and usage guides: https://python.tjuse.com/

To build the docs locally:

uv sync --group docs
uv run mkdocs serve

License

GPLv3 License © 2023-PRESENT Super Lee