zzupy package

zzupy package#

Submodules#

zzupy.api module#

class zzupy.api.UserInfo[源代码]#

基类：TypedDict

name: str#

usercode: str#

class zzupy.api.ZZUPy(usercode: str, password: str, cookie: SimpleCookie | None = None)[源代码]#

基类：object

初始化一个 ZZUPy 对象

参数:

usercode (str) – 学号
password (str) – 密码
cookie (SimpleCookie) – 统一认证 Cookie。目前必须包含 ‘userToken’，否则会抛出 ValueError

抛出:

ValueError – Cookie 中缺少 ‘userToken’ 时抛出

get_user_token() → str[源代码]#: 获取本次会话的 userToken

property is_logged_in: bool#: 判断是否已登录

login(app_version: str = 'SWSuperApp/1.0.42', app_id: str = 'com.supwisdom.zzu', os_type: str = 'android') → LoginResult[源代码]#

参数:

app_version (str) – APP 版本，一般类似 “SWSuperApp/1.0.39” ，可自行更新版本号。
app_id (str) – APP 包名，一般不需要修改
os_type (str) – 系统类型，一般不需要修改

返回:

Tuple[str, str]

usercode (str) – 学号
name (str) – 姓名

返回类型:

Tuple[str,str]

抛出:

LoginException – 登录失败时抛出

async login_async(app_version: str = 'SWSuperApp/1.0.42', app_id: str = 'com.supwisdom.zzu', os_type: str = 'android') → LoginResult[源代码]#

参数:

app_version (str) – APP 版本，一般类似 “SWSuperApp/1.0.39” ，可自行更新版本号。
app_id (str) – APP 包名，一般不需要修改
os_type (str) – 系统类型，一般不需要修改

返回:

Tuple[str, str]

usercode (str) – 学号
name (str) – 姓名

返回类型:

Tuple[str,str]

抛出:

LoginException – 登录失败时抛出

set_device_params(**kwargs: Unpack[Dict[str, Any]]) → None[源代码]#

设置设备参数。这些参数都需要抓包获取，但其实可有可无，因为目前并没有观察到相关风控机制

参数:

deviceName (str) – 设备名，位于 “passwordLogin” 请求的 User-Agent 中，组成为 ‘{appVersion}({deviceName})’
deviceId (str) – 设备 ID ，
deviceInfo (str) – 设备信息，位于名为 “X-Device-Info” 的请求头中
deviceInfos (str) – 设备信息，位于名为 “X-Device-Infos” 的请求头中
userAgentPrecursor (str) – 设备 UA 前体，只需要包含 “SuperApp” 或 “uni-app Html5Plus/1.0 (Immersed/38.666668)” 前面的部分

zzupy.ecard module#

class zzupy.ecard.eCard(parent)[源代码]#

基类：object

初始化 eCard 实例

参数:: parent – 父对象

get_balance() → float[源代码]#

获取校园卡余额

返回:: 校园卡余额
返回类型:: float

async get_balance_async() → float[源代码]#

异步获取校园卡余额

返回:: 校园卡余额
返回类型:: float

get_default_room() → str[源代码]#

获取账户默认房间

返回:: 默认的房间

async get_default_room_async() → str[源代码]#

异步获取账户默认房间

返回:: 默认的房间

get_remaining_energy(room: str | None = None) → float[源代码]#

获取剩余电量

参数:: room (str) – 房间 ID 。格式应为 ‘areaid-buildingid–unitid-roomid’，可通过 get_room_dict() 获取
返回:: 剩余能源
返回类型:: float

async get_remaining_energy_async(room: str | None = None) → float[源代码]#

异步获取剩余电量

参数:: room (str) – 房间 ID 。格式应为 ‘areaid-buildingid–unitid-roomid’，可通过 get_room_dict() 获取
返回:: 剩余能源
返回类型:: float

get_remaining_power(room: str | None = None) → float[源代码]#

获取剩余电量

已被废弃，请使用 get_remaining_energy()

参数:: room (str) – 房间 ID 。格式应为 ‘areaid-buildingid–unitid-roomid’，可通过 get_room_dict() 获取
返回:: 剩余能源
返回类型:: float

get_room_dict(id: str) → dict[源代码]#

获取房间的字典

参数:: id (str) – 已知房间 ID 。例如: ‘’, ‘99’, ‘99-12’, ‘99-12–33’
返回:: 对应的字典
返回类型:: dict

async get_room_dict_async(id: str) → dict[源代码]#

异步获取房间的字典

参数:: id (str) – 已知房间 ID 。例如: ‘’, ‘99’, ‘99-12’, ‘99-12–33’
返回:: 对应的字典
返回类型:: dict

async init_async()[源代码]#: 异步初始化 eCard 实例

recharge_electricity(payment_password: str, amt: int, room: str | None = None) → Tuple[bool, str][源代码]#

