Metadata-Version: 2.4
Name: zzupy
Version: 7.0.0
Summary: 豫见郑大的 Python API 封装 / An API wrapper for Zhengzhou University Mobile Campus written in Python.
Project-URL: Repository, https://github.com/Illustar0/ZZU.Py
Project-URL: Documentation, https://illustar0.github.io/ZZU.Py
Author-email: Illustar0 <me@illustar0.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.13.3
Requires-Dist: gmalg>=1.0.6
Requires-Dist: httpx>=0.28.1
Requires-Dist: icalendar>=7.0.1
Requires-Dist: ifaddr>=0.2.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: pydantic>=2.11.7
Requires-Dist: pyjwt>=2.10.1
Requires-Dist: typing-extensions>=4.12.2
Requires-Dist: whenever>=0.9.5
Provides-Extra: develop
Requires-Dist: pre-commit>=4.5.1; extra == 'develop'
Requires-Dist: ruff>=0.14.13; extra == 'develop'
Requires-Dist: ty>=0.0.23; extra == 'develop'
Provides-Extra: docs
Requires-Dist: jieba>=0.42.1; extra == 'docs'
Requires-Dist: markdown-callouts>=0.4.0; extra == 'docs'
Requires-Dist: markdown-exec>=1.11.0; extra == 'docs'
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.4.7; extra == 'docs'
Requires-Dist: mkdocs-include-markdown-plugin>=7.1.7; extra == 'docs'
Requires-Dist: mkdocs-llmstxt>=0.3.1; extra == 'docs'
Requires-Dist: mkdocs-material>=9.6.20; extra == 'docs'
Requires-Dist: mkdocs-minify-plugin>=0.8.0; extra == 'docs'
Requires-Dist: mkdocs-redirects>=1.2.2; extra == 'docs'
Requires-Dist: mkdocs-section-index>=0.3.10; extra == 'docs'
Requires-Dist: mkdocs>=1.6.1; extra == 'docs'
Requires-Dist: mkdocstrings>=0.30.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.30.0; extra == 'docs'
Description-Content-Type: text/markdown

# ZZU.Py

豫见郑大相关服务的 Python API 封装。

## 概述

`zzupy` 面向郑州大学常用线上服务，提供统一、显式且带类型提示的 Python 客户端。当前主要覆盖：

- App 端统一认证（CAS）
- 新本科教务（EAS）
- 校园一卡通
- 校园网 Portal 认证与自助服务系统
- 对应的异步实现

> [!WARNING]
> 当前仅适配本科教务新系统，研究生教务暂未支持。

## 特性

- 账密登录与 Token 复用并存，适合脚本和长期任务
- 同步 / 异步 API 基本对齐，迁移成本低
- 使用 Pydantic 模型组织响应数据，便于补全和校验
- 提供统一异常层级，公共异常基类为 `zzupy.exception.ZZUError`
- 保留较底层的请求行为，尽量贴近真实上游接口

## 安装

```bash
pip install -U zzupy
```

要求：

- Python `>=3.11`

## 快速开始

### 统一认证 + 本科教务

```python
from zzupy.app import CASClient, UndergradEASClient

cas = CASClient("your_account", "your_password")
cas.login()

with UndergradEASClient(cas) as eas:
    eas.login()
    week = eas.get_teaching_week(week=1)
    lesson = week.get(weekday=1, unit=1)
    if lesson:
        print(lesson.course.name_zh)
```

### 校园网 Portal 认证

```python
from zzupy.web import EPortalClient, discover_portal_info

portal = discover_portal_info()
with EPortalClient(portal.portal_server_url, bind_address=portal.user_ip) as client:
    result = client.auth("your_account", "your_password")
    print(result.success, result.message)
```

## 模块概览

### `zzupy.app`

- `CASClient`: App 端统一认证
- `UndergradEASClient`: 新本科教务课表与学期数据
- `ECardClient`: 校园卡余额、电费与房间相关接口

### `zzupy.web`

- `discover_portal_info`: 自动探测校园网 Portal 参数
- `EPortalClient`: Portal 认证
- `SelfServiceSystem`: 自助服务系统设备管理

### `zzupy.aio`

- 提供 `app` 与 `web` 下主要客户端的异步版本

## 文档

- 使用文档：<https://illustar0.github.io/ZZU.Py/>
- API 参考：<https://illustar0.github.io/ZZU.Py/reference/api/>

## 开发

项目使用 `uv` 管理环境和命令。

```bash
uv sync --extra develop,docs
ruff format zzupy
ruff check zzupy
ty check zzupy
uv build
```

异常处理建议优先捕获 `zzupy.exception.ZZUError`，再按需细分到 `NetworkError`、`ParsingError`、`OperationError`、`InvalidArgumentError` 等具体异常。

如需快速打开库内日志，推荐直接调用 `logger.enable("zzupy")`。
```python
# 启用 TRACE 日志
from loguru import logger
import sys

logger.remove()
logger.add(sys.stderr, level="TRACE")
logger.enable("zzupy")
```

## 许可证

本项目使用 MIT 许可证，详见 `LICENSE`。

## 相关链接

- GitHub：<https://github.com/Illustar0/ZZU.Py>
- Issues：<https://github.com/Illustar0/ZZU.Py/issues>
