Metadata-Version: 2.4
Name: pyhikvision-isc
Version: 3.0.0
Summary: 海康威视 ISecureCenter (ISC) API 的 Python SDK，支持同步和异步两种调用方式，提供完整的请求签名机制。
Home-page: https://gitee.com/guolei19850528/pyhikvision_isc
Author: guolei
Author-email: 174000902@qq.com
License: MIT
Keywords: 海康威视 ISecureCenter (ISC) 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

# pyhikvision_isc

海康威视 ISecureCenter (ISC) API 客户端 Python SDK

提供对海康威视 ISC API 的异步和同步调用支持，实现了基于 HMAC-SHA256 的请求签名机制。

## 功能特性

- 支持同步和异步两种调用方式
- 自动生成请求签名（HMAC-SHA256）
- 支持 JSON Schema 响应校验
- 提供 JSONPath 数据提取工具
- 简洁的 API 接口设计

## 安装

```bash
pip install pyhikvision-isc
```

## 快速开始

### 同步客户端

```python
from pyhikvision_isc import Isc

# 创建客户端
client = Isc(
    host="https://your-isc-server.com",
    ak="your-access-key",
    sk="your-secret-key"
)

# 发送请求
response = client.request(
    url="/api/parking/info",
    json={"param": "value"}
)

# 获取响应数据
data = response.json()
```

### 异步客户端

```python
import asyncio
from pyhikvision_isc import Isc

# 创建异步客户端
client = Isc(
    host="https://your-isc-server.com",
    ak="your-access-key",
    sk="your-secret-key",
    is_async=True
)


# 发送异步请求
async def fetch_data():
    response = await client.async_request(
        url="/api/parking/info",
        json={"param": "value"}
    )
    return response.json()


result = asyncio.run(fetch_data())
```

## API 文档

### Isc 类

#### 初始化参数

| 参数            | 类型   | 必填 | 说明                 |
|---------------|------|----|--------------------|
| host          | str  | 是  | ISC 服务器地址          |
| ak            | str  | 是  | 访问密钥 (Access Key)  |
| sk            | str  | 是  | 安全密钥 (Secret Key)  |
| client_kwargs | dict | 否  | httpx.Client 配置参数  |
| is_async      | bool | 否  | 是否使用异步客户端，默认 False |

#### 方法

##### `request(client, **kwargs)`

同步请求方法

| 参数       | 类型           | 必填 | 说明                           |
|----------|--------------|----|------------------------------|
| client   | httpx.Client | 否  | 自定义同步客户端                     |
| **kwargs | dict         | 否  | 传递给 httpx.Client.request 的参数 |

##### `async_request(client, **kwargs)`

异步请求方法

| 参数       | 类型                | 必填 | 说明                                |
|----------|-------------------|----|-----------------------------------|
| client   | httpx.AsyncClient | 否  | 自定义异步客户端                          |
| **kwargs | dict              | 否  | 传递给 httpx.AsyncClient.request 的参数 |

## 工具函数

### json_find_first(expression, data)

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

```python
from pyhikvision_isc.utils import json_find_first

data = {"code": "0", "data": {"items": [1, 2, 3]}}
result = json_find_first("$.data.items[0]", data)  # 返回 1
```

### json_is_valid(schema, data)

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

```python
from pyhikvision_isc.utils import json_is_valid, ValidatorSchema

data = {"code": "0"}
is_valid = json_is_valid(ValidatorSchema.success, data)  # 返回 True
```

## 安全说明

- 请求签名使用 HMAC-SHA256 算法，确保请求的完整性和真实性
- 配合 nonce（随机数）和 timestamp（时间戳）防止请求重放攻击
- 建议在生产环境开启 SSL 证书验证（设置 `verify=True`）

## 许可证

MIT License

## 作者

guolei<174000902@qq.com>

## 项目主页

[https://github.com/guolei/pyhikvision_isc]https://github.com/guolei/pyhikvision_isc)
