ZZU.Py

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

概述

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

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

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

特性

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

安装

pip install -U zzupy

要求：

Python >=3.11

快速开始

统一认证 + 本科教务

from zzupy.app import CASClient, UndergradEASClient

cas = CASClient("your_account", "your_password")
# cas.set_token("your_userToken", "your_refreshToken")
# cas.set_device("your_deviceId")
if cas.mfa.is_required():
    cas.mfa.send_sms()
    cas.mfa.verify_sms(input("input sms code:"))
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 认证

from zzupy.web import EPortalClient, discover_portal_info

portal = discover_portal_info()
with EPortalClient(portal.portal_server_url, bind_address=portal.user_ip, force_bind=True) as client:
    result = client.auth("your_account", "your_password")
    print(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/
文档站点由 Zensical 构建

开发

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

uv sync --extra develop,docs
uv run python scripts/generate_api_reference.py
uv run zensical serve
uv run zensical build
ruff format zzupy
ruff check zzupy
ty check zzupy
uv build

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

如需快速打开库内日志，推荐直接调用 logger.enable("zzupy")。

# 启用 TRACE 日志
from loguru import logger
import sys

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

许可证

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

Metadata

Release files for zzupy 7.2.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zzupy 7.2.3
File	Size	Uploaded
zzupy-7.2.3.tar.gz	66.1 kB	Aug 10, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for zzupy 7.2.3
File	Interpreter	ABI	Platform	Reset
zzupy-7.2.3-py3-none-any.whl 61.1 kB Aug 10, 2026	Python 3	none	any	Details

Total release size: 127.2 kB

Release files / zzupy-7.2.3.tar.gz

Download URL	zzupy-7.2.3.tar.gz
Size	66.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`3b6e55ace53d448ca7223f34bb61b4e58b07d7cc877b18d6d3f65d02164131dc`
BLAKE2b-256 checksum How to use checksums	`44219d9b310d24cc55e7bf135f2d2fa887731ed72b96f2eadb72d3ee02a0e3b4`
Upload date	Aug 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / zzupy-7.2.3-py3-none-any.whl

Download URL	zzupy-7.2.3-py3-none-any.whl
Size	61.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a07b3c488e12f65180d6f439f53d62de6f3091722ce018c9be36fc283bf129cd`
BLAKE2b-256 checksum How to use checksums	`2b01660295d08df9242e640b028d40b533dba1f45a586fc7b2d30315ef638553`
Upload date	Aug 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`