py-hikvision 0.1.0__tar.gz

py_hikvision-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_hikvision-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: py-hikvision
+Version: 0.1.0
+Summary: 一个用于与海康威视 iSecure Center (ISC) API 交互的 Python 客户端库。
+License-Expression: MIT
+Project-URL: Home, https://gitee.com/guolei19850528/py_hikvision
+Keywords: isc,hikvision,python,client,api,海康威视,iSecure Center
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: jsonpath-ng>=1.2.0
+Requires-Dist: jsonschema>=4.0.0
+Requires-Dist: twine>=6.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: build>=0.18.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# py_hikvision
+
+一个用于与海康威视 iSecure Center (ISC) API 交互的 Python 客户端库。
+
+## 功能特性
+
+- 🔐 **API 认证**: 支持 HMAC-SHA256 签名认证机制
+- 🚀 **同步/异步请求**: 支持同步和异步两种 HTTP 请求方式
+- 📋 **响应模型**: 使用 Pydantic 进行响应数据校验和解析
+- 🔧 **工具函数**: 提供时间戳、UUID、JSONPath 查询等实用工具
+
+## 安装
+
+```bash
+pip install py_hikvision
+```
+
+## 快速开始
+
+### 基本使用
+
+```python
+from py_hikvision.isc import Isc
+
+# 初始化客户端
+isc = Isc(
+    host="https://your-isc-server.com",
+    ak="your-access-key",
+    sk="your-secret-key"
+)
+
+# 发送同步请求
+response = isc.request(
+    method="POST",
+    url="/api/parking/info",
+    json={"plateNo": "京A12345"}
+)
+print(response.json())
+
+# 发送异步请求
+async def fetch_data():
+    response = await isc.async_request(
+        method="GET",
+        url="/api/parking/list"
+    )
+    return response.json()
+```
+
+## API 文档
+
+### Isc 类
+
+#### 初始化
+
+```python
+isc = Isc(
+    host: Optional[str] = None,      # ISC 服务器地址
+    ak: Optional[str] = None,        # Access Key
+    sk: Optional[str] = None,        # Secret Key
+    client_kwargs: Optional[dict] = None  # httpx 客户端配置
+)
+```
+
+#### 方法
+
+| 方法 | 说明 |
+|------|------|
+| `client()` | 创建同步 HTTP 客户端 |
+| `async_client()` | 创建异步 HTTP 客户端 |
+| `signature(string)` | 生成 HMAC-SHA256 签名 |
+| `headers(method, path, headers)` | 生成请求头（包含签名） |
+| `request(**kwargs)` | 发送同步请求 |
+| `async_request(**kwargs)` | 发送异步请求 |
+
+### 工具函数
+
+```python
+from py_hikvision.isc.utils import (
+    timestamp,           # 生成毫秒时间戳
+    nonce,              # 生成 UUID
+    json_find_first,    # JSONPath 查询
+    json_is_valid,      # JSON Schema 校验
+    url_add_artemis_prefix,  # 添加 Artemis 前缀
+    image_to_base64_and_md5, # 图片编码
+    convert_to_normal   # 转换为 Normal 模型
+)
+```
+
+## 响应模型
+
+```python
+from py_hikvision.isc.responses import Normal
+
+# 响应结构
+normal = Normal(
+    code=0,           # 错误码，0 表示成功
+    msg="success",    # 错误信息
+    data={...}        # 响应数据
+)
+```
+
+## 安全说明
+
+1. **签名机制**: 使用 HMAC-SHA256 算法确保请求完整性
+2. **防止重放攻击**: 通过 nonce（随机 UUID）和 timestamp（时间戳）实现
+3. **密钥管理**: Access Key 和 Secret Key 应妥善保管，避免泄露
+
+## 依赖
+
+- `httpx`: HTTP 客户端
+- `pydantic`: 数据验证
+- `jsonpath-ng`: JSONPath 查询
+- `jsonschema`: JSON Schema 校验
+
+## 主页
+
+[https://gitee.com/guolei19850528/py_hikvision](https://gitee.com/guolei19850528/py_hikvision)
+
+## 许可证
+
+MIT License
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！

py_hikvision-0.1.0/README.md

@@ -0,0 +1,125 @@
+# py_hikvision
+
+一个用于与海康威视 iSecure Center (ISC) API 交互的 Python 客户端库。
+
+## 功能特性
+
+- 🔐 **API 认证**: 支持 HMAC-SHA256 签名认证机制
+- 🚀 **同步/异步请求**: 支持同步和异步两种 HTTP 请求方式
+- 📋 **响应模型**: 使用 Pydantic 进行响应数据校验和解析
+- 🔧 **工具函数**: 提供时间戳、UUID、JSONPath 查询等实用工具
+
+## 安装
+
+```bash
+pip install py_hikvision
+```
+
+## 快速开始
+
+### 基本使用
+
+```python
+from py_hikvision.isc import Isc
+
+# 初始化客户端
+isc = Isc(
+    host="https://your-isc-server.com",
+    ak="your-access-key",
+    sk="your-secret-key"
+)
+
+# 发送同步请求
+response = isc.request(
+    method="POST",
+    url="/api/parking/info",
+    json={"plateNo": "京A12345"}
+)
+print(response.json())
+
+# 发送异步请求
+async def fetch_data():
+    response = await isc.async_request(
+        method="GET",
+        url="/api/parking/list"
+    )
+    return response.json()
+```
+
+## API 文档
+
+### Isc 类
+
+#### 初始化
+
+```python
+isc = Isc(
+    host: Optional[str] = None,      # ISC 服务器地址
+    ak: Optional[str] = None,        # Access Key
+    sk: Optional[str] = None,        # Secret Key
+    client_kwargs: Optional[dict] = None  # httpx 客户端配置
+)
+```
+
+#### 方法
+
+| 方法 | 说明 |
+|------|------|
+| `client()` | 创建同步 HTTP 客户端 |
+| `async_client()` | 创建异步 HTTP 客户端 |
+| `signature(string)` | 生成 HMAC-SHA256 签名 |
+| `headers(method, path, headers)` | 生成请求头（包含签名） |
+| `request(**kwargs)` | 发送同步请求 |
+| `async_request(**kwargs)` | 发送异步请求 |
+
+### 工具函数
+
+```python
+from py_hikvision.isc.utils import (
+    timestamp,           # 生成毫秒时间戳
+    nonce,              # 生成 UUID
+    json_find_first,    # JSONPath 查询
+    json_is_valid,      # JSON Schema 校验
+    url_add_artemis_prefix,  # 添加 Artemis 前缀
+    image_to_base64_and_md5, # 图片编码
+    convert_to_normal   # 转换为 Normal 模型
+)
+```
+
+## 响应模型
+
+```python
+from py_hikvision.isc.responses import Normal
+
+# 响应结构
+normal = Normal(
+    code=0,           # 错误码，0 表示成功
+    msg="success",    # 错误信息
+    data={...}        # 响应数据
+)
+```
+
+## 安全说明
+
+1. **签名机制**: 使用 HMAC-SHA256 算法确保请求完整性
+2. **防止重放攻击**: 通过 nonce（随机 UUID）和 timestamp（时间戳）实现
+3. **密钥管理**: Access Key 和 Secret Key 应妥善保管，避免泄露
+
+## 依赖
+
+- `httpx`: HTTP 客户端
+- `pydantic`: 数据验证
+- `jsonpath-ng`: JSONPath 查询
+- `jsonschema`: JSON Schema 校验
+
+## 主页
+
+[https://gitee.com/guolei19850528/py_hikvision](https://gitee.com/guolei19850528/py_hikvision)
+
+## 许可证
+
+MIT License
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！

py_hikvision-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+[project]
+name = "py-hikvision"
+version = "0.1.0"
+requires-python = ">=3.13"
+description = "一个用于与海康威视 iSecure Center (ISC) API 交互的 Python 客户端库。"
+keywords = ["isc", "hikvision", "python", "client", "api", "海康威视", "iSecure Center"]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+    "jsonpath-ng>=1.2.0",
+    "jsonschema>=4.0.0",
+    "twine>=6.2.0",
+]
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "build>=0.18.0",
+    "twine>=4.0.0"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+[project.urls]
+"Home" = "https://gitee.com/guolei19850528/py_hikvision"

py_hikvision-0.1.0/setup.cfg

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

py_hikvision-0.1.0/src/py_hikvision/__init__.py

@@ -0,0 +1,2 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-

py_hikvision-0.1.0/src/py_hikvision/isc/__init__.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+import base64
+import hashlib
+import hmac
+from typing import Optional, Tuple
+
+import httpx
+from pydantic import HttpUrl
+
+from .responses import Normal
+from .utils import timestamp, nonce
+
+
+class Isc:
+    """
+    Isc类，用于与iSecure Center进行交互
+    """
+
+    def __init__(
+            self,
+            host: Optional[HttpUrl] = None,
+            ak: Optional[str] = None,
+            sk: Optional[str] = None,
+            client_kwargs: Optional[dict] = None,
+    ):
+        """
+        初始化 Isc 客户端
+
+        创建与 iSecure Center 交互的客户端实例，配置连接参数和认证密钥。
+
+        参数:
+            host (Optional[HttpUrl]): iSecure Center 服务器地址，如 "https://isc.example.com"
+            ak (Optional[str]): Access Key，用于 API 认证
+            sk (Optional[str]): Secret Key，用于生成请求签名
+            client_kwargs (Optional[dict]): 传递给 httpx.Client 的额外配置参数
+
+        配置说明:
+            - host 会自动去除末尾的斜杠
+            - 默认配置: base_url=host, verify=False, timeout=60
+            - client_kwargs 中的参数会覆盖默认配置
+        """
+        self.host = host or ""
+        self.host = self.host[:-1] if self.host.endswith("/") else self.host
+        self.ak = ak or ""
+        self.sk = sk or ""
+        self.client_kwargs = client_kwargs or {}
+        self.client_kwargs = {
+            **{
+                "base_url": self.host,
+                "verify": False,
+                "timeout": 60,
+            },
+            **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, string: str = "") -> str:
+        """
+        生成请求签名
+
+        使用 HMAC-SHA256 算法对输入字符串进行签名，确保请求的完整性和真实性。
+
+        参数:
+            string (str): 需要签名的字符串，由请求方法、Accept、Content-Type、
+                         x-ca-key、x-ca-nonce、x-ca-timestamp 和请求路径组成
+
+        返回:
+            str: 生成的签名（Base64 编码的 HMAC-SHA256 哈希值）
+
+        签名算法流程:
+            1. 将 Secret Key 编码为字节串作为 HMAC 密钥
+            2. 将待签名字符串编码为字节串
+            3. 使用 HMAC-SHA256 算法计算哈希值
+            4. 对哈希结果进行 Base64 编码并转换为字符串
+
+        安全说明:
+            - 签名机制防止请求被篡改
+            - 配合 nonce 和 timestamp 防止请求重放攻击
+        """
+        return base64.b64encode(
+            hmac.new(
+                self.sk.encode(),
+                string.encode(),
+                digestmod=hashlib.sha256
+            ).digest()
+        ).decode()
+
+    def headers(
+            self,
+            method: str = "POST",
+            path: str = "",
+            headers: dict = None
+    ) -> dict:
+        """
+        生成符合 ISecureCenter API 规范的请求头
+
+        根据 ISC API 规范生成包含认证信息的请求头，包括签名、密钥、随机数和时间戳。
+
+        参数:
+            method (str): HTTP 请求方法，支持 GET、POST、PUT、DELETE 等，默认 POST
+            path (str): 请求路径，例如 "/api/parking/info"
+            headers (dict): 额外的请求头，会覆盖默认请求头中的同名项
+
+        返回:
+            dict: 完整的请求头字典，包含所有必要的认证信息
+
+        请求头字段说明:
+            - accept: 接受所有响应类型
+            - content-type: 内容类型，固定为 application/json
+            - x-ca-key: 访问密钥 Access Key，用于标识请求来源
+            - x-ca-nonce: 随机 UUID，防止请求被重放攻击
+            - x-ca-timestamp: 当前时间戳（毫秒），用于请求时效性验证
+            - x-ca-signature: 请求签名，使用 HMAC-SHA256 算法生成
+            - x-ca-signature-headers: 参与签名计算的请求头列表
+
+        签名字符串格式:
+            按顺序拼接以下字段，使用换行符分隔：
+            1. HTTP 请求方法
+            2. Accept 头值
+            3. Content-Type 头值
+            4. x-ca-key:{value}
+            5. x-ca-nonce:{value}
+            6. x-ca-timestamp:{value}
+            7. 请求路径
+
+        示例:
+            >>> headers = isc_client.headers(method="POST", path="/api/parking/info")
+            >>> print(headers)
+            {
+                'accept': '*/*',
+                'content-type': 'application/json',
+                'x-ca-signature-headers': 'x-ca-key,x-ca-nonce,x-ca-timestamp',
+                'x-ca-key': 'your_access_key',
+                'x-ca-nonce': 'uuid-string',
+                'x-ca-timestamp': '1234567890123',
+                'x-ca-signature': 'base64-encoded-signature'
+            }
+        """
+        method = method or "POST"
+        path = path or ""
+        headers = headers or {}
+
+        headers = {
+            "accept": "*/*",
+            "content-type": "application/json",
+            "x-ca-signature-headers": "x-ca-key,x-ca-nonce,x-ca-timestamp",
+            "x-ca-key": self.ak,
+            "x-ca-nonce": nonce(),
+            "x-ca-timestamp": str(timestamp()),
+            **headers
+        }
+
+        string = "\n".join([
+            method,
+            headers["accept"],
+            headers["content-type"],
+            f"x-ca-key:{headers['x-ca-key']}",
+            f"x-ca-nonce:{headers['x-ca-nonce']}",
+            f"x-ca-timestamp:{headers['x-ca-timestamp']}",
+            path,
+        ])
+
+        headers["x-ca-signature"] = self.signature(string=string)
+        return headers
+
+    def request(self, client: Optional[httpx.Client] = None, **kwargs) -> httpx.Response:
+        """
+        发送同步 HTTP 请求
+
+        自动添加 ISC API 认证签名，支持传入自定义客户端或使用内置客户端。
+
+        参数:
+            client (Optional[httpx.Client]): 自定义的 httpx.Client 实例，若为 None 则自动创建
+            **kwargs: 传递给 httpx.Client.request 的参数，包括 method、url、headers、data、json 等
+
+        返回:
+            httpx.Response: HTTP 响应对象
+
+        使用示例:
+            >>> isc = Isc(host="https://isc.example.com", ak="your_ak", sk="your_sk")
+            >>> response = isc.request(method="GET", url="/api/parking/info")
+            >>> print(response.json())
+        """
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "method": "POST",
+                "headers": {
+                    **self.headers(
+                        method=kwargs.get("method", "POST"),
+                        path=kwargs.get("url", ""),
+                        headers=kwargs.get("headers", {})
+                    )
+                },
+            },
+            **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:
+        """
+        发送异步 HTTP 请求
+
+        自动添加 ISC API 认证签名，支持传入自定义异步客户端或使用内置客户端。
+
+        参数:
+            client (Optional[httpx.AsyncClient]): 自定义的 httpx.AsyncClient 实例，若为 None 则自动创建
+            **kwargs: 传递给 httpx.AsyncClient.request 的参数，包括 method、url、headers、data、json 等
+
+        返回:
+            httpx.Response: HTTP 响应对象
+
+        使用示例:
+            >>> isc = Isc(host="https://isc.example.com", ak="your_ak", sk="your_sk")
+            >>> response = await isc.async_request(method="POST", url="/api/parking/info", json={"key": "value"})
+            >>> print(response.json())
+        """
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "method": "POST",
+                "headers": {
+                    **self.headers(
+                        method=kwargs.get("method", "POST"),
+                        path=kwargs.get("url", ""),
+                        headers=kwargs.get("headers", {})
+                    )
+                },
+            },
+            **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_hikvision-0.1.0/src/py_hikvision/isc/responses.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+from pydantic import BaseModel
+from pydantic import Field
+from typing import Literal, Union, Any
+
+class Base(BaseModel):
+    """
+    iSecure Center响应基类
+    
+    所有API响应都包含错误码和错误信息字段
+    """
+    code: Union[int, str] = Field(..., title="错误码", description="错误码，0表示成功，非0表示失败")
+    msg: str = Field(..., title="错误信息", description="错误信息描述")
+
+
+class Normal(Base):
+    """
+    正常响应模型
+    
+    继承自Base，用于正常接口的响应
+    """
+    code: Literal[0, "0"] = Field(..., title="错误码", description="成功，值为0")
+    data: Any = Field(title="数据", description="正常响应数据")

