Metadata-Version: 2.4
Name: tju
Version: 0.1.1
Summary: The Python TJU client — scrapes TJU SSO + EAMS for structured academic data
Project-URL: Homepage, https://github.com/superpung/tju-python
Project-URL: Repository, https://github.com/superpung/tju-python
Project-URL: Documentation, https://superpung.github.io/tju-python/
Project-URL: Changelog, https://github.com/superpung/tju-python/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/superpung/tju-python/issues
Author-email: Super Lee <hi@repus.me>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: academic,eams,scraper,tianjin university,tju
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: ddddocr>=1.5.5
Requires-Dist: fake-useragent>=1.5.1
Requires-Dist: httpx>=0.27.2
Requires-Dist: markdownify>=0.13.1
Requires-Dist: marshmallow-dataclass>=8.7.1
Requires-Dist: marshmallow>=3.22.0
Requires-Dist: pyexecjs>=1.5.1
Description-Content-Type: text/markdown

<p align="center"><b>TJU</b> <sup><samp>The Python TJU client</samp></sup></p>

[![PyPI version](https://img.shields.io/pypi/v/tju.svg)](https://pypi.org/project/tju/)
[![CI](https://github.com/superpung/tju-python/actions/workflows/ci.yml/badge.svg)](https://github.com/superpung/tju-python/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://superpung.github.io/tju-python/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)

English | [简体中文](README.zh-CN.md)

> **Beta release (v0.1.0).** 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

| Feature | Client method |
|---|---|
| Student profile | `client.profile` |
| Personal timetable | `client.schedule(semester)` |
| Public course library | `client.query_courses(semester)` |
| Course detail | `client.query_course_info(lession_id)` |
| Course syllabus | `client.query_syllabus(lession_id)` |
| Exam schedule | `client.exam(semester)` |
| Scores (UG + GS) | `client.score()` |
| Experiment scores | `client.exp_score(semester)` |
| Free classroom search | `client.free_classrooms(date_begin, ...)` |

## Installation

```sh
pip install tju
```

From source (recommended for development):

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

## Quick start

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

```sh
export TJU_USER=your_student_id
export TJU_PASS=your_password
```

```python
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:**

```sh
# 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

```python
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

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

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

## Documentation

Full API reference and usage guides: **<https://superpung.github.io/tju-python/>**

To build the docs locally:

```sh
uv sync --group docs
uv run mkdocs serve
```

## License

[GPLv3 License](LICENSE) © 2023-PRESENT Super Lee
