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.
Files changed (29) hide show
  1. py_tiehu_sdk-0.1.0/.env.example +14 -0
  2. py_tiehu_sdk-0.1.0/.gitee/ISSUE_TEMPLATE.zh-CN.md +13 -0
  3. py_tiehu_sdk-0.1.0/.gitee/PULL_REQUEST_TEMPLATE.zh-CN.md +12 -0
  4. py_tiehu_sdk-0.1.0/.gitignore +158 -0
  5. py_tiehu_sdk-0.1.0/.python-version +1 -0
  6. py_tiehu_sdk-0.1.0/LICENSE +21 -0
  7. py_tiehu_sdk-0.1.0/PKG-INFO +429 -0
  8. py_tiehu_sdk-0.1.0/README.md +418 -0
  9. py_tiehu_sdk-0.1.0/pyproject.toml +147 -0
  10. py_tiehu_sdk-0.1.0/scripts/debug_request.py +99 -0
  11. py_tiehu_sdk-0.1.0/scripts/quick_test.py +66 -0
  12. py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/__init__.py +80 -0
  13. py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/_version.py +13 -0
  14. py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/__init__.py +12 -0
  15. py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/base/__init__.py +55 -0
  16. py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/base/_config.py +84 -0
  17. py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/base/_exceptions.py +100 -0
  18. py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/base/_models.py +100 -0
  19. py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/base/_signature.py +122 -0
  20. py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/base/_sync_api.py +272 -0
  21. py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/downstream/__init__.py +21 -0
  22. py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/core/pklot/downstream/_sync_api.py +331 -0
  23. py_tiehu_sdk-0.1.0/src/py_tiehu_sdk/provider.py +90 -0
  24. py_tiehu_sdk-0.1.0/tests/conftest.py +73 -0
  25. py_tiehu_sdk-0.1.0/tests/test_integration.py +71 -0
  26. py_tiehu_sdk-0.1.0/tests/test_models.py +62 -0
  27. py_tiehu_sdk-0.1.0/tests/test_provider.py +66 -0
  28. py_tiehu_sdk-0.1.0/tests/test_signature.py +74 -0
  29. 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,13 @@
1
+ ### 该问题是怎么引起的?
2
+
3
+
4
+
5
+ ### 重现步骤
6
+
7
+
8
+
9
+ ### 报错信息
10
+
11
+
12
+
13
+
@@ -0,0 +1,12 @@
1
+ ### 相关的Issue
2
+
3
+
4
+ ### 原因(目的、解决的问题等)
5
+
6
+
7
+ ### 描述(做了什么,变更了什么)
8
+
9
+
10
+ ### 测试用例(新增、改动、可能影响的功能)
11
+
12
+
@@ -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
+ [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/release/python-3100/)
17
+ [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
18
+ [![Toolchain](https://img.shields.io/badge/uv-ruff-mypyt-4B8BBE?logo=python&logoColor=FFD43B)](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) 开源。