为 room 充值电费

已被废弃，请使用 recharge_energy()

参数:

room (str) – 房间 ID 。格式应为 ‘areaid-buildingid–unitid-roomid’，可通过 get_room_dict() 获取
payment_password (str) – 支付密码
amt (int) – 充值金额

返回:

Tuple[bool, str]

success (bool) – 充值是否成功
msg (str) – 服务端返回信息。

返回类型:

Tuple[bool,str]

async recharge_electricity_async(payment_password: str, amt: int, room: str | None = None) → Tuple[bool, str][源代码]#

异步为 room 充值电费

已被废弃，请使用 recharge_energy_async()

参数:

room (str) – 房间 ID 。格式应为 ‘areaid-buildingid–unitid-roomid’，可通过 get_room_dict() 获取
payment_password (str) – 支付密码
amt (int) – 充值金额

返回:

Tuple[bool, str]

success (bool) – 充值是否成功
msg (str) – 服务端返回信息。

返回类型:

Tuple[bool,str]

recharge_energy(payment_password: str, amt: int, room: str | None = None) → Tuple[bool, str][源代码]#

为 room 充值电费

参数:

room (str) – 房间 ID 。格式应为 ‘areaid-buildingid–unitid-roomid’，可通过 get_room_dict() 获取
payment_password (str) – 支付密码
amt (int) – 充值金额

返回:

Tuple[bool, str]

success (bool) – 充值是否成功
msg (str) – 服务端返回信息。

返回类型:

Tuple[bool,str]

async recharge_energy_async(payment_password: str, amt: int, room: str | None = None) → Tuple[bool, str][源代码]#

异步为 room 充值电费

参数:

room (str) – 房间 ID 。格式应为 ‘areaid-buildingid–unitid-roomid’，可通过 get_room_dict() 获取
payment_password (str) – 支付密码
amt (int) – 充值金额

返回:

Tuple[bool, str]

success (bool) – 充值是否成功
msg (str) – 服务端返回信息。

返回类型:

Tuple[bool,str]

async start_token_refresh_loop()[源代码]#: 启动异步的 token 刷新循环

zzupy.log module#

zzupy.network module#

class zzupy.network.Network(parent)[源代码]#

基类：object

初始化网络管理类

参数:: parent – 父对象，通常是ZZUPy实例

get_online_devices() → OnlineDevices[源代码]#

获取全部在线设备

返回:: 在线设备列表
返回类型:: OnlineDevices

async get_online_devices_async() → OnlineDevices[源代码]#

异步获取全部在线设备

返回:: 在线设备列表
返回类型:: OnlineDevices

get_total_traffic() → int[源代码]#

获取消耗的流量

返回:: 消耗的流量，单位为 MB
返回类型:: int

async get_total_traffic_async() → int[源代码]#

异步获取消耗的流量

返回:: 消耗的流量，单位为 MB
返回类型:: int

get_used_time() → int[源代码]#

获取使用时间

返回:: 使用时间，单位为分钟
返回类型:: int

async get_used_time_async() → int[源代码]#

异步获取使用时间

返回:: 使用时间，单位为分钟
返回类型:: int

login(loginurl: str = 'http://10.2.7.16:8080', ua: str = None) → bool[源代码]#

登录自助服务平台

参数:

loginurl (str) – 自助服务平台的登录 URL
ua (str) – User Agent，默认随机生成

返回:

登录是否成功

返回类型:

bool

async login_async(loginurl: str = 'http://10.2.7.16:8080', ua: str = None) → bool[源代码]#

异步登录自助服务平台

参数:

loginurl (str) – 自助服务平台的登录 URL
ua (str) – User Agent，默认随机生成

返回:

登录是否成功

返回类型:

bool

logout_device(sessionid: str) → bool[源代码]#

注销指定设备

参数:: sessionid (str) – sessionid,可通过 get_online_devices() 获取
返回:: 成功或失败
返回类型:: bool

async logout_device_async(sessionid: str) → bool[源代码]#

异步注销指定设备

参数:: sessionid (str) – sessionid,可通过 get_online_devices_async() 获取
返回:: 成功或失败
返回类型:: bool

portal_auth(interface: str = None, authurl: str = 'http://10.2.7.8:801', ua: str = None, isp: str = 'campus') → Tuple[str, bool, str][源代码]#

进行校园网认证

参数:

interface (str) – 网络接口名
authurl (str) – PortalAuth 服务器。根据情况修改
ua (str) – User-Agent，默认随机生成
isp (str) – 运营商。可选项：campus,cm,ct,cu

返回:

Tuple[str, bool, str]

interface (str) – 本次认证调用的网络接口。
success (bool) – 认证是否成功。(不可信，有时失败仍可正常上网)
msg (str) – 服务端返回信息。

