py-tiehu 0.1.1

PyTiehu 是铁虎停车场管理系统的 Python SDK，提供同步和异步两种调用方式，实现完整的请求签名机制，用于与铁虎停车场管理系统进行 API 交互。

py-tiehu - 铁虎停车场 API Python SDK

py-tiehu 是铁虎停车场管理系统的 Python SDK，提供同步和异步两种调用方式，实现完整的请求签名机制，用于与铁虎停车场管理系统进行 API 交互。

功能特性

• ✅ 自动生成请求签名（MD5 算法）
• ✅ 支持同步/异步 HTTP 请求
• ✅ 自动添加公共请求参数（parkingId、timestamp、sign）
• ✅ 灵活的客户端配置选项
• ✅ Pydantic 响应模型支持

安装

pip install py_tiehu

快速开始

同步客户端

from py_tiehu import Pklot
from py_tiehu.utils import convert_to_status_eq_1

# 初始化客户端
pklot_inst = Pklot(
    base_url="https://isc.example.com",
    parking_id="park001",
    app_key="your_app_secret"
)

# 发送请求
response = pklot_inst.request(
    url="/api/v1/parking/query",
    json={"plateNo": "京A12345"}
)

# 处理响应
print(convert_to_status_eq_1(response))

异步客户端

import asyncio
from py_tiehu import Pklot
from py_tiehu.utils import convert_to_status_eq_1

# 初始化客户端
pklot_inst = Pklot(
    base_url="https://isc.example.com",
    parking_id="park001",
    app_key="your_app_secret"
)


# 异步发送请求
async def main():
    response = await pklot_inst.async_request(
        url="/api/v1/parking/query",
        json={"plateNo": "京A12345"}
    )
    print(convert_to_status_eq_1(response))


asyncio.run(main())

API 文档

Pklot 类

初始化参数

参数	类型	必填	说明
base_url	str	是	停车场管理系统服务器基础 URL
parking_id	str	是	停车场 ID
app_key	str	是	应用密钥，用于生成请求签名
client_kwargs	dict	否	传递给 httpx.Client 的额外配置参数

方法

方法	说明	返回值
client()	创建同步 HTTP 客户端	httpx.Client
async_client()	创建异步 HTTP 客户端	httpx.AsyncClient
signature(data)	生成请求签名	str
request(**kwargs)	发送同步请求	httpx.Response
async_request(**kwargs)	发送异步请求	httpx.Response

签名算法

签名生成步骤：

1. 排除数据中的 appKey 字段
2. 对剩余字段按键名进行升序排序
3. 将排序后的字段以 key=value 格式用 & 连接
4. 尾部拼接 appKey 的 MD5 值（大写）
5. 对拼接后的完整字符串进行 MD5 计算并转为大写

工具函数

timestamp()

生成当前时间戳（毫秒）

from py_tiehu.utils import timestamp

ts = timestamp()  # 输出示例: 1630000000000

json_find_first(expression, data)

使用 JSONPath 表达式从数据中查找第一个匹配项

from py_tiehu.utils import json_find_first

result = json_find_first("$.data[0].name", response.json())

convert_to_status_eq_1(response)

将 HTTP 响应或字典转换为 STATUS_EQ_1 模型对象

from py_tiehu.utils import convert_to_status_eq_1

result = convert_to_status_eq_1(response)
print(result.status)  # 1
print(result.Data)  # 响应数据

响应模型

Base

所有 API 响应的基类：

class Base(BaseModel):
    status: Union[int, str]  # 错误码，1表示成功，非1表示失败
    message: Optional[str]  # 错误信息描述

STATUS_EQ_1

成功响应模型：

class STATUS_EQ_1(Base):
    status: Literal[1, "1"]  # 成功，值为1
    Data: Any  # 成功响应数据

配置说明

默认配置

{
    "base_url": "<your_base_url>",
    "verify": False,  # 禁用 SSL 证书验证
    "timeout": 120  # 超时时间 120 秒
}

自定义配置

from py_tiehu import Pklot

pklot_inst = Pklot(
    base_url="https://isc.example.com",
    parking_id="park001",
    app_key="your_app_secret",
    client_kwargs={
        "timeout": 60,
        "verify": True,
        "headers": {"X-Custom": "value"}
    }
)

示例

查询车辆信息

from py_tiehu import Pklot
from py_tiehu.utils import convert_to_status_eq_1

pklot_inst = Pklot(
    base_url="https://isc.example.com",
    parking_id="park001",
    app_key="your_app_secret",
    client_kwargs={
        "timeout": 60,
        "verify": True,
        "headers": {"X-Custom": "value"}
    }
)
response = pklot_inst.request(
    url="/api/v1/vehicle/query",
    json={
        "plateNo": "京A12345",
        "parkingId": "park001"
    }
)
print(convert_to_status_eq_1(response))

批量查询

from py_tiehu import Pklot
from py_tiehu.utils import convert_to_status_eq_1

pklot_inst = Pklot(
    base_url="https://isc.example.com",
    parking_id="park001",
    app_key="your_app_secret",
    client_kwargs={
        "timeout": 60,
        "verify": True,
        "headers": {"X-Custom": "value"}
    }
)
response = pklot_inst.request(
    url="/api/v1/vehicle/batch",
    json={
        "plateNos": ["京A12345", "京B67890"],
        "pageIndex": 1,
        "pageSize": 20
    }
)
print(convert_to_status_eq_1(response))

主页

https://gitee.com/guolei19850528/py_tiehu

许可证

MIT License

作者

[e-mail]