py-tiehu 0.1.0__tar.gz

py_tiehu-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 郭磊
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_tiehu-0.1.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: py-tiehu
+Version: 0.1.0
+Summary: PyTiehu 是铁虎停车场管理系统的 Python SDK，提供同步和异步两种调用方式，实现完整的请求签名机制，用于与铁虎停车场管理系统进行 API 交互。
+Author-email: Guolei <174000902@qq.com>
+License: MIT License
+        
+        Copyright (c) 2026 郭磊
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://gitee.com/guolei19850528/py_tiehu
+Project-URL: Repository, https://gitee.com/guolei19850528/py_tiehu.git
+Keywords: tiehu,python,client,api,铁虎,停车场
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: jsonpath-ng>=1.5.3
+Requires-Dist: jsonschema>=4.21.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: setuptools>=61.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# PyTiehu - 铁虎停车场 API Python SDK
+
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+PyTiehu 是铁虎停车场管理系统的 Python SDK，提供同步和异步两种调用方式，实现完整的请求签名机制，用于与铁虎停车场管理系统进行
+API 交互。
+
+## 功能特性
+
+- ✅ 自动生成请求签名（MD5 算法）
+- ✅ 支持同步/异步 HTTP 请求
+- ✅ 自动添加公共请求参数（parkingId、timestamp、sign）
+- ✅ 灵活的客户端配置选项
+- ✅ Pydantic 响应模型支持
+
+## 安装
+
+```bash
+pip install py_tiehu
+```
+
+## 快速开始
+
+### 同步客户端
+
+```python
+from py_tiehu import Pklot
+
+# 初始化客户端
+client = Pklot(
+    base_url="https://isc.example.com",
+    parking_id="park001",
+    app_key="your_app_secret"
+)
+
+# 发送请求
+response = client.request(
+    url="/api/v1/parking/query",
+    json={"plateNo": "京A12345"}
+)
+
+# 处理响应
+print(response.json())
+```
+
+### 异步客户端
+
+```python
+import asyncio
+from py_tiehu import Pklot
+
+# 初始化客户端
+client = Pklot(
+    base_url="https://isc.example.com",
+    parking_id="park001",
+    app_key="your_app_secret"
+)
+
+
+# 异步发送请求
+async def main():
+    response = await client.async_request(
+        url="/api/v1/parking/query",
+        json={"plateNo": "京A12345"}
+    )
+    print(response.json())
+
+
+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()`
+
+生成当前时间戳（毫秒）
+
+```python
+from py_tiehu.utils import timestamp
+
+ts = timestamp()  # 输出示例: 1630000000000
+```
+
+#### `json_find_first(expression, data)`
+
+使用 JSONPath 表达式从数据中查找第一个匹配项
+
+```python
+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 模型对象
+
+```python
+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 响应的基类：
+
+```python
+class Base(BaseModel):
+    status: Union[int, str]  # 错误码，1表示成功，非1表示失败
+    message: Optional[str]  # 错误信息描述
+```
+
+### STATUS_EQ_1
+
+成功响应模型：
+
+```python
+class STATUS_EQ_1(Base):
+    status: Literal[1, "1"]  # 成功，值为1
+    Data: Any  # 成功响应数据
+```
+
+## 配置说明
+
+### 默认配置
+
+```python
+{
+    "base_url": "<your_base_url>",
+    "verify": False,  # 禁用 SSL 证书验证
+    "timeout": 120  # 超时时间 120 秒
+}
+```
+
+### 自定义配置
+
+```python
+client = 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"}
+    }
+)
+```
+
+## 示例
+
+### 查询车辆信息
+
+```python
+response = client.request(
+    url="/api/v1/vehicle/query",
+    json={
+        "plateNo": "京A12345",
+        "parkingId": "park001"
+    }
+)
+```
+
+### 批量查询
+
+```python
+response = client.request(
+    url="/api/v1/vehicle/batch",
+    json={
+        "plateNos": ["京A12345", "京B67890"],
+        "pageIndex": 1,
+        "pageSize": 20
+    }
+)
+```
+
+## 主页
+
+[https://gitee.com/guolei19850528/py_tiehu](https://gitee.com/guolei19850528/py_tiehu)
+
+## 许可证
+
+MIT License
+
+## 开发

py_tiehu-0.1.0/README.md

@@ -0,0 +1,224 @@
+# PyTiehu - 铁虎停车场 API Python SDK
+
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+PyTiehu 是铁虎停车场管理系统的 Python SDK，提供同步和异步两种调用方式，实现完整的请求签名机制，用于与铁虎停车场管理系统进行
+API 交互。
+
+## 功能特性
+
+- ✅ 自动生成请求签名（MD5 算法）
+- ✅ 支持同步/异步 HTTP 请求
+- ✅ 自动添加公共请求参数（parkingId、timestamp、sign）
+- ✅ 灵活的客户端配置选项
+- ✅ Pydantic 响应模型支持
+
+## 安装
+
+```bash
+pip install py_tiehu
+```
+
+## 快速开始
+
+### 同步客户端
+
+```python
+from py_tiehu import Pklot
+
+# 初始化客户端
+client = Pklot(
+    base_url="https://isc.example.com",
+    parking_id="park001",
+    app_key="your_app_secret"
+)
+
+# 发送请求
+response = client.request(
+    url="/api/v1/parking/query",
+    json={"plateNo": "京A12345"}
+)
+
+# 处理响应
+print(response.json())
+```
+
+### 异步客户端
+
+```python
+import asyncio
+from py_tiehu import Pklot
+
+# 初始化客户端
+client = Pklot(
+    base_url="https://isc.example.com",
+    parking_id="park001",
+    app_key="your_app_secret"
+)
+
+
+# 异步发送请求
+async def main():
+    response = await client.async_request(
+        url="/api/v1/parking/query",
+        json={"plateNo": "京A12345"}
+    )
+    print(response.json())
+
+
+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()`
+
+生成当前时间戳（毫秒）
+
+```python
+from py_tiehu.utils import timestamp
+
+ts = timestamp()  # 输出示例: 1630000000000
+```
+
+#### `json_find_first(expression, data)`
+
+使用 JSONPath 表达式从数据中查找第一个匹配项
+
+```python
+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 模型对象
+
+```python
+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 响应的基类：
+
+```python
+class Base(BaseModel):
+    status: Union[int, str]  # 错误码，1表示成功，非1表示失败
+    message: Optional[str]  # 错误信息描述
+```
+
+### STATUS_EQ_1
+
+成功响应模型：
+
+```python
+class STATUS_EQ_1(Base):
+    status: Literal[1, "1"]  # 成功，值为1
+    Data: Any  # 成功响应数据
+```
+
+## 配置说明
+
+### 默认配置
+
+```python
+{
+    "base_url": "<your_base_url>",
+    "verify": False,  # 禁用 SSL 证书验证
+    "timeout": 120  # 超时时间 120 秒
+}
+```
+
+### 自定义配置
+
+```python
+client = 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"}
+    }
+)
+```
+
+## 示例
+
+### 查询车辆信息
+
+```python
+response = client.request(
+    url="/api/v1/vehicle/query",
+    json={
+        "plateNo": "京A12345",
+        "parkingId": "park001"
+    }
+)
+```
+
+### 批量查询
+
+```python
+response = client.request(
+    url="/api/v1/vehicle/batch",
+    json={
+        "plateNos": ["京A12345", "京B67890"],
+        "pageIndex": 1,
+        "pageSize": 20
+    }
+)
+```
+
+## 主页
+
+[https://gitee.com/guolei19850528/py_tiehu](https://gitee.com/guolei19850528/py_tiehu)
+
+## 许可证
+
+MIT License
+
+## 开发

py_tiehu-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+[project]
+name = "py-tiehu"
+version = "0.1.0"
+requires-python = ">=3.10"
+authors = [
+    { name = "Guolei", email = "174000902@qq.com" }
+]
+description = "PyTiehu 是铁虎停车场管理系统的 Python SDK，提供同步和异步两种调用方式，实现完整的请求签名机制，用于与铁虎停车场管理系统进行 API 交互。"
+keywords = ["tiehu", "python", "client", "api", "铁虎", "停车场"]
+license = { file = "LICENSE" }
+readme = "README.md"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0",
+    "jsonpath-ng>=1.5.3",
+    "jsonschema>=4.21.0",
+]
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "setuptools>=61.0",
+    "twine>=4.0",
+]
+
+[project.urls]
+"Homepage" = "https://gitee.com/guolei19850528/py_tiehu"
+"Repository" = "https://gitee.com/guolei19850528/py_tiehu.git"
+
+[tool.setuptools.packages.find]
+where = ["src"]

