easy-start-tiehu 0.1.2
一个用于铁虎停车系统集成的 Python 包，提供简洁易用的 API 接口。
Requires Python: >=3.6

# easy_start_tiehu

一个用于铁虎停车系统集成的Python包，提供简洁易用的API接口，支持与停车系统进行同步和异步交互。

## 功能特性

- 与铁虎停车系统API无缝集成
- 支持同步和异步两种请求方式
- 自动生成请求签名，确保数据安全
- 内置请求参数构建和响应验证
- 灵活的HTTP客户端配置选项
- 支持自定义超时和连接参数
- 内置JSON Schema响应验证，确保数据格式正确

## 安装方法

### 使用pip安装

```bash
pip install easy-start-tiehu
```

### 从源码安装

```bash
git clone https://gitee.com/guolei19850528/easy_start_tiehu.git
cd easy_start_tiehu
pip install -e .
```

## 快速开始

### 同步请求示例

```python
from easy_start_tiehu.pklot import Pklot

# 初始化客户端
pklot_client = Pklot(
    base_url="http://ykt.test.cxyun.net.cn:7303",  # 停车系统API地址
    parking_id="your_parking_id",                  # 停车场ID
    app_key="your_app_key"                         # API应用密钥
)

# 发送API请求
success, data, response = pklot_client.request(
    url="/api/parking/info",                       # API路径
    json={"carNumber": "京A12345"}                 # 请求参数
)

# 处理响应
if success:
    print("请求成功！")
    print(f"响应数据：{data}")
else:
    print("请求失败！")
    print(f"响应状态码：{response.status_code}")
    print(f"响应数据：{data}")
```

### 异步请求示例

```python
import asyncio
from easy_start_tiehu.pklot import Pklot

async def get_parking_info():
    # 初始化客户端
    pklot_client = Pklot(
        base_url="http://ykt.test.cxyun.net.cn:7303",
        parking_id="your_parking_id",
        app_key="your_app_key"
    )

    # 发送异步API请求
    success, data, response = await pklot_client.async_request(
        url="/api/parking/info",
        json={"carNumber": "京A12345"}
    )

    # 处理响应
    if success:
        print("异步请求成功！")
        print(f"响应数据：{data}")
    else:
        print("异步请求失败！")
        print(f"响应状态码：{response.status_code}")
        print(f"响应数据：{data}")

# 运行异步函数
asyncio.run(get_parking_info())
```

### 客户端复用示例

```python
from easy_start_tiehu.pklot import Pklot
import httpx

# 初始化客户端
pklot_client = Pklot(
    base_url="http://ykt.test.cxyun.net.cn:7303",
    parking_id="your_parking_id",
    app_key="your_app_key"
)

# 创建自定义客户端并复用
custom_client = httpx.Client(
    base_url=pklot_client.base_url,
    timeout=60,  # 自定义超时时间
    headers={"X-Custom-Header": "Value"}  # 自定义请求头
)

try:
    # 发送多个请求复用同一个客户端
    success1, data1, response1 = pklot_client.request(
        client=custom_client,
        url="/api/parking/info",
        json={"carNumber": "京A12345"}
    )
    
    success2, data2, response2 = pklot_client.request(
        client=custom_client,
        url="/api/parking/record",
        json={"carNumber": "京A12345"}
    )
finally:
    # 关闭客户端
    custom_client.close()
```

## API文档

### Pklot类

#### 初始化参数

```python
Pklot(
    base_url: str = "http://ykt.test.cxyun.net.cn:7303",
    parking_id: str = "",
    app_key: str = "",
)
```

- `base_url`: API基础URL，默认值为测试环境地址
- `parking_id`: 停车场ID，用于标识特定的停车场
- `app_key`: API应用密钥，用于生成请求签名，确保请求的安全性

#### 主要方法

##### client() - 创建同步HTTP客户端

```python
client(**kwargs)
```

- `**kwargs`: 传递给httpx.Client的额外参数，可用于覆盖默认配置

返回值: `httpx.Client` - 配置好基础URL和超时时间的同步HTTP客户端

##### async_client() - 创建异步HTTP客户端

```python
async_client(**kwargs)
```

- `**kwargs`: 传递给httpx.AsyncClient的额外参数，可用于覆盖默认配置

返回值: `httpx.AsyncClient` - 配置好基础URL和超时时间的异步HTTP客户端

##### signature() - 生成请求签名

```python
signature(data: dict = dict())
```

- `data`: 需要签名的数据字典，包含API请求的参数

返回值: `str` - 生成的MD5签名字符串（大写），用于API请求的sign参数

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

##### request() - 发送同步API请求

```python
request(
    client: httpx.Client = None,
    validate_json_schema: dict = {...},
    **kwargs
)
```

- `client`: 可选的HTTP客户端，如果不提供则创建新客户端
- `validate_json_schema`: 可选的JSON schema验证规则，用于验证响应格式
- `**kwargs`: 传递给client.request的额外参数，如url、headers等

返回值: `tuple` - (请求是否成功, 响应JSON数据, 原始响应对象)
- 请求是否成功: `bool`类型，根据响应的status字段判断
- 响应JSON数据: `dict`类型，API返回的JSON数据
- 原始响应对象: `httpx.Response`类型，包含完整的响应信息

##### async_request() - 发送异步API请求

```python
async_request(
    client: httpx.AsyncClient = None,
    validate_json_schema: dict = {...},
    **kwargs
)
```

参数与`request()`方法相同，但需要使用`await`关键字调用。

返回值: 与`request()`方法相同

## 依赖项

- [httpx](https://www.python-httpx.org/) - 用于发送HTTP请求
- [jsonschema](https://python-jsonschema.readthedocs.io/en/stable/) - 用于验证API响应的JSON格式

## 项目结构
```
easy_start_tiehu/
├── easy_start_tiehu/
│   ├── __init__.py
│   ├── pklot.py
├── requirements.txt
```
## 许可证

本项目采用MIT许可证。详见LICENSE文件。

## 作者信息

- 作者: guolei
- 邮箱: 174000902@qq.com
- 项目地址: https://gitee.com/guolei19850528/easy_start_tiehu