Metadata-Version: 2.4
Name: pytiehu_parking
Version: 1.0.1
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 签名）
- JSON Schema 响应校验
- JSONPath 数据提取
- 支持自定义 HTTP 客户端配置

## 安装方式

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

或者从源码安装：

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

## 依赖项

- `httpx` - HTTP 客户端（同步和异步）
- `jsonschema` - JSON Schema 校验
- `decorator` - 装饰器支持
- `jsonpath-ng` - 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(
    method="POST",
    url="/api/path",
    json={"param1": "value1"}
)

# 处理响应
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",
        is_async=True
    )

    # 发送异步请求
    response = await client.async_request(
        method="POST",
        url="/api/path",
        json={"param1": "value1"}
    )

    # 处理响应
    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 客户端配置参数 |
| is_async | 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`

异步请求方法。

### 工具函数

#### `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"}
    }
)
```

## 许可证

MIT License

## 作者

guolei <174000902@qq.com>

## 项目地址

https://gitee.com/guolei19850528/pytiehu_parking