py_tiehu-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

py_tiehu-0.1.0/src/py_tiehu/__init__.py

@@ -0,0 +1,234 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+铁虎 停车场 API Python SDK
+
+提供同步和异步两种调用方式，实现完整的请求签名机制，
+用于与铁虎停车场管理系统进行 API 交互。
+
+主要功能：
+- 自动生成请求签名（MD5算法）
+- 支持同步/异步 HTTP 请求
+- 自动添加公共请求参数（parkingId、timestamp、sign）
+- 灵活的客户端配置选项
+"""
+
+import hashlib
+from typing import Optional
+
+import httpx
+
+from .utils import timestamp
+
+
+class Pklot:
+    """
+    铁虎停车场 API 客户端类
+
+    提供与铁虎 停车场管理系统交互的核心功能，
+    支持同步和异步两种请求模式，自动处理请求签名和公共参数。
+
+    Attributes:
+        base_url (str): 停车场管理系统 服务器基础 URL
+        parking_id (str): 停车场 ID，用于标识目标停车场
+        app_key (str): 应用密钥，用于生成请求签名
+        client_kwargs (dict): HTTP 客户端配置参数
+
+    Example:
+        # 同步客户端
+        sync_client = Pklot(
+            base_url="https://isc.example.com",
+            parking_id="park001",
+            app_key="your_app_secret"
+        )
+
+        # 异步客户端
+        async_client = Pklot(
+            base_url="https://isc.example.com",
+            parking_id="park001",
+            app_key="your_app_secret",
+            use_async_client=True
+        )
+    """
+
+    def __init__(
+            self,
+            base_url: Optional[str] = None,
+            parking_id: Optional[str] = None,
+            app_key: Optional[str] = None,
+            client_kwargs: Optional[dict] = None
+    ):
+        """
+        初始化 Pklot 客户端
+
+        Args:
+            base_url: 停车场管理系统 服务器基础 URL，如 "https://isc.example.com"
+            parking_id: 停车场 ID，由停车场 系统分配
+            app_key: 应用密钥，用于请求签名生成
+            client_kwargs: 传递给 httpx.Client 的额外配置参数
+
+        Note:
+            - base_url 末尾的斜杠会被自动移除
+            - client_kwargs 支持 httpx 客户端的所有配置选项
+            - 默认超时时间为 120 秒
+            - 默认禁用 SSL 证书验证（verify=False）
+        """
+        # 处理基础 URL，移除末尾斜杠
+        self.base_url = base_url or ""
+        self.base_url = self.base_url[:-1] if self.base_url.endswith("/") else self.base_url
+
+        # 存储核心配置参数
+        self.parking_id = parking_id or ""
+        self.app_key = app_key or ""
+        self.client_kwargs = client_kwargs or {}
+
+        self.client_kwargs = {
+            **{
+                "base_url": self.base_url,
+                "verify": False,
+                "timeout": 120,
+            },
+            **self.client_kwargs,
+        }
+
+    def client(self) -> httpx.Client:
+        """
+        创建并返回同步HTTP客户端
+
+        Returns:
+            httpx.Client: 配置好的同步HTTP客户端实例
+        """
+        return httpx.Client(**self.client_kwargs)
+
+    def async_client(self) -> httpx.AsyncClient:
+        """
+        创建并返回异步HTTP客户端
+
+        Returns:
+            httpx.AsyncClient: 配置好的异步HTTP客户端实例
+        """
+        return httpx.AsyncClient(**self.client_kwargs)
+
+    def signature(self, data: Optional[dict] = None) -> str:
+        """
+        生成请求签名，用于验证 API 请求的合法性和完整性
+
+        Args:
+            data: 需要签名的数据字典，包含 API 请求的参数
+
+        Returns:
+            str: 生成的 MD5 签名字符串（大写），用于 API 请求的 sign 参数
+
+        签名算法说明:
+            1. 排除数据中的 appKey 字段
+            2. 对剩余字段按键名进行升序排序
+            3. 将排序后的字段以 "key=value" 格式用 "&" 连接
+            4. 尾部拼接 appKey 的 MD5 值（大写）
+            5. 对拼接后的完整字符串进行 MD5 计算并转为大写
+
+        Example:
+            >>> client = Parking(parking_id="123", app_key="secret")
+            >>> sign = client.signature({"parkingId": "123", "timestamp": 1234567890})
+            >>> print(sign)  # 输出类似: A1B2C3D4E5F67890ABCDEF1234567890
+        """
+        # 确保 data 是字典类型，避免后续操作出错
+        data = data or {}
+        temp_string = ""
+
+        # 如果有数据需要签名
+        if len(data.keys()):
+            # 对字典键进行排序，确保签名的一致性（升序排列）
+            data_sorted = sorted(data.keys())
+            if isinstance(data_sorted, list):
+                # 构建待签名字符串，排除 appKey 字段
+                temp_string = "&".join([
+                    f"{i}={data[i]}"
+                    for i in data_sorted if i != "appKey"  # 排除 appKey 字段，避免重复签名
+                ]) + f"{hashlib.md5(self.app_key.encode('utf-8')).hexdigest().upper()}"
+
+        # 生成最终的 MD5 签名并转换为大写格式
+        return hashlib.md5(temp_string.encode('utf-8')).hexdigest().upper()
+
+    def request(self, client: Optional[httpx.Client] = None, **kwargs):
+        """
+        同步请求方法
+
+        自动添加公共请求参数（parkingId、timestamp、sign），
+        并生成请求签名，然后发送同步 HTTP 请求。
+
+        Args:
+            client: 可选的同步客户端实例，若不提供则使用内置客户端
+            **kwargs: 传递给 client.request 的额外参数，支持所有 httpx 参数
+
+        Returns:
+            httpx.Response: HTTP 响应对象
+
+        Example:
+            >>> client = Parking(base_url="https://isc.example.com", ...)
+            >>> response = client.request(url="/api/v1/parking/query", json={"plateNo": "京A12345"})
+            >>> print(response.json())
+        """
+        ts = timestamp()
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "method": "POST",
+                "json": {
+                    "parkingId": self.parking_id,  # 停车场 ID，必填公共参数
+                    "timestamp": ts,  # 时间戳，用于防止请求重放
+                    "sign": self.signature({  # 生成请求签名
+                        "parkingId": self.parking_id,
+                        "timestamp": ts,
+                    })
+                },
+            },
+            **kwargs
+        }
+        if isinstance(client, httpx.Client):
+            response = client.request(**kwargs)
+        else:
+            with self.client() as _client:
+                response = _client.request(**kwargs)
+        return response
+
+    async def async_request(self, client: Optional[httpx.AsyncClient] = None, **kwargs) -> httpx.Response:
+        """
+        异步请求方法
+
+        自动添加公共请求参数（parkingId、timestamp、sign），
+        并生成请求签名，然后发送异步 HTTP 请求。
+
+        Args:
+            client: 可选的异步客户端实例，若不提供则使用内置客户端
+            **kwargs: 传递给 client.request 的额外参数，支持所有 httpx 参数
+
+        Returns:
+            httpx.Response: HTTP 响应对象
+
+        Example:
+            >>> client = Parking(base_url="https://isc.example.com", use_async_client=True, ...)
+            >>> response = await client.async_request(url="/api/v1/parking/query", json={"plateNo": "京A12345"})
+            >>> print(response.json())
+        """
+        ts = timestamp()
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "method": "POST",
+                "json": {
+                    "parkingId": self.parking_id,  # 停车场 ID，必填公共参数
+                    "timestamp": ts,  # 时间戳，用于防止请求重放
+                    "sign": self.signature({  # 生成请求签名
+                        "parkingId": self.parking_id,
+                        "timestamp": ts,
+                    })
+                },
+            },
+            **kwargs
+        }
+        if isinstance(client, httpx.AsyncClient):
+            response = await client.request(**kwargs)
+        else:
+            async with self.async_client() as _client:
+                response = await _client.request(**kwargs)
+        return response

py_tiehu-0.1.0/src/py_tiehu/responses.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+from pydantic import BaseModel
+from pydantic import Field
+from typing import Literal, Union, Any, Optional
+
+
+class Base(BaseModel):
+    """
+    iSecure Center响应基类
+    
+    所有API响应都包含错误码和错误信息字段
+    """
+    status: Union[int, str] = Field(..., title="错误码", description="错误码，1表示成功，非1表示失败")
+    message: Optional[str] = Field(default=None, title="错误信息", description="错误信息描述")
+
+    model_config = {
+        "extra": "allow"  # 允许额外动态字段
+    }
+
+
+class STATUS_EQ_1(Base):
+    """
+    成功响应模型
+    
+    继承自Base，用于成功接口的响应
+    """
+    status: Literal[1, "1"] = Field(..., title="错误码", description="成功，值为1")
+    Data: Any = Field(title="数据", description="成功响应数据")

py_tiehu-0.1.0/src/py_tiehu/utils.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+from datetime import datetime
+from typing import Any, Optional, Union
+
+import httpx
+from jsonpath_ng import parse
+from jsonschema.validators import Draft202012Validator
+
+from .responses import STATUS_EQ_1
+
+
+def json_find_first(expression: str, data: Any) -> Any:
+    """
+    使用 JSONPath 表达式从数据中查找第一个匹配项
+
+    Args:
+        expression: JSONPath 表达式，用于指定要查找的数据路径
+        data: 待查询的 JSON 数据
+
+    Returns:
+        Any: 第一个匹配的值，如果没有匹配项则返回 None
+    """
+    results = [i.value for i in parse(expression).find(data)]
+    if isinstance(results, list) and len(results) > 0:
+        return results[0]
+    return None
+
+
+def json_is_valid(schema: Optional[dict], data: Any) -> bool:
+    """
+    校验 JSON 数据是否符合指定的 JSON Schema
+
+    Args:
+        schema: JSON Schema 字典
+        data: 待校验的 JSON 数据
+
+    Returns:
+        bool: 校验是否成功
+    """
+    return Draft202012Validator(schema).is_valid(data)
+
+
+def timestamp() -> int:
+    """
+    生成当前时间戳（毫秒）
+
+    返回:
+        int: 当前时间戳（毫秒），用于请求的时效性验证
+
+    示例:
+        >>> ts = utils.timestamp()
+        >>> print(ts)  # 输出示例: 1630000000000
+    """
+    return int((datetime.now().timestamp() * 1000))
+
+
+def convert_to_status_eq_1(response: Union[httpx.Response, dict]) -> STATUS_EQ_1:
+    """
+    将 HTTP 响应或字典转换为 STATUS_EQ_1 模型对象
+
+    统一处理 httpx.Response 对象和字典，将其转换为标准化的 STATUS_EQ_1 响应模型。
+
+    参数:
+        response (Union[httpx.Response, dict]): HTTP 响应对象或字典数据
+
+    返回:
+        STATUS_EQ_1: 标准化的响应模型对象，包含 status、message 和 Data 字段
+
+    处理逻辑:
+        - 如果输入是 httpx.Response 对象，先调用 json() 方法解析响应体
+        - 如果输入是字典，直接传入 STATUS_EQ_1 构造函数
+    """
+    if isinstance(response, httpx.Response):
+        return STATUS_EQ_1(**response.json())
+    return STATUS_EQ_1(**response)
+
+
+def status_eq_1_validator(
+        response: Union[httpx.Response, dict] = None,
+        schema: dict = {
+            "type": "object",
+            "properties": {
+                "status": {
+                    "oneOf": [
+                        {"type": "integer", "const": 1},
+                        {"type": "string", "const": "1"}
+                    ]
+                },
+            },
+            "required": ["status"]
+        }
+):
+    """
+    校验 HTTP 响应或字典是否符合指定的 JSON Schema
+
+    :param response: HTTP 响应对象或字典数据
+    :param schema: JSON Schema 字典
+    :return: 校验是否成功
+    """
+    if isinstance(response, httpx.Response):
+        return json_is_valid(schema, response.json())
+    return json_is_valid(schema, response)

py_tiehu-0.1.0/src/py_tiehu.egg-info/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: py-tiehu
+Version: 0.1.0
+Summary: PyTiehu 是铁虎停车场管理系统的 Python SDK，提供同步和异步两种调用方式，实现完整的请求签名机制，用于与铁虎停车场管理系统进行 API 交互。
+Author-email: Guolei <174000902@qq.com>
+License: MIT License
+        
+        Copyright (c) 2026 郭磊
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://gitee.com/guolei19850528/py_tiehu
+Project-URL: Repository, https://gitee.com/guolei19850528/py_tiehu.git
+Keywords: tiehu,python,client,api,铁虎,停车场
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: jsonpath-ng>=1.5.3
+Requires-Dist: jsonschema>=4.21.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: setuptools>=61.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# PyTiehu - 铁虎停车场 API Python SDK
+
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+PyTiehu 是铁虎停车场管理系统的 Python SDK，提供同步和异步两种调用方式，实现完整的请求签名机制，用于与铁虎停车场管理系统进行
+API 交互。
+
+## 功能特性
+
+- ✅ 自动生成请求签名（MD5 算法）
+- ✅ 支持同步/异步 HTTP 请求
+- ✅ 自动添加公共请求参数（parkingId、timestamp、sign）
+- ✅ 灵活的客户端配置选项
+- ✅ Pydantic 响应模型支持
+
+## 安装
+
+```bash
+pip install py_tiehu
+```
+
+## 快速开始
+
+### 同步客户端
+
+```python
+from py_tiehu import Pklot
+
+# 初始化客户端
+client = Pklot(
+    base_url="https://isc.example.com",
+    parking_id="park001",
+    app_key="your_app_secret"
+)
+
+# 发送请求
+response = client.request(
+    url="/api/v1/parking/query",
+    json={"plateNo": "京A12345"}
+)
+
+# 处理响应
+print(response.json())
+```
+
+### 异步客户端
+
+```python
+import asyncio
+from py_tiehu import Pklot
+
+# 初始化客户端
+client = Pklot(
+    base_url="https://isc.example.com",
+    parking_id="park001",
+    app_key="your_app_secret"
+)
+
+
+# 异步发送请求
+async def main():
+    response = await client.async_request(
+        url="/api/v1/parking/query",
+        json={"plateNo": "京A12345"}
+    )
+    print(response.json())
+
+
+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()`
+
+生成当前时间戳（毫秒）
+
+```python
+from py_tiehu.utils import timestamp
+
+ts = timestamp()  # 输出示例: 1630000000000
+```
+
+#### `json_find_first(expression, data)`
+
+使用 JSONPath 表达式从数据中查找第一个匹配项
+
+```python
+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 模型对象
+
+```python
+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 响应的基类：
+
+```python
+class Base(BaseModel):
+    status: Union[int, str]  # 错误码，1表示成功，非1表示失败
+    message: Optional[str]  # 错误信息描述
+```
+
+### STATUS_EQ_1
+
+成功响应模型：
+
+```python
+class STATUS_EQ_1(Base):
+    status: Literal[1, "1"]  # 成功，值为1
+    Data: Any  # 成功响应数据
+```
+
+## 配置说明
+
+### 默认配置
+
+```python
+{
+    "base_url": "<your_base_url>",
+    "verify": False,  # 禁用 SSL 证书验证
+    "timeout": 120  # 超时时间 120 秒
+}
+```
+
+### 自定义配置
+
+```python
+client = 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"}
+    }
+)
+```
+
+## 示例
+
+### 查询车辆信息
+
+```python
+response = client.request(
+    url="/api/v1/vehicle/query",
+    json={
+        "plateNo": "京A12345",
+        "parkingId": "park001"
+    }
+)
+```
+
+### 批量查询
+
+```python
+response = client.request(
+    url="/api/v1/vehicle/batch",
+    json={
+        "plateNos": ["京A12345", "京B67890"],
+        "pageIndex": 1,
+        "pageSize": 20
+    }
+)
+```
+
+## 主页
+
+[https://gitee.com/guolei19850528/py_tiehu](https://gitee.com/guolei19850528/py_tiehu)
+
+## 许可证
+
+MIT License
+
+## 开发

py_tiehu-0.1.0/src/py_tiehu.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/py_tiehu/__init__.py
+src/py_tiehu/responses.py
+src/py_tiehu/utils.py
+src/py_tiehu.egg-info/PKG-INFO
+src/py_tiehu.egg-info/SOURCES.txt
+src/py_tiehu.egg-info/dependency_links.txt
+src/py_tiehu.egg-info/requires.txt
+src/py_tiehu.egg-info/top_level.txt

py_tiehu-0.1.0/src/py_tiehu.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

py_tiehu-0.1.0/src/py_tiehu.egg-info/requires.txt

@@ -0,0 +1,10 @@
+httpx>=0.27.0
+pydantic>=2.0
+jsonpath-ng>=1.5.3
+jsonschema>=4.21.0
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0
+setuptools>=61.0
+twine>=4.0

py_tiehu-0.1.0/src/py_tiehu.egg-info/top_level.txt

@@ -0,0 +1 @@
+py_tiehu