py-tiehu-sdk 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- py_tiehu_sdk-0.1.0/.env.example +14 -0
- py_tiehu_sdk-0.1.0/.gitee/ISSUE_TEMPLATE.zh-CN.md +13 -0
- py_tiehu_sdk-0.1.0/.gitee/PULL_REQUEST_TEMPLATE.zh-CN.md +12 -0
- py_tiehu_sdk-0.1.0/.gitignore +158 -0
- py_tiehu_sdk-0.1.0/.python-version +1 -0
- py_tiehu_sdk-0.1.0/LICENSE +21 -0
- py_tiehu_sdk-0.1.0/PKG-INFO +429 -0
- py_tiehu_sdk-0.1.0/README.md +418 -0
- py_tiehu_sdk-0.1.0/pyproject.toml +147 -0
- py_tiehu_sdk-0.1.0/scripts/debug_request.py +99 -0
- py_tiehu_sdk-0.1.0/scripts/quick_test.py +66 -0
- py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/__init__.py +80 -0
- py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/_version.py +13 -0
- py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/__init__.py +12 -0
- py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/base/__init__.py +55 -0
- py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/base/_config.py +84 -0
- py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/base/_exceptions.py +100 -0
- py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/base/_models.py +100 -0
- py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/base/_signature.py +122 -0
- py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/base/_sync_api.py +272 -0
- py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/downstream/__init__.py +21 -0
- py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/downstream/_sync_api.py +331 -0
- py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/provider.py +90 -0
- py_tiehu_sdk-0.1.0/tests/conftest.py +73 -0
- py_tiehu_sdk-0.1.0/tests/test_integration.py +71 -0
- py_tiehu_sdk-0.1.0/tests/test_models.py +62 -0
- py_tiehu_sdk-0.1.0/tests/test_provider.py +66 -0
- py_tiehu_sdk-0.1.0/tests/test_signature.py +74 -0
- py_tiehu_sdk-0.1.0/uv.lock +797 -0
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# TieHuo 道闸平台测试环境配置
|
|
2
|
+
# 复制为 .env 后填入真实值即可运行集成测试
|
|
3
|
+
|
|
4
|
+
# API 基础 URL(去掉 /interface 后缀)
|
|
5
|
+
PKLOT_BASE_URL=http://ykt.test.cxyun.net.cn:7303/cxzn
|
|
6
|
+
|
|
7
|
+
# 道闸平台分配的 appKey(明文,SDK 内部会 MD5 大写32位参与签名)
|
|
8
|
+
PKLOT_APP_KEY=b620f6be42328effc32b982a2b9
|
|
9
|
+
|
|
10
|
+
# 默认车场 ID(每次请求会自动注入)
|
|
11
|
+
PKLOT_PARKING_ID=5607116888606308222
|
|
12
|
+
|
|
13
|
+
# HTTP 请求超时(秒)
|
|
14
|
+
PKLOT_TIMEOUT=30.0
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# C extensions
|
|
7
|
+
*.so
|
|
8
|
+
|
|
9
|
+
# Distribution / packaging
|
|
10
|
+
.Python
|
|
11
|
+
build/
|
|
12
|
+
develop-eggs/
|
|
13
|
+
dist/
|
|
14
|
+
downloads/
|
|
15
|
+
eggs/
|
|
16
|
+
.eggs/
|
|
17
|
+
lib/
|
|
18
|
+
lib64/
|
|
19
|
+
parts/
|
|
20
|
+
sdist/
|
|
21
|
+
var/
|
|
22
|
+
wheels/
|
|
23
|
+
share/python-wheels/
|
|
24
|
+
*.egg-info/
|
|
25
|
+
.installed.cfg
|
|
26
|
+
*.egg
|
|
27
|
+
MANIFEST
|
|
28
|
+
|
|
29
|
+
# PyInstaller
|
|
30
|
+
# Usually these files are written by a python script from a template
|
|
31
|
+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
|
32
|
+
*.manifest
|
|
33
|
+
*.spec
|
|
34
|
+
|
|
35
|
+
# Installer logs
|
|
36
|
+
pip-log.txt
|
|
37
|
+
pip-delete-this-directory.txt
|
|
38
|
+
|
|
39
|
+
# Unit test / coverage reports
|
|
40
|
+
htmlcov/
|
|
41
|
+
.tox/
|
|
42
|
+
.nox/
|
|
43
|
+
.coverage
|
|
44
|
+
.coverage.*
|
|
45
|
+
.cache
|
|
46
|
+
nosetests.xml
|
|
47
|
+
coverage.xml
|
|
48
|
+
*.cover
|
|
49
|
+
*.py,cover
|
|
50
|
+
.hypothesis/
|
|
51
|
+
.pytest_cache/
|
|
52
|
+
cover/
|
|
53
|
+
|
|
54
|
+
# Translations
|
|
55
|
+
*.mo
|
|
56
|
+
*.pot
|
|
57
|
+
|
|
58
|
+
# Django stuff:
|
|
59
|
+
*.log
|
|
60
|
+
local_settings.py
|
|
61
|
+
db.sqlite3
|
|
62
|
+
db.sqlite3-journal
|
|
63
|
+
|
|
64
|
+
# Flask stuff:
|
|
65
|
+
instance/
|
|
66
|
+
.webassets-cache
|
|
67
|
+
|
|
68
|
+
# Scrapy stuff:
|
|
69
|
+
.scrapy
|
|
70
|
+
|
|
71
|
+
# Sphinx documentation
|
|
72
|
+
docs/_build/
|
|
73
|
+
|
|
74
|
+
# PyBuilder
|
|
75
|
+
.pybuilder/
|
|
76
|
+
target/
|
|
77
|
+
|
|
78
|
+
# Jupyter Notebook
|
|
79
|
+
.ipynb_checkpoints
|
|
80
|
+
|
|
81
|
+
# IPython
|
|
82
|
+
profile_default/
|
|
83
|
+
ipython_config.py
|
|
84
|
+
|
|
85
|
+
# pyenv
|
|
86
|
+
# For a library or package, you might want to ignore these files since the code is
|
|
87
|
+
# intended to run in multiple environments; otherwise, check them in:
|
|
88
|
+
# .python-version
|
|
89
|
+
|
|
90
|
+
# pipenv
|
|
91
|
+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
|
|
92
|
+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
|
|
93
|
+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
|
|
94
|
+
# install all needed dependencies.
|
|
95
|
+
#Pipfile.lock
|
|
96
|
+
|
|
97
|
+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow
|
|
98
|
+
__pypackages__/
|
|
99
|
+
|
|
100
|
+
# Celery stuff
|
|
101
|
+
celerybeat-schedule
|
|
102
|
+
celerybeat.pid
|
|
103
|
+
|
|
104
|
+
# SageMath parsed files
|
|
105
|
+
*.sage.py
|
|
106
|
+
|
|
107
|
+
# Environments
|
|
108
|
+
.env
|
|
109
|
+
.venv
|
|
110
|
+
env/
|
|
111
|
+
venv/
|
|
112
|
+
ENV/
|
|
113
|
+
env.bak/
|
|
114
|
+
venv.bak/
|
|
115
|
+
|
|
116
|
+
# Spyder project settings
|
|
117
|
+
.spyderproject
|
|
118
|
+
.spyproject
|
|
119
|
+
|
|
120
|
+
# Rope project settings
|
|
121
|
+
.ropeproject
|
|
122
|
+
|
|
123
|
+
# mkdocs documentation
|
|
124
|
+
/site
|
|
125
|
+
|
|
126
|
+
# mypy
|
|
127
|
+
.mypy_cache/
|
|
128
|
+
.dmypy.json
|
|
129
|
+
dmypy.json
|
|
130
|
+
|
|
131
|
+
# Pyre type checker
|
|
132
|
+
.pyre/
|
|
133
|
+
|
|
134
|
+
# pytype static type analyzer
|
|
135
|
+
.pytype/
|
|
136
|
+
|
|
137
|
+
# Cython debug symbols
|
|
138
|
+
cython_debug/
|
|
139
|
+
|
|
140
|
+
# ============================================================================
|
|
141
|
+
# macOS 系统文件
|
|
142
|
+
# ============================================================================
|
|
143
|
+
.DS_Store
|
|
144
|
+
.AppleDouble
|
|
145
|
+
.LSOverride
|
|
146
|
+
|
|
147
|
+
# ============================================================================
|
|
148
|
+
# Ruff / uv / hatchling 缓存
|
|
149
|
+
# ============================================================================
|
|
150
|
+
.ruff_cache/
|
|
151
|
+
.hatch/
|
|
152
|
+
|
|
153
|
+
# ============================================================================
|
|
154
|
+
# SDK 特定(不要提交测试环境变量和构建产物)
|
|
155
|
+
# ============================================================================
|
|
156
|
+
# .env.example 是模板,需要提交;但 .env 是本地真实配置,不要提交
|
|
157
|
+
.env
|
|
158
|
+
dist/
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
3.10
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 郭磊
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,429 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: py-tiehu-sdk
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: 铁虎道闸平台 Python SDK - 同步接口调用(官方文档: https://www.showdoc.com.cn/1735808258920310/9467753400037587)
|
|
5
|
+
Author-email: guolei <174000902@qq.com>
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Requires-Python: >=3.10
|
|
8
|
+
Requires-Dist: httpx[http2]>=0.27
|
|
9
|
+
Requires-Dist: pydantic>=2.7
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
|
|
12
|
+
# py_tiehu_sdk
|
|
13
|
+
|
|
14
|
+
> TieHuo 铁虎道闸平台 Python SDK — 同步接口调用
|
|
15
|
+
|
|
16
|
+
[](https://www.python.org/downloads/release/python-3100/)
|
|
17
|
+
[](LICENSE)
|
|
18
|
+
[](https://docs.astral.sh/uv/)
|
|
19
|
+
|
|
20
|
+
## 📖 项目简介
|
|
21
|
+
|
|
22
|
+
`py_tiehu_sdk` 是 [铁虎道闸平台](https://www.showdoc.com.cn/1735808258920310/9467753400037587) 的官方 Python SDK 封装,提供**自动签名**、**HTTP 请求发送**、**响应数据验证**、**异常统一处理**等开箱即用的能力。
|
|
23
|
+
|
|
24
|
+
### 核心特性
|
|
25
|
+
|
|
26
|
+
- 🔐 **自动签名** — 按道闸平台 6 步签名规则自动计算 sign,无需手动处理 MD5 拼接
|
|
27
|
+
- 🚀 **类型安全** — 完整的 Pydantic v2 数据模型 + mypy strict 类型检查
|
|
28
|
+
- 📦 **零样板** — 只需提供 `base_url` / `app_key` / `parking_id`,即可调用所有接口
|
|
29
|
+
- 🌐 **httpx 驱动** — 支持 HTTP/2、连接池复用、代理配置、自定义超时
|
|
30
|
+
- 🛠 **国际主流工具链** — uv 管理依赖、ruff 格式化/Lint、mypy 类型检查
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## 🧱 项目结构
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
py_tiehu_sdk/
|
|
38
|
+
├── pyproject.toml # uv + hatchling 配置,版本动态读取 _version.py
|
|
39
|
+
├── uv.lock # 依赖锁文件
|
|
40
|
+
├── src/
|
|
41
|
+
│ └── py_tiehu_sdk/
|
|
42
|
+
│ ├── __init__.py # ✅ 对外统一入口(Provider + Config + 异常 + 响应模型)
|
|
43
|
+
│ ├── _version.py # 版本号(pyproject.toml 动态读取)
|
|
44
|
+
│ ├── provider.py # ✅ PklotSyncAPIProvider — 对外统一访问入口
|
|
45
|
+
│ └── core/
|
|
46
|
+
│ └── pklot/
|
|
47
|
+
│ ├── base/
|
|
48
|
+
│ │ ├── __init__.py # ✅ 统一对外导出(Config / 异常 / 模型 / API 基类)
|
|
49
|
+
│ │ ├── _config.py # PklotConfig(SDK 全局配置,Pydantic)
|
|
50
|
+
│ │ ├── _exceptions.py # SDK 异常体系(PklotError 基类 + 5 种子类)
|
|
51
|
+
│ │ ├── _models.py # PklotBaseResponse + PklotCommonResponse
|
|
52
|
+
│ │ ├── _signature.py # 🔒 签名算法(内部,不对外暴露)
|
|
53
|
+
│ │ └── _sync_api.py # PklotSyncBaseAPI + PklotSyncAPI(请求处理器)
|
|
54
|
+
│ └── downstream/
|
|
55
|
+
│ ├── __init__.py # ✅ DownstreamSyncAPI 导出
|
|
56
|
+
│ └── _sync_api.py # DownstreamSyncAPI(13 个下行业务接口)
|
|
57
|
+
├── tests/
|
|
58
|
+
│ ├── conftest.py # pytest 配置 + .env 加载 + --integration 开关
|
|
59
|
+
│ ├── test_signature.py # 签名算法单元测试
|
|
60
|
+
│ ├── test_models.py # 响应模型单元测试
|
|
61
|
+
│ ├── test_provider.py # Provider 构造 + 签名注入测试
|
|
62
|
+
│ └── test_integration.py # 🔗 真实网络集成测试(需 --integration)
|
|
63
|
+
├── scripts/
|
|
64
|
+
│ ├── quick_test.py # 快速验证脚本(执行查询类接口并打印返回)
|
|
65
|
+
│ └── debug_request.py # Debug 脚本(打印签名计算细节)
|
|
66
|
+
├── .env.example # 测试环境配置模板
|
|
67
|
+
├── .ruff.toml # Ruff 配置(可选,也可写在 pyproject.toml)
|
|
68
|
+
└── LICENSE # MIT License
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### 目录分层设计
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
┌──────────────────────────────────────────────────────────────┐
|
|
75
|
+
│ py_tiehu_sdk/__init__.py ← 对外唯一入口 │
|
|
76
|
+
│ py_tiehu_sdk/provider.py ← Provider 统一入口 │
|
|
77
|
+
└──────────────────────────────────────────────────────────────┘
|
|
78
|
+
│
|
|
79
|
+
▼
|
|
80
|
+
┌──────────────────────────────────────────────────────────────┐
|
|
81
|
+
│ core/pklot/base/ 🔧 基础能力层 │
|
|
82
|
+
│ ├─ _config.py SDK 全局配置 │
|
|
83
|
+
│ ├─ _signature.py 🔒 签名算法(内部) │
|
|
84
|
+
│ ├─ _exceptions.py 异常定义 │
|
|
85
|
+
│ ├─ _models.py Pydantic 响应模型 │
|
|
86
|
+
│ └─ _sync_api.py 请求处理器(签名 + HTTP + 解析) │
|
|
87
|
+
└──────────────────────────────────────────────────────────────┘
|
|
88
|
+
│
|
|
89
|
+
▼
|
|
90
|
+
┌──────────────────────────────────────────────────────────────┐
|
|
91
|
+
│ core/pklot/downstream/ 📥 下行业务层 │
|
|
92
|
+
│ └─ _sync_api.py DownstreamSyncAPI — 13 个接口 │
|
|
93
|
+
└──────────────────────────────────────────────────────────────┘
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### 调用链路示意
|
|
97
|
+
|
|
98
|
+
```python
|
|
99
|
+
provider = PklotSyncAPIProvider(config)
|
|
100
|
+
resp = provider.downstream_sync_api.query_pklot()
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
PklotSyncAPIProvider(config)
|
|
105
|
+
│
|
|
106
|
+
├─ .base_sync_api = PklotSyncAPI(config)
|
|
107
|
+
│ └─ 持有 httpx.Client,负责签名 + 请求 + 响应解析
|
|
108
|
+
│
|
|
109
|
+
└─ .downstream_sync_api = DownstreamSyncAPI(base_sync_api)
|
|
110
|
+
└─ .query_pklot()
|
|
111
|
+
│
|
|
112
|
+
▼
|
|
113
|
+
base_sync_api._post_json("queryPklot", {})
|
|
114
|
+
│
|
|
115
|
+
├─ _build_signed_payload() 自动注入 parkingId / timestamp / sign
|
|
116
|
+
├─ httpx.Client.post() 发送 JSON POST
|
|
117
|
+
├─ PklotCommonResponse 解析响应 JSON
|
|
118
|
+
└─ raise_for_status() status != 1 抛 PklotAPIError
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## 📦 已实现的下行接口(13 个)
|
|
124
|
+
|
|
125
|
+
| 分组 | 方法名 | 接口路径 | 文档编号 | 说明 |
|
|
126
|
+
|:---|:---|:---|:---|:---|
|
|
127
|
+
| **车位查询** | `query_pklot()` | queryPklot | 1.0 | 获取车场车位信息 |
|
|
128
|
+
| | `get_parkinfo()` | getParkinfo | 2.1 | 获取车场详情 |
|
|
129
|
+
| | `get_park_device_state()` | getParkDeviceState | 3.3 | 获取设备在线状态 |
|
|
130
|
+
| **临停缴费** | `calculating_temp_cost()` | calculatingTempCost | 1.1 | 获取临停应缴金额 |
|
|
131
|
+
| | `pay_temp_cost()` | payTempCost | 1.2 | 支付通知道闸 |
|
|
132
|
+
| | `get_vehicle_information()` | getVehicleInformation | 4.4 | 查询车辆在场信息 |
|
|
133
|
+
| | `simulate_cla_fee()` | simulateClaFee | 4.3 | 模拟计算费用 |
|
|
134
|
+
| **车类/车型** | `get_park_car_type()` | getParkCarType | 1.3 | 获取车类列表 |
|
|
135
|
+
| | `get_park_car_model()` | getParkCarModel | 1.4 | 获取车型列表 |
|
|
136
|
+
| **闸机控制** | `open_gate()` | openGate | 2.5 | 远程开关闸 |
|
|
137
|
+
| | `get_park_gate()` | getParkGate | 2.4 | 获取通道列表 |
|
|
138
|
+
| **月卡管理** | `get_monthly_rent()` | getMonthlyRent | 2.8 | 车牌查月卡 |
|
|
139
|
+
| | `get_monthly_rent_list()` | getMonthlyRentList | 2.9 | 月卡列表分页 |
|
|
140
|
+
|
|
141
|
+
> **待扩展接口**(约 17 个):月卡增删改、黑名单管理、商家打折、访客、锁车、储值充值、车牌号修改、开票等。
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## 🚀 快速开始
|
|
146
|
+
|
|
147
|
+
### 前置要求
|
|
148
|
+
|
|
149
|
+
- Python **3.10 或更高**
|
|
150
|
+
- [uv](https://docs.astral.sh/uv/) 包管理器(推荐)或 pip
|
|
151
|
+
|
|
152
|
+
### 安装
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
# 方式一:通过 uv 安装(推荐)
|
|
156
|
+
uv add py-tiehu-sdk
|
|
157
|
+
|
|
158
|
+
# 方式二:通过 pip 安装
|
|
159
|
+
pip install py-tiehu-sdk
|
|
160
|
+
|
|
161
|
+
# 开发模式(本地开发)
|
|
162
|
+
git clone <repo-url> py_tiehu_sdk
|
|
163
|
+
cd py_tiehu_sdk
|
|
164
|
+
uv sync --dev
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### 配置环境变量
|
|
168
|
+
|
|
169
|
+
复制 `.env.example` 为 `.env`,填入你的道闸平台测试参数:
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
cp .env.example .env
|
|
173
|
+
# 然后编辑 .env 填入真实值
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
`.env` 内容示例:
|
|
177
|
+
|
|
178
|
+
```ini
|
|
179
|
+
# API 基础 URL(去掉 /interface 后缀)
|
|
180
|
+
PKLOT_BASE_URL=http://ykt.test.cxyun.net.cn:7303/cxzn
|
|
181
|
+
|
|
182
|
+
# 道闸平台分配的 appKey(明文,SDK 内部自动 MD5)
|
|
183
|
+
PKLOT_APP_KEY=b620f6be42328effc32b982a2b9
|
|
184
|
+
|
|
185
|
+
# 默认车场 ID
|
|
186
|
+
PKLOT_PARKING_ID=5607116888606308222
|
|
187
|
+
|
|
188
|
+
# HTTP 请求超时(秒)
|
|
189
|
+
PKLOT_TIMEOUT=30.0
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### 基本使用
|
|
193
|
+
|
|
194
|
+
```python
|
|
195
|
+
from py_tiehu_sdk import PklotSyncAPIProvider, PklotConfig
|
|
196
|
+
|
|
197
|
+
# 1. 创建配置(从 .env 读取,或直接硬编码)
|
|
198
|
+
config = PklotConfig(
|
|
199
|
+
base_url="http://ykt.test.cxyun.net.cn:7303/cxzn",
|
|
200
|
+
app_key="your_app_key_here",
|
|
201
|
+
parking_id="your_parking_id_here",
|
|
202
|
+
)
|
|
203
|
+
|
|
204
|
+
# 2. 创建 Provider(SDK 统一入口)
|
|
205
|
+
provider = PklotSyncAPIProvider(config)
|
|
206
|
+
|
|
207
|
+
# 3. 调用下行接口
|
|
208
|
+
resp = provider.downstream_sync_api.query_pklot()
|
|
209
|
+
|
|
210
|
+
# 4. 检查结果
|
|
211
|
+
if resp.ok:
|
|
212
|
+
print("✅ 成功!")
|
|
213
|
+
print(f" 总车位 : {resp.Data.get('totalLot')}")
|
|
214
|
+
print(f" 空闲车位 : {resp.Data.get('emptyLot')}")
|
|
215
|
+
else:
|
|
216
|
+
print(f"❌ 失败: {resp.message}")
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
### 更多接口调用示例
|
|
220
|
+
|
|
221
|
+
```python
|
|
222
|
+
# 车场详情
|
|
223
|
+
resp = provider.downstream_sync_api.get_parkinfo()
|
|
224
|
+
|
|
225
|
+
# 远程开闸(gate_id 从 get_park_gate 获取)
|
|
226
|
+
resp = provider.downstream_sync_api.open_gate(gate_id="G001", status=1)
|
|
227
|
+
|
|
228
|
+
# 根据车牌查询月卡
|
|
229
|
+
resp = provider.downstream_sync_api.get_monthly_rent(plate_number="湘A12345")
|
|
230
|
+
|
|
231
|
+
# 分页获取月卡列表(支持车牌模糊搜索 + 月卡类型过滤)
|
|
232
|
+
resp = provider.downstream_sync_api.get_monthly_rent_list(
|
|
233
|
+
page_index=1,
|
|
234
|
+
page_size=20,
|
|
235
|
+
plate_number="湘A", # 可选
|
|
236
|
+
rent_type=1, # 可选
|
|
237
|
+
)
|
|
238
|
+
|
|
239
|
+
# 根据停车时长(秒)模拟计算费用
|
|
240
|
+
resp = provider.downstream_sync_api.simulate_cla_fee(during_time=3600)
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
### 复用外部 httpx.Client(连接池复用)
|
|
244
|
+
|
|
245
|
+
```python
|
|
246
|
+
import httpx
|
|
247
|
+
from py_tiehu_sdk import PklotSyncAPIProvider, PklotConfig
|
|
248
|
+
|
|
249
|
+
# 手动管理 httpx.Client,适用于多 SDK 实例共享连接池
|
|
250
|
+
with httpx.Client(
|
|
251
|
+
proxies={"http://": "http://127.0.0.1:7890"}, # 代理
|
|
252
|
+
headers={"User-Agent": "my-app/1.0"},
|
|
253
|
+
) as client:
|
|
254
|
+
config = PklotConfig(
|
|
255
|
+
base_url="http://x.cxyun.net.cn:7303/cxzn",
|
|
256
|
+
app_key="xxx",
|
|
257
|
+
parking_id="yyy",
|
|
258
|
+
)
|
|
259
|
+
provider = PklotSyncAPIProvider(config, client=client)
|
|
260
|
+
resp = provider.downstream_sync_api.query_pklot()
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
---
|
|
264
|
+
|
|
265
|
+
## 🔑 签名算法
|
|
266
|
+
|
|
267
|
+
SDK 内部自动处理签名,调用方无需关心。签名规则(6 步):
|
|
268
|
+
|
|
269
|
+
```
|
|
270
|
+
原始 params
|
|
271
|
+
│ ① sort_params 过滤空值 + 按参数名 ASCII 升序
|
|
272
|
+
▼
|
|
273
|
+
排序后 params
|
|
274
|
+
│ ② 拼接 "key1=value1&key2=value2" → stringA
|
|
275
|
+
▼
|
|
276
|
+
stringA
|
|
277
|
+
│ ③ md5(appKey) → 大写 32 位 md5_app_key
|
|
278
|
+
▼
|
|
279
|
+
md5_app_key
|
|
280
|
+
│ ④ stringA + md5_app_key → stringSignTemp
|
|
281
|
+
▼
|
|
282
|
+
stringSignTemp
|
|
283
|
+
│ ⑤ md5 → 大写 32 位 → sign
|
|
284
|
+
▼
|
|
285
|
+
sign(最终结果)
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
### 自动注入的请求字段
|
|
289
|
+
|
|
290
|
+
每次 `_post_json` 调用会自动注入以下三个字段,**调用方不需要手动传入**:
|
|
291
|
+
|
|
292
|
+
| 字段 | 来源 | 值 |
|
|
293
|
+
|:---|:---|:---|
|
|
294
|
+
| `parkingId` | `config.parking_id` | 车场 ID |
|
|
295
|
+
| `timestamp` | `int(time.time() * 1000)` | 13 位毫秒时间戳(2 分钟内有效) |
|
|
296
|
+
| `sign` | `generate_sign()` 计算 | 大写 32 位签名 |
|
|
297
|
+
|
|
298
|
+
---
|
|
299
|
+
|
|
300
|
+
## 🧪 测试
|
|
301
|
+
|
|
302
|
+
### 运行单元测试(默认,不发真实网络请求)
|
|
303
|
+
|
|
304
|
+
```bash
|
|
305
|
+
uv run pytest -v
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
输出示例:
|
|
309
|
+
|
|
310
|
+
```
|
|
311
|
+
tests/test_signature.py::TestMd5Uppercase::test_basic PASSED
|
|
312
|
+
tests/test_models.py::TestPklotBaseResponse::test_ok_true_with_int PASSED
|
|
313
|
+
tests/test_provider.py::TestProvider::test_provider_creation PASSED
|
|
314
|
+
...
|
|
315
|
+
======================== 20 passed, 6 skipped in 0.08s =========================
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
### 运行集成测试(真实网络请求)
|
|
319
|
+
|
|
320
|
+
**前置**:
|
|
321
|
+
1. 复制 `.env.example` 为 `.env` 并填入真实值
|
|
322
|
+
2. 当前出口 IP 必须已在道闸平台白名单内(否则平台返回 `status=0, msg=不是白名单`)
|
|
323
|
+
|
|
324
|
+
```bash
|
|
325
|
+
uv run pytest --integration -v
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
### 快速验证脚本
|
|
329
|
+
|
|
330
|
+
```bash
|
|
331
|
+
# 执行查询类接口并打印完整返回
|
|
332
|
+
uv run python scripts/quick_test.py
|
|
333
|
+
|
|
334
|
+
# Debug 脚本 — 打印签名计算细节,用于排查签名不匹配问题
|
|
335
|
+
uv run python scripts/debug_request.py
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
### 代码质量检查
|
|
339
|
+
|
|
340
|
+
```bash
|
|
341
|
+
# Ruff 格式化 + Lint
|
|
342
|
+
uv run ruff check src tests --fix
|
|
343
|
+
|
|
344
|
+
# Mypy 类型检查(strict 模式)
|
|
345
|
+
uv run mypy src
|
|
346
|
+
|
|
347
|
+
# 构建发布包(自动从 _version.py 读取版本号)
|
|
348
|
+
uv build
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
---
|
|
352
|
+
|
|
353
|
+
## 📚 异常处理
|
|
354
|
+
|
|
355
|
+
SDK 定义了统一的异常体系,所有异常都继承自 `PklotError`:
|
|
356
|
+
|
|
357
|
+
```python
|
|
358
|
+
from py_tiehu_sdk import (
|
|
359
|
+
PklotError, # 所有 SDK 异常基类(可以统一捕获)
|
|
360
|
+
PklotAPIError, # 平台返回 status != 1 或 HTTP 错误
|
|
361
|
+
PklotSignatureError, # 签名生成失败(内部使用)
|
|
362
|
+
PklotTimeoutError, # 请求超时
|
|
363
|
+
PklotValidationError, # 响应 JSON 解析 / Pydantic 验证失败
|
|
364
|
+
)
|
|
365
|
+
|
|
366
|
+
try:
|
|
367
|
+
resp = provider.downstream_sync_api.query_pklot()
|
|
368
|
+
except PklotAPIError as e:
|
|
369
|
+
print(f"平台错误 [{e.status}]: {e.message}")
|
|
370
|
+
except PklotTimeoutError:
|
|
371
|
+
print("请求超时,可通过 PklotConfig(timeout=60) 增加超时时间")
|
|
372
|
+
except PklotValidationError as e:
|
|
373
|
+
print(f"响应格式异常: {e}")
|
|
374
|
+
print(f"原始数据: {e.raw_data}")
|
|
375
|
+
except PklotError as e:
|
|
376
|
+
print(f"SDK 通用错误: {e}")
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
---
|
|
380
|
+
|
|
381
|
+
## 🧰 工具链
|
|
382
|
+
|
|
383
|
+
| 工具 | 版本 | 用途 |
|
|
384
|
+
|:---|:---|:---|
|
|
385
|
+
| **uv** | ≥ 0.5 | 依赖管理 + 虚拟环境 + 构建 |
|
|
386
|
+
| **ruff** | ≥ 0.5 | 格式化(替代 black)+ Lint(替代 flake8 + isort)|
|
|
387
|
+
| **mypy** | ≥ 1.10 | strict 模式类型检查 |
|
|
388
|
+
| **hatchling** | — | 构建后端(支持动态版本)|
|
|
389
|
+
| **pytest** | ≥ 8 | 单元测试 + 集成测试 |
|
|
390
|
+
| **pydantic** | ≥ 2.7 | 数据验证 + 序列化 |
|
|
391
|
+
| **httpx** | ≥ 0.27 | HTTP 客户端(支持 HTTP/2)|
|
|
392
|
+
| **python-dotenv** | ≥ 1.2 | 加载 `.env` 配置(dev 依赖)|
|
|
393
|
+
|
|
394
|
+
---
|
|
395
|
+
|
|
396
|
+
## 🔐 安全说明
|
|
397
|
+
|
|
398
|
+
- **appKey 明文存储** — SDK 内部会自动 MD5 转大写后参与签名,调用方无需任何加密处理
|
|
399
|
+
- **HTTPS** — 建议使用 `https://` 开头的 API 地址,避免 appKey 在明文传输中被劫持
|
|
400
|
+
- **IP 白名单** — 道闸平台默认校验请求来源 IP,需要在平台管理后台配置白名单
|
|
401
|
+
- **签名有效期** — timestamp 对应的毫秒时间戳与道闸服务器时间差不能超过 2 分钟
|
|
402
|
+
- **不暴露签名工具** — `generate_sign`、`md5_uppercase`、`sort_params` 为内部方法,不通过 `__init__.py` 对外暴露
|
|
403
|
+
|
|
404
|
+
---
|
|
405
|
+
|
|
406
|
+
## 📄 版本管理
|
|
407
|
+
|
|
408
|
+
版本号统一在 `src/py_tiehu_sdk/_version.py` 中维护:
|
|
409
|
+
|
|
410
|
+
```python
|
|
411
|
+
__version__ = "0.1.0"
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
`pyproject.toml` 通过 hatchling 动态读取,**无需**两处重复修改:
|
|
415
|
+
|
|
416
|
+
```toml
|
|
417
|
+
[project]
|
|
418
|
+
dynamic = ["version"]
|
|
419
|
+
|
|
420
|
+
[tool.hatch.version]
|
|
421
|
+
path = "src/py_tiehu_sdk/_version.py"
|
|
422
|
+
expression = "__version__"
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
---
|
|
426
|
+
|
|
427
|
+
## 📜 License
|
|
428
|
+
|
|
429
|
+
本项目基于 [MIT License](LICENSE) 开源。
|