py_hikvision-0.1.0/src/py_hikvision/isc/utils.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+import base64
+import hashlib
+import uuid
+from datetime import datetime
+from typing import Any, Optional, Tuple, Union
+
+import httpx
+from jsonpath_ng import parse
+from jsonschema.validators import Draft202012Validator
+
+from py_hikvision.isc import Normal
+
+
+class ValidatorSchema:
+    """
+    JSON Schema 校验器定义类
+
+    使用 JSON Schema Draft 2020-12 规范进行数据校验。
+
+    Attributes:
+        success: 通用成功响应 Schema，校验 code 是否为 0
+    """
+
+    success = {
+        "type": "object",
+        "properties": {
+            "code": {
+                "oneOf": [
+                    {"type": "integer", "const": 0},
+                    {"type": "string", "const": "0"}
+                ]
+            },
+        },
+        "required": ["code"]
+    }
+
+
+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 nonce() -> str:
+    """
+    生成随机的 UUID 字符串
+
+    返回:
+        str: 随机的 UUID 字符串（无连字符），用于防止请求重放攻击
+
+    示例:
+        >>> random_nonce = utils.nonce()
+        >>> print(random_nonce)  # 输出示例: "a1b2c3d4e5f6g7h8i9j0..."
+    """
+    return uuid.uuid4().hex
+
+
+def url_add_artemis_prefix(url: Optional[str]) -> str:
+    """
+    在URL前添加/artemis/前缀
+
+    :param url: 输入的URL字符串
+    :return: 包含/artemis/前缀的URL字符串
+    """
+    url = url or ""
+    if url.startswith("/"):
+        if not url.startswith("/artemis"):
+            return "/artemis" + url
+        return url
+    else:
+        return "/artemis/" + url
+
+
+def image_to_base64_and_md5(image_path: Optional[str] = None) -> Tuple[str, str]:
+    """
+    将图片文件转换为 Base64 编码和 MD5 校验值
+
+    企业微信 Webhook 图片消息要求同时提供 base64 编码和 md5 值。
+
+    Args:
+        image_path: 图片文件的绝对路径或相对路径，默认值为 None
+
+    Returns:
+        Tuple[str, str]: 包含两个元素的元组
+            - 第一个元素: 图片的 Base64 编码字符串
+            - 第二个元素: 图片内容的 MD5 哈希值（小写十六进制）
+
+    Raises:
+        FileNotFoundError: 当指定的图片路径不存在时抛出
+        IOError: 当读取图片文件失败时抛出
+    """
+    image_path = image_path or ""
+    with open(image_path, 'rb') as f:
+        image_data = f.read()
+
+    base64_str = base64.b64encode(image_data).decode('utf-8')
+    md5_str = hashlib.md5(image_data).hexdigest()
+
+    return base64_str, md5_str
+
+
+def convert_to_normal(response: Union[httpx.Response, dict]) -> Normal:
+    """
+    将 HTTP 响应或字典转换为 Normal 模型对象
+
+    统一处理 httpx.Response 对象和字典，将其转换为标准化的 Normal 响应模型。
+
+    参数:
+        response (Union[httpx.Response, dict]): HTTP 响应对象或字典数据
+
+    返回:
+        Normal: 标准化的响应模型对象，包含 code、msg 和 data 字段
+
+    处理逻辑:
+        - 如果输入是 httpx.Response 对象，先调用 json() 方法解析响应体
+        - 如果输入是字典，直接传入 Normal 构造函数
+    """
+    if isinstance(response, httpx.Response):
+        return Normal(**response.json())
+    return Normal(**response)

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

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: py-hikvision
+Version: 0.1.0
+Summary: 一个用于与海康威视 iSecure Center (ISC) API 交互的 Python 客户端库。
+License-Expression: MIT
+Project-URL: Home, https://gitee.com/guolei19850528/py_hikvision
+Keywords: isc,hikvision,python,client,api,海康威视,iSecure Center
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: jsonpath-ng>=1.2.0
+Requires-Dist: jsonschema>=4.0.0
+Requires-Dist: twine>=6.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: build>=0.18.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# py_hikvision
+
+一个用于与海康威视 iSecure Center (ISC) API 交互的 Python 客户端库。
+
+## 功能特性
+
+- 🔐 **API 认证**: 支持 HMAC-SHA256 签名认证机制
+- 🚀 **同步/异步请求**: 支持同步和异步两种 HTTP 请求方式
+- 📋 **响应模型**: 使用 Pydantic 进行响应数据校验和解析
+- 🔧 **工具函数**: 提供时间戳、UUID、JSONPath 查询等实用工具
+
+## 安装
+
+```bash
+pip install py_hikvision
+```
+
+## 快速开始
+
+### 基本使用
+
+```python
+from py_hikvision.isc import Isc
+
+# 初始化客户端
+isc = Isc(
+    host="https://your-isc-server.com",
+    ak="your-access-key",
+    sk="your-secret-key"
+)
+
+# 发送同步请求
+response = isc.request(
+    method="POST",
+    url="/api/parking/info",
+    json={"plateNo": "京A12345"}
+)
+print(response.json())
+
+# 发送异步请求
+async def fetch_data():
+    response = await isc.async_request(
+        method="GET",
+        url="/api/parking/list"
+    )
+    return response.json()
+```
+
+## API 文档
+
+### Isc 类
+
+#### 初始化
+
+```python
+isc = Isc(
+    host: Optional[str] = None,      # ISC 服务器地址
+    ak: Optional[str] = None,        # Access Key
+    sk: Optional[str] = None,        # Secret Key
+    client_kwargs: Optional[dict] = None  # httpx 客户端配置
+)
+```
+
+#### 方法
+
+| 方法 | 说明 |
+|------|------|
+| `client()` | 创建同步 HTTP 客户端 |
+| `async_client()` | 创建异步 HTTP 客户端 |
+| `signature(string)` | 生成 HMAC-SHA256 签名 |
+| `headers(method, path, headers)` | 生成请求头（包含签名） |
+| `request(**kwargs)` | 发送同步请求 |
+| `async_request(**kwargs)` | 发送异步请求 |
+
+### 工具函数
+
+```python
+from py_hikvision.isc.utils import (
+    timestamp,           # 生成毫秒时间戳
+    nonce,              # 生成 UUID
+    json_find_first,    # JSONPath 查询
+    json_is_valid,      # JSON Schema 校验
+    url_add_artemis_prefix,  # 添加 Artemis 前缀
+    image_to_base64_and_md5, # 图片编码
+    convert_to_normal   # 转换为 Normal 模型
+)
+```
+
+## 响应模型
+
+```python
+from py_hikvision.isc.responses import Normal
+
+# 响应结构
+normal = Normal(
+    code=0,           # 错误码，0 表示成功
+    msg="success",    # 错误信息
+    data={...}        # 响应数据
+)
+```
+
+## 安全说明
+
+1. **签名机制**: 使用 HMAC-SHA256 算法确保请求完整性
+2. **防止重放攻击**: 通过 nonce（随机 UUID）和 timestamp（时间戳）实现
+3. **密钥管理**: Access Key 和 Secret Key 应妥善保管，避免泄露
+
+## 依赖
+
+- `httpx`: HTTP 客户端
+- `pydantic`: 数据验证
+- `jsonpath-ng`: JSONPath 查询
+- `jsonschema`: JSON Schema 校验
+
+## 主页
+
+[https://gitee.com/guolei19850528/py_hikvision](https://gitee.com/guolei19850528/py_hikvision)
+
+## 许可证
+
+MIT License
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！

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

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

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,11 @@
+httpx>=0.27.0
+pydantic>=2.0.0
+jsonpath-ng>=1.2.0
+jsonschema>=4.0.0
+twine>=6.2.0
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21
+build>=0.18.0
+twine>=4.0.0

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

@@ -0,0 +1 @@
+py_hikvision