Metadata-Version: 2.4
Name: pyhikvision-isc
Version: 1.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，支持同步和异步两种调用方式，提供完整的请求签名机制。

## 功能特性

- ✅ **同步/异步支持**: 同时提供同步和异步请求方法
- ✅ **请求签名**: 实现基于 HMAC-SHA256 的请求签名机制
- ✅ **响应校验**: 使用 JSON Schema 校验 API 响应
- ✅ **数据提取**: 使用 JSONPath 提取响应数据
- ✅ **类型提示**: 完整的类型注解支持

## 安装

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

## 快速开始

### 同步客户端

```python
from pyhikvision_isc import Isc

# 创建同步客户端
client = Isc(
    host="https://isc.example.com",
    ak="your_access_key",
    sk="your_secret_key"
)

# 发送请求
result = client.request(
    method="GET",
    url="/api/parking/info",
    json={"param1": "value1"}
)

print(result)
```

### 异步客户端

```python
import asyncio
from pyhikvision_isc import Isc

# 创建异步客户端
client = Isc(
    host="https://isc.example.com",
    ak="your_access_key",
    sk="your_secret_key",
    is_async=True
)

# 发送异步请求
async def main():
    result = await client.async_request(
        method="POST",
        url="/api/parking/query",
        json={"param1": "value1"}
    )
    print(result)

asyncio.run(main())
```

## API 文档

### Isc 类

#### 初始化参数

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

#### 方法

##### `request()` - 同步请求

```python
def request(
    client: Optional[httpx.Client] = None,
    **kwargs
) -> Optional[dict]
```

**参数:**
- `client`: 可选的同步客户端实例
- `**kwargs`: 传递给 `httpx.Client.request` 的参数

**返回:**
- 响应中的 `data` 字段内容，请求失败返回 `None`

##### `async_request()` - 异步请求

```python
async def async_request(
    client: Optional[httpx.AsyncClient] = None,
    **kwargs
) -> Optional[dict]
```

**参数:**
- `client`: 可选的异步客户端实例
- `**kwargs`: 传递给 `httpx.AsyncClient.request` 的参数

**返回:**
- 响应中的 `data` 字段内容，请求失败返回 `None`

##### `headers()` - 生成请求头

```python
def headers(
    method: str = "POST",
    path: str = "",
    headers: dict = {}
) -> dict
```

**参数:**
- `method`: HTTP 请求方法，默认 `POST`
- `path`: 请求路径
- `headers`: 额外的请求头

**返回:**
- 包含认证信息的完整请求头字典

##### `signature()` - 生成签名

```python
def signature(string: str = "") -> str
```

**参数:**
- `string`: 需要签名的字符串

**返回:**
- Base64 编码的 HMAC-SHA256 签名

## 签名机制

请求签名采用 HMAC-SHA256 算法，签名字符串格式如下（按顺序用换行符分隔）：

1. HTTP 请求方法 (POST/GET/PUT/DELETE)
2. Accept 头值 (`*/*`)
3. Content-Type 头值 (`application/json`)
4. `x-ca-key:{value}`
5. `x-ca-nonce:{value}`
6. `x-ca-timestamp:{value}`
7. 请求路径

## 响应处理

SDK 会自动验证响应状态码，并提取响应中的 `data` 字段：

```python
# 响应示例
{
    "code": "0",
    "message": "success",
    "data": {...}
}

# SDK 提取后返回
{...}  # data 字段内容
```

## 配置说明

### httpx 客户端配置

可以通过 `client_kwargs` 参数配置 httpx 客户端：

```python
client = Isc(
    host="https://isc.example.com",
    ak="your_ak",
    sk="your_sk",
    client_kwargs={
        "timeout": 60,
        "verify": True,  # 生产环境建议开启 SSL 验证
        "proxies": "http://proxy.example.com:8080"
    }
)
```

## 依赖

- Python >= 3.10
- httpx
- jsonschema
- jsonpath-ng

## 许可证

MIT License

## 作者

guolei <174000902@qq.com>

## 项目地址

[https://gitee.com/guolei19850528/pyhikvision_isc](https://gitee.com/guolei19850528/pyhikvision_isc)