返回类型:

Tuple[str,bool,str]

async portal_auth_async(interface: str = None, authurl: str = 'http://10.2.7.8:801', ua: str = None, isp: str = 'campus') → Tuple[str, bool, str][源代码]#

异步进行校园网认证

参数:

interface (str) – 网络接口名
authurl (str) – PortalAuth 服务器。根据情况修改
ua (str) – User-Agent，默认随机生成
isp (str) – 运营商。可选项：campus,cm,ct,cu

返回:

Tuple[str, bool, str]

interface (str) – 本次认证调用的网络接口。
success (bool) – 认证是否成功。(不可信，有时失败仍可正常上网)
msg (str) – 服务端返回信息。

返回类型:

Tuple[str,bool,str]

zzupy.supwisdom module#

class zzupy.supwisdom.Supwisdom(parent)[源代码]#

基类：object

树维教务相关功能的类

初始化Supwisdom实例

参数:: parent – 父对象，通常是ZZUPy实例

get_biz_type_id() → int[源代码]#

获取账户默认业务类型 ID，用于区分本科生和研究生。

返回:: 返回默认业务类型 ID
返回类型:: int

get_courses(start_date: str, semester_id: str | int = None, biz_type_id: str | int = None) → Courses[源代码]#

获取课程表

参数:

start_date (str) – 课表的开始日期，格式必须为 YYYY-MM-DD ，且必须为某一周周一，否则课表会时间错乱
semester_id (str) – 学期ID
biz_type_id (str) – 业务类型 ID，用于区分本科生和研究生

返回:

返回课程表数据

返回类型:

Courses

抛出:

ValueError – 如果日期格式不正确
Exception – 如果API请求失败

async get_courses_async(start_date: str, semester_id: str | int = None, biz_type_id: str | int = None) → Courses[源代码]#

异步获取课程表

参数:

start_date (str) – 课表的开始日期，格式必须为 YYYY-MM-DD ，且必须为某一周周一，否则课表会时间错乱
semester_id (str) – 学期ID
biz_type_id (str) – 业务类型 ID，用于区分本科生和研究生

返回:

返回课程表数据

返回类型:

Courses

抛出:

ValueError – 如果日期格式不正确
Exception – 如果API请求失败

get_current_semester_id() → int[源代码]#

获取默认学期 ID

返回:: 返回学期 ID
返回类型:: int

get_current_week_courses(semester_id: str | int = None, biz_type_id: str | int = None) → Courses[源代码]#

获取本周课程表

参数:

semester_id (str) – 学期ID
biz_type_id (str) – 业务类型 ID，用于区分本科生和研究生

返回:

返回本周课程表数据

返回类型:

Courses

async get_current_week_courses_async(semester_id: str | int = None, biz_type_id: str | int = None) → Courses[源代码]#

异步获取本周课程表

参数:

semester_id (str) – 学期ID。
biz_type_id (str) – 业务类型 ID，用于区分本科生和研究生

返回:

返回本周课程表数据

返回类型:

Courses

get_room_data(building_id: int | str, date_str: str = '2025-05-22') → RoomOccupancyData[源代码]#

获取教室占用数据

参数:

building_id – 建筑ID
date_str – 日期字符串，格式为YYYY-MM-DD，默认为当天

返回:

返回教室占用数据

返回类型:

RoomOccupancyData

抛出:

Exception – 如果API请求失败

async get_room_data_async(building_id: int | str, date_str: str = '2025-05-22') → RoomOccupancyData[源代码]#

异步获取教室占用数据

参数:

building_id – 建筑ID
date_str – 日期字符串，格式为YYYY-MM-DD，默认为当天

返回:

返回教室占用数据

返回类型:

RoomOccupancyData

抛出:

Exception – 如果API请求失败

get_semester_data(biz_type_id: str | int = None) → SemesterData[源代码]#

获取学期数据

参数:: biz_type_id – 业务类型 ID，用于区分本科生和研究生。
返回:: 返回学期数据
返回类型:: SemesterData
抛出:: Exception – 如果API请求失败

async get_semester_data_async(biz_type_id: str | int = None) → SemesterData[源代码]#

异步获取学期数据

参数:: biz_type_id – 业务类型 ID，用于区分本科生和研究生。
返回:: 返回学期数据
返回类型:: SemesterData
抛出:: Exception – 如果API请求失败

get_today_courses(semester_id: str | int = None, biz_type_id: str | int = None) → Courses[源代码]#

获取今日课程表

参数:

semester_id (str) – 学期ID
biz_type_id (str) – 业务类型 ID，用于区分本科生和研究生

返回:

返回今日课程表数据

返回类型:

Courses

async get_today_courses_async(semester_id: str | int = None, biz_type_id: str | int = None) → Courses[源代码]#

异步获取今日课程表

