Metadata-Version: 2.4
Name: py-easy-hikvision
Version: 1.0.0
Summary: 一个简化海康威视ISecureCenter平台API使用的Python工具包，提供设备管理、事件订阅等功能的便捷封装。
Home-page: https://gitee.com/guolei19850528/py_easy_hikvision
Author: guolei
Author-email: 174000902@qq.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx
Requires-Dist: jsonschema
Requires-Dist: jsonpath-ng
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# py-easy-hikvision

一个简化海康威视ISecureCenter平台API使用的Python工具包，提供设备管理、事件订阅等功能的便捷封装。

## 功能特性

- **认证管理**：支持海康威视ISecureCenter平台的AK/SK认证
- **签名生成**：自动生成符合平台要求的请求签名
- **请求头构建**：自动构建符合API规范的请求头
- **同步与异步**：同时支持同步和异步操作
- **响应处理**：统一的响应处理机制，自动验证响应结果
- **类型提示**：完整的类型注解，提供良好的IDE支持

## 安装

### 使用pip安装

```bash
pip install py-easy-hikvision
```

### 从源码安装

```bash
git clone https://gitee.com/guolei19850528/py_easy_hikvision.git
cd py_easy_hikvision
pip install -e .
```

## 依赖

- httpx
- jsonschema
- jsonpath-ng

## 快速开始

### 基本使用

```python
from py_easy_hikvision.isc import ISecureCenter

# 初始化ISecureCenter实例
isc = ISecureCenter(
    host="https://your-isc-server:1443",  # ISecureCenter平台地址
    ak="YOUR_AK",  # Access Key
    sk="YOUR_SK"   # Secret Key
)

# 发送API请求
response = isc.request(
    url="/artemis/api/resource/v1/person/condition/personInfo",
    json={
        "paramName": "phoneNo",
        "paramValue": [
            "13800000000"
        ]
    },
)

print(f"请求结果: {response.validated}")
if response.validated:
    print(f"返回数据: {response.value}")
else:
    print(f"错误信息: {response.json}")
```

### 异步使用

```python
import asyncio
from py_easy_hikvision.isc import ISecureCenter

async def main():
    # 初始化ISecureCenter实例
    isc = ISecureCenter(
        host="https://your-isc-server:1443",
        ak="YOUR_AK",
        sk="YOUR_SK"
    )
    
    # 异步发送API请求
    response = await isc.async_request(
        url="/artemis/api/resource/v1/person/condition/personInfo",
        json={
            "paramName": "phoneNo",
            "paramValue": [
                "13800000000"
            ]
        },
    )
    
    print(f"请求结果: {response.validated}")
    if response.validated:
        print(f"返回数据: {response.value}")
    else:
        print(f"错误信息: {response.json}")

asyncio.run(main())
```

## API文档

### ISecureCenter类

#### 初始化参数
- `host`：ISecureCenter平台的基础URL
- `ak`：Access Key，用于身份认证
- `sk`：Secret Key，用于签名生成
- `client_kwargs`：传递给httpx.Client的额外参数

#### 方法
- `timestamp()`：生成当前时间戳（毫秒）
- `nonce()`：生成随机的UUID字符串
- `signature(string)`：生成请求签名
- `headers(method, path, headers)`：生成符合ISecureCenter API规范的请求头
- `client(**kwargs)`：创建同步客户端实例
- `async_client(**kwargs)`：创建异步客户端实例
- `request(client=None, **kwargs)`：同步请求方法
- `async_request(client=None, **kwargs)`：异步请求方法

### 响应处理

所有API调用都会返回`RequestResponse`对象，包含以下属性：
- `validated`：响应是否有效
- `value`：从响应中提取的值
- `json`：响应的JSON数据
- `response`：原始的httpx.Response对象

## 测试

运行测试用例：

```bash
python -m unittest test_isc.py
```

## 项目结构

```
py-easy-hikvision/
├── py_easy_hikvision/
│   ├── __init__.py        # 模块初始化
│   └── isc/
│       └── __init__.py    # ISecureCenter API客户端实现
├── test_isc.py            # ISecureCenter测试
├── setup.py               # 安装配置
├── requirements.txt       # 依赖声明
├── LICENSE                # 许可证
└── README.md              # 项目文档
```

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

## 联系方式

- 作者：guolei
- 邮箱：174000902@qq.com
- 项目地址：https://gitee.com/guolei19850528/py_easy_hikvision
