Metadata-Version: 2.4
Name: pytiehu_parking
Version: 2.0.0
Summary: 铁虎 停车 API 的 Python SDK，支持同步和异步两种调用方式，提供完整的请求签名机制。
Home-page: https://gitee.com/guolei19850528/pytiehu_parking
Author: guolei
Author-email: 174000902@qq.com
License: MIT
Keywords: 铁虎 停车 API Python SDK
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx
Requires-Dist: jsonschema
Requires-Dist: decorator
Requires-Dist: jsonpath-ng
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# pytiehu_parking

铁虎 停车场 API 的 Python SDK，支持同步和异步两种调用方式，提供完整的请求签名机制。

## 功能特性

- **双模式支持**：同时支持同步和异步 HTTP 请求
- **自动签名**：完整的 MD5 请求签名机制，自动处理签名生成
- **参数自动注入**：自动添加 parkingId、timestamp、sign 等公共参数
- **灵活配置**：支持自定义 HTTP 客户端配置（超时、SSL 验证等）
- **响应处理**：提供 JSON Schema 校验和 JSONPath 数据提取工具

## 安装方式

```bash
pip install pytiehu-parking
```

或者从源码安装：

```bash
git clone https://gitee.com/guolei19850528/pytiehu_parking.git
cd pytiehu_parking
pip install .
```

## 依赖项

| 依赖包 | 版本要求 | 说明 |
|--------|----------|------|
| httpx | latest | HTTP 客户端（支持同步/异步） |
| jsonschema | latest | JSON Schema 校验 |
| jsonpath-ng | latest | JSONPath 数据提取 |

## 快速开始

### 同步调用

```python
from pytiehu_parking import Parking

# 创建同步客户端
client = Parking(
    base_url="https://your-isc-server.com",
    parking_id="your_parking_id",
    app_key="your_app_key"
)

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

# 处理响应
data = response.json()
print(data)
```

### 异步调用

```python
import asyncio
from pytiehu_parking import Parking

async def main():
    # 创建异步客户端
    client = Parking(
        base_url="https://your-isc-server.com",
        parking_id="your_parking_id",
        app_key="your_app_key",
        use_async_client=True
    )

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

    # 处理响应
    data = response.json()
    print(data)

asyncio.run(main())
```

## API 文档

### Parking 类

#### 初始化参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| base_url | str | 是 | - | ISC 服务器基础 URL |
| parking_id | str | 是 | - | 停车场 ID |
| app_key | str | 是 | - | 应用密钥，用于签名生成 |
| client_kwargs | dict | 否 | {} | HTTP 客户端配置参数 |
| use_async_client | bool | 否 | False | 是否使用异步客户端 |

#### 方法

##### `signature(data: Optional[dict] = None) -> str`

生成请求签名，用于验证 API 请求的合法性和完整性。

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

##### `request(client: Optional[httpx.Client] = None, **kwargs)`

同步请求方法，自动添加公共参数并生成签名。

##### `async_request(client: Optional[httpx.AsyncClient] = None, **kwargs) -> httpx.Response`

异步请求方法，自动添加公共参数并生成签名。

### 工具函数

工具函数位于 `pytiehu_parking.utils` 模块：

#### `json_find_first(expression: str, data: Any) -> Any`

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

#### `json_is_valid(schema: Optional[dict], data: Any) -> bool`

校验 JSON 数据是否符合指定的 JSON Schema。

#### `get_request_result(response: Optional[Any] = None)`

从接口响应中提取数据，支持 `httpx.Response` 对象或直接的 JSON 数据字典。

## 示例

### 使用工具函数处理响应

```python
from pytiehu_parking import Parking
from pytiehu_parking.utils import get_request_result

client = Parking(
    base_url="https://your-isc-server.com",
    parking_id="your_parking_id",
    app_key="your_app_key"
)

response = client.request(url="/api/v1/parking/info")
data = get_request_result(response)
print(data)
```

### 自定义客户端配置

```python
from pytiehu_parking import Parking

client = Parking(
    base_url="https://your-isc-server.com",
    parking_id="your_parking_id",
    app_key="your_app_key",
    client_kwargs={
        "timeout": 60,
        "verify": True,
        "headers": {"X-Custom-Header": "value"}
    }
)
```

## 签名机制说明

请求签名是保障 API 调用安全的重要机制：

1. **时效性验证**：每次请求都会生成当前时间戳，服务器会验证请求的时效性
2. **完整性验证**：签名基于请求参数生成，防止参数被篡改
3. **身份验证**：签名使用 appKey 生成，验证请求来源的合法性

## 许可证

MIT License

## 作者

guolei <174000902@qq.com>

## 项目地址

https://gitee.com/guolei19850528/pytiehu_parking