参数:

semester_id (str) – 学期ID
biz_type_id (str) – 业务类型 ID，用于区分本科生和研究生

返回:

返回今日课程表数据

返回类型:

Courses

zzupy.typing module#

zzupy.utils module#

zzupy.utils.check_permission(self)[源代码]#

检查用户是否登录

参数:: self

zzupy.utils.dec_pwd(hex_string: str, key: int) → str[源代码]#: 解密函数：将十六进制字符串解密回原始密码

zzupy.utils.enc_pwd(pass_in: str, key: int) → str[源代码]#: 加密函数：将密码与密钥进行异或运算，并转为十六进制字符串

zzupy.utils.get_interface_by_ip(target_ip)[源代码]#

zzupy.utils.get_ip_by_interface(interface)[源代码]#

获取指定网卡的IP地址

参数:: interface – 网卡名称
返回:: 给定王卡的 IP 地址

zzupy.utils.get_key(ip: str = '') → int[源代码]#: 计算输入字符串的异或密钥

zzupy.utils.get_local_ip()[源代码]#

zzupy.utils.get_sign(dynamicSecret, params)[源代码]#

获取sign值

参数:

dynamicSecret (str) – login后自动获取，来自 login-token 请求
params (str) – URL请求参数

返回:

sign值

返回类型:

str

zzupy.utils.pkcs7_unpad(padded_data: bytes, block_size: int) → bytes[源代码]#

去除数据中的PKCS#7填充。

参数:

padded_data (bytes) – 带填充的数据
block_size (int) – 用于填充的块大小

返回:

去除填充后的数据

返回类型:

bytes

抛出:

ValueError – 如果填充无效

zzupy.utils.sm4_decrypt_ecb(ciphertext: bytes, key: bytes)[源代码]#

SM4 解密，ECB模式

参数:

ciphertext (bytes) – 密文
key (bytes) – 密钥

返回:

明文 Hex

返回类型:

str

zzupy.utils.sync_wrapper(async_func)[源代码]#: 将异步方法包装为同步方法的装饰器

Module contents#

class zzupy.ZZUPy(usercode: str, password: str, cookie: SimpleCookie | None = None)[源代码]#

基类：object

初始化一个 ZZUPy 对象

参数:

usercode (str) – 学号
password (str) – 密码
cookie (SimpleCookie) – 统一认证 Cookie。目前必须包含 ‘userToken’，否则会抛出 ValueError

抛出:

ValueError – Cookie 中缺少 ‘userToken’ 时抛出

get_user_token() → str[源代码]#: 获取本次会话的 userToken

property is_logged_in: bool#: 判断是否已登录

login(app_version: str = 'SWSuperApp/1.0.42', app_id: str = 'com.supwisdom.zzu', os_type: str = 'android') → LoginResult[源代码]#

参数:

app_version (str) – APP 版本，一般类似 “SWSuperApp/1.0.39” ，可自行更新版本号。
app_id (str) – APP 包名，一般不需要修改
os_type (str) – 系统类型，一般不需要修改

返回:

Tuple[str, str]

usercode (str) – 学号
name (str) – 姓名

返回类型:

Tuple[str,str]

抛出:

LoginException – 登录失败时抛出

async login_async(app_version: str = 'SWSuperApp/1.0.42', app_id: str = 'com.supwisdom.zzu', os_type: str = 'android') → LoginResult[源代码]#

参数:

app_version (str) – APP 版本，一般类似 “SWSuperApp/1.0.39” ，可自行更新版本号。
app_id (str) – APP 包名，一般不需要修改
os_type (str) – 系统类型，一般不需要修改

返回:

Tuple[str, str]

usercode (str) – 学号
name (str) – 姓名

返回类型:

Tuple[str,str]

抛出:

LoginException – 登录失败时抛出

set_device_params(**kwargs: Unpack[Dict[str, Any]]) → None[源代码]#

设置设备参数。这些参数都需要抓包获取，但其实可有可无，因为目前并没有观察到相关风控机制

参数:

deviceName (str) – 设备名，位于 “passwordLogin” 请求的 User-Agent 中，组成为 ‘{appVersion}({deviceName})’
deviceId (str) – 设备 ID ，
deviceInfo (str) – 设备信息，位于名为 “X-Device-Info” 的请求头中
deviceInfos (str) – 设备信息，位于名为 “X-Device-Infos” 的请求头中
userAgentPrecursor (str) – 设备 UA 前体，只需要包含 “SuperApp” 或 “uni-app Html5Plus/1.0 (Immersed/38.666668)” 前面的部分

zzupy package

目录

zzupy package#

Submodules#

zzupy.api module#

zzupy.ecard module#

zzupy.log module#

zzupy.network module#

zzupy.supwisdom module#

zzupy.typing module#

zzupy.utils module#

Module contents#