py-tiehu-sdk
铁虎道闸平台 Python SDK。提供 32 个完整业务接口的签名 + HTTP 封装,支持同步调用。
官方接口文档:https://www.showdoc.com.cn/1735808258920310/9467753400037587
功能特性
| 特性 | 说明 |
|---|---|
| ✅ 完整接口覆盖 | 32 个下行接口:车位、车类、闸机、临停、月卡、储值、访客、黑名单、商家、锁车 |
| ✅ 自动签名 | 6 步签名规则(parkingId + timestamp + appKey + params 按 ASCII 排序 + MD5 大写) |
| ✅ 签名排除 | applicationId 等字段按平台规则自动排除出签名 |
| ✅ 响应模型 | Pydantic BaseModel,resp.ok() 判断成功,resp.Data 承载业务数据 |
| ✅ 不自动抛异常 | status=2(如"车辆不在场")为正常业务状态,由调用方判断 |
| ✅ 异常透传 | HTTP/网络异常透传 httpx,响应结构异常透传 pydantic.ValidationError |
| ✅ 测试分级 | query 默认执行、modify 需显式 --run-modify 避免误操作线上数据 |
安装
pip install py-tiehu-sdk
# 或
uv add py-tiehu-sdk
最低支持 Python 3.10。
快速开始
from py_tiehu_sdk.provider import PklotAPIProvider, PklotAPIConfig
config = PklotAPIConfig(
base_url="http://ykt.test.cxyun.net.cn:7303/cxzn",
app_key="your_app_key",
parking_id="your_parking_id",
)
provider = PklotAPIProvider(config)
# 车位总览
resp = provider.downstream_api.query_pklot()
print(f"车场: {resp.Data.get('parkingId')}, 总车位: {resp.Data.get('totalLot')}, 空闲: {resp.Data.get('emptyLot')}")
# 闸机列表
resp = provider.downstream_api.get_park_gate()
for gate in resp.Data:
print(f" {gate['gateName']}: iostate={gate['iostate']}")
# 车辆在场查询
resp = provider.downstream_api.get_vehicle_information(plate_number="湘A12345")
if resp.ok():
print(f"入场时间: {resp.Data.get('startTime')}")
elif resp.status == 2:
print("车辆不在场(正常业务状态)")
else:
print(f"查询失败: {resp.message}")
项目结构
py_tiehu_sdk/
├── README.md
├── pyproject.toml
├── .env.example # 测试环境变量模板
├── tests/
│ ├── conftest.py # pytest 配置 + .env 加载 + query/modify 分类
│ ├── test_provider.py # Provider / Config / 签名单元测试
│ ├── test_signature.py # 签名算法单元测试
│ ├── test_models.py # 响应模型单元测试
│ └── test_integration.py # 32 个集成测试(query 默认执行,modify 需 --run-modify)
└── src/py_tiehu_sdk/
├── __init__.py # 只导出 provider + __version__
├── _version.py # 版本号(pyproject.toml 动态读取)
├── provider.py # ★ 主入口:PklotAPIProvider + 所有公共类导出
└── core/pklot/
├── base/
│ ├── api.py # PklotBaseAPI(签名 + HTTP POST + 响应解析)
│ ├── config.py # PklotAPIConfig(base_url / app_key / parking_id / timeout)
│ ├── models.py # PklotCommonResponse(status / message / Data / ok())
│ └── signature.py # generate_sign / md5_uppercase / sort_params(内部模块)
└── downstream/
└── api.py # ★ DownstreamAPI — 35 个业务方法
架构设计
PklotAPIProvider(PklotBaseAPI)
│
├─ .client = httpx.Client # 底层 HTTP client(继承自 BaseAPI)
├─ .config = PklotAPIConfig # 全局配置(继承自 BaseAPI)
├─ ._build_signed_payload() # 自动注入 parkingId / timestamp / sign
├─ ._post_json(endpoint, params) # 发送 JSON POST
│
└─ .downstream_api = DownstreamAPI(self) # 挂载的业务容器
│
└─ .base_api = PklotAPIProvider # 反向持有 Provider
└─ .query_pklot() / .open_gate() / ...
调用链路:provider.downstream_api.query_pklot() → DownstreamAPI.query_pklot() → self.base_api._post_json("queryPklot", {}) → PklotBaseAPI._post_json() → 签名 → httpx POST → 解析为 PklotCommonResponse。
API 接口分组
全部通过 provider.downstream_api.<method>() 调用。
车位查询(3 个)
| 方法 | Endpoint | 说明 |
|---|---|---|
query_pklot() |
queryPklot | 车位总览(总车位 / 空闲车位 / 区域列表) |
get_parkinfo() |
getParkinfo | 车场详情(名称 / 车位 / 收费规则 / 地址) |
get_park_device_state() |
getParkDeviceState | 设备在线状态(掉线 / 在线) |
车类车型(2 个)
| 方法 | Endpoint | 说明 |
|---|---|---|
get_park_car_type() |
getParkCarType | 车类列表(月租车 / 储值车 / 临时车 等) |
get_park_car_model() |
getParkCarModel | 车型列表(小车 / 大车 / 新能源车 等) |
闸机控制(3 个)
| 方法 | Endpoint | 说明 |
|---|---|---|
get_park_gate() |
getParkGate | 通道列表(只读查询) |
open_gate(gate_id, status) |
openGate | 远程开闸 |
no_plate_qrcode(lane_no, open_id) |
noPlateQrcode | 无牌车扫码放行 |
临停缴费(4 个)
| 方法 | Endpoint | 说明 |
|---|---|---|
calculating_temp_cost(plate_number, application_id) |
calculatingTempCost | 计算临停应缴金额 |
pay_temp_cost(...) |
payTempCost | 支付成功后通知道闸放车 |
get_vehicle_information(plate_number) |
getVehicleInformation | 查询车辆在场信息 |
simulate_cla_fee(during_time) |
simulateClaFee | 根据时长(分钟)模拟计算费用 |
月卡储值(7 个)
| 方法 | Endpoint | 说明 |
|---|---|---|
pay_monthly(...) |
payMonthly | 月卡续费 |
save_monthly_rent(...) |
saveMonthlyRent | 月卡新增 |
del_monthly_rent(plate_number) |
delMonthlyRent | 月卡删除(按月卡号) |
get_monthly_rent(plate_number) |
getMonthlyRent | 查询车牌月卡信息 |
get_monthly_rent_list(page_index, page_size) |
getMonthlyRentList | 月卡列表分页 |
del_monthly_rent_list(plate_numbers) |
delMonthlyRentList | 批量删除月卡 |
recharge_stored_value(...) |
rechargeStoredValue | 储值卡充值 |
访客(2 个)
| 方法 | Endpoint | 说明 |
|---|---|---|
add_visit(...) |
addVisit | 新增访客 |
delete_visit(plate_number) |
deleteVisit | 删除访客 |
黑名单(3 个)
| 方法 | Endpoint | 说明 |
|---|---|---|
add_park_black(...) |
addParkBlack | 黑名单新增 |
del_park_blacklist(plate_number) |
delParkBlacklist | 黑名单删除 |
get_park_black_list(plate_number, page_index, page_size) |
getParkBlackList | 黑名单分页查询 |
商家(5 个)
| 方法 | Endpoint | 说明 |
|---|---|---|
discount_rules(seller_no, pwd) |
discountRules | 商家打折规则 |
discount_pay(...) |
discountPay | 商家打折支付 |
seller_charge(seller_id, money) |
sellerCharge | 商家收款 |
seller_charge_list(seller_id, parking_nume) |
sellerChargeList | 商家收款记录查询 |
get_park_seller_list(page_index, page_size) |
getParkSellerList | 车场商家列表 |
其他辅助(3 个)
| 方法 | Endpoint | 说明 |
|---|---|---|
lock_car(plate_number) |
lockCar | 车场锁车 |
upate_plate_info(...) |
upatePlateInfo | 更新车牌信息 |
parking_invoice(...) |
parkingInvoice | 获取停车发票 |
响应模型
所有接口返回 PklotCommonResponse:
class PklotCommonResponse:
status: int | str # 1=成功, 2=正常业务状态, 0=失败
message: str # 消息
Data: dict | list | None # 业务数据
def ok(self) -> bool: # status == 1 时为 True
...
道闸平台 status 语义:
| status | 含义 | 处理方式 |
|---|---|---|
| 1 | 成功 | 正常读取 resp.Data |
| 2 | 正常业务状态(车辆不在场、不是月卡车 等) | 按业务逻辑处理,不算异常 |
| 0 | 失败(参数错误、白名单、网络) | 通过 resp.message 排查 |
SDK 不自动抛异常。推荐调用模式:
resp = provider.downstream_api.get_monthly_rent(plate_number="测试00001")
if resp.ok():
print(f"月卡信息: {resp.Data}")
elif resp.status == 2:
print("该车牌不是月卡车(正常业务状态)")
else:
print(f"查询失败: {resp.message}")
异常处理
SDK 不定义自定义异常类,网络/HTTP/解析异常直接透传给调用方:
| 异常来源 | 触发场景 | 处理建议 |
|---|---|---|
httpx.TimeoutException |
请求超时(超过 config.timeout 秒) |
检查网络或调大 timeout |
httpx.ConnectError / httpx.ConnectTimeout |
无法连接到道闸平台 | 检查 base_url、出口 IP 白名单 |
httpx.HTTPStatusError |
HTTP 状态码非 2xx | 通常是网关或平台内部错误 |
pydantic.ValidationError |
平台返回的 JSON 不符合预期结构 | 检查接口文档或联系道闸方 |
业务层 status != 1 不会抛异常,由调用方通过 resp.ok() + resp.message 自行判断。
测试
运行方式
# 默认:只跑单元测试(18 个)
pytest
# 跑集成测试 + 查询类(15 个 query,真实网络请求)
pytest --integration -m query
# 跑集成测试 + 查询类 + 修改类(⚠️ 会调用 open_gate / add_park_black 等写操作)
pytest --integration --run-modify
测试分类
| 分类 | Marker | 默认行为 | 数量 |
|---|---|---|---|
| 单元测试 | 无 | 始终执行 | 18 |
| 集成测试 - query | integration -m query |
需 --integration |
15 |
| 集成测试 - modify | integration -m modify |
需 --integration --run-modify |
17 |
.env 配置
集成测试通过 .env 加载真实车场参数:
cp .env.example .env
# 填入测试车场参数
PKLOT_BASE_URL=http://your-park.cxyun.net.cn:7303/cxzn
PKLOT_APP_KEY=your_app_key
PKLOT_PARKING_ID=your_parking_id
外部调用入口
所有公共类统一从 py_tiehu_sdk.provider 导入:
from py_tiehu_sdk.provider import (
PklotAPIProvider, # 主入口
PklotAPIConfig, # 配置
DownstreamAPI, # 业务容器(provider.downstream_api 的类型)
PklotCommonResponse, # 响应模型
PklotBaseResponse,
)
根包 py_tiehu_sdk.__version__ 可单独导入:
from py_tiehu_sdk import __version__
版本历史
v0.3.3 (2026-11-19)
- 删除自定义异常体系(
exceptions.py),HTTP/网络异常透传httpx,响应结构异常透传pydantic.ValidationError PklotBaseResponse.ok从@property改为普通方法ok()- 移除
raise_for_status()方法 - 删除
scripts/调试脚本目录 - 同步更新 README、测试用例、provider docstring
v0.3.2 (2026-11-19)
- README 重新生成:完整架构图 + 35 接口分组表
v0.3.1 (2026-11-18)
- 重构:文件去掉
_前缀(_api.py→api.py等) - 重构:
PklotAPIProvider继承PklotBaseAPI,自身具备签名 + HTTP 能力 - 重构:
__init__.py瘦身,所有公共类统一从py_tiehu_sdk.provider导入 - 统一注释风格为 py_wecom_sdk 风格
v0.2.1 / v0.2.2
- 新增签名排除参数
sign_exclude(applicationId不参与签名) PklotConfig→PklotAPIConfig- 移除自动抛异常,保留
status=2正常业务状态
v0.1.0
- 初始版本
- 32 个下行接口完整实现
Metadata
Release files for py-tiehu-sdk 0.3.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| py_tiehu_sdk-0.3.3.tar.gz | 83.4 kB | Without provenance | Details for py_tiehu_sdk-0.3.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| py_tiehu_sdk-0.3.3-py3-none-any.whl | Python 3 | none | any | Details for py_tiehu_sdk-0.3.3-py3-none-any.whl |
Total release size: 109.0 kB
Release files / py_tiehu_sdk-0.3.3.tar.gz
| Download URL | py_tiehu_sdk-0.3.3.tar.gz |
|---|---|
| Size | 83.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b932285edae08039d1528f46d9edceff9b5920a52f7396ba159ee5538f80db76
|
|
BLAKE2b-256 checksum How to use checksums |
f4ec20d9d83bad375e47de64f60ff6a694221d0b126d98cad4f20a4c4f9f519a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.22
|
Release files / py_tiehu_sdk-0.3.3-py3-none-any.whl
| Download URL | py_tiehu_sdk-0.3.3-py3-none-any.whl |
|---|---|
| Size | 25.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
39acd8801049f21f3fcab9aea2b3c6de474e030309ab422301bf1128fd0d781b
|
|
BLAKE2b-256 checksum How to use checksums |
0178323ff25674d4090e2c8db6e0607eb6b82cabbdcf369dfc64959f90ff2786
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.22
|
Security for py-tiehu-sdk 0.3.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.