Metadata-Version: 2.4
Name: py-tjbrhk
Version: 1.0.0
Summary: 一个用于与天津博瑞皓科 API 交互的 Python 客户端库
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_tjbrhk
Project-URL: Repository, https://gitee.com/guolei19850528/py_tjbrhk.git
Project-URL: Documentation, https://www.yuque.com/lingdutuandui/ugcpag/umbzsd
Keywords: 天津博瑞皓科,tjbrhk,python,client,智能云音箱,api,speaker
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Programming Language :: Python
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Communications
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: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: setuptools>=61.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Dynamic: license-file

# py-tjbrhk

一个用于与天津博瑞皓科智能云音箱 API 交互的 Python 客户端库。

## 官网文档

[https://www.yuque.com/lingdutuandui/ugcpag/umbzsd](https://www.yuque.com/lingdutuandui/ugcpag/umbzsd)

## 功能特性

- 支持同步和异步 HTTP 请求
- 提供通知发送功能
- 内置 JSON 数据处理工具
- 响应模型验证支持
- 灵活的配置选项
- 完整的类型提示
- 详细的代码注释

## 安装

```bash
pip install py_tjbrhk
```

或者从源代码安装：

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

## 快速开始

### 同步使用

```python
from py_tjbrhk.speaker import Speaker

speaker = Speaker(
    base_url="https://speaker.17laimai.cn",
    token="your_token",
    id="your_id",
    version="1"
)

response = speaker.notify(message="Hello, World!")
print(response.json())
```

### 异步使用

```python
import asyncio
from py_tjbrhk.speaker import Speaker

async def main():
    speaker = Speaker(
        base_url="https://speaker.17laimai.cn",
        token="your_token",
        id="your_id"
    )
    
    response = await speaker.async_notify(message="Hello, Async World!")
    print(response.json())

asyncio.run(main())
```

### 使用自定义客户端

```python
import httpx
from py_tjbrhk.speaker import Speaker

speaker = Speaker(token="your_token", id="your_id")

with speaker.client() as client:
    response = speaker.notify(client=client, message="Custom Client")
    print(response.json())
```

## API 参考

### Speaker 类

#### 初始化参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| base_url | str | `https://speaker.17laimai.cn` | Speaker 服务器地址 |
| token | str | `""` | API 认证 Token |
| id | str | `""` | API 认证 ID |
| version | str | `"1"` | API 版本号 |
| client_kwargs | dict | `None` | httpx.Client 额外配置参数 |

#### 方法

| 方法 | 说明 | 返回值 |
|------|------|--------|
| `client()` | 创建并返回同步 HTTP 客户端 | `httpx.Client` |
| `async_client()` | 创建并返回异步 HTTP 客户端 | `httpx.AsyncClient` |
| `notify(client, message, **kwargs)` | 发送同步通知请求 | `httpx.Response` |
| `async_notify(client, message, **kwargs)` | 发送异步通知请求 | `httpx.Response` |

### 工具函数

#### `json_find_first(expression, data)`

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

```python
from py_tjbrhk.speaker.utils import json_find_first

data = {"data": {"items": [{"id": 1}, {"id": 2}]}}
result = json_find_first("$.data.items[0].id", data)
```

#### `json_is_valid(schema, data)`

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

```python
from py_tjbrhk.speaker.utils import json_is_valid

schema = {"type": "object", "required": ["name"]}
is_valid = json_is_valid(schema, {"name": "test"})
```

#### `convert_to_errcode_eq_0(response)`

将 HTTP 响应或字典转换为 ERRCODE_EQ_0 模型对象。

```python
from py_tjbrhk.speaker.utils import convert_to_errcode_eq_0

response = speaker.notify(message="Hello")
model = convert_to_errcode_eq_0(response)
print(model.errcode)
```

#### `errcode_eq_0_validator(response, schema)`

校验响应是否符合成功响应 Schema。

```python
from py_tjbrhk.speaker.utils import errcode_eq_0_validator

response = speaker.notify(message="Hello")
is_success = errcode_eq_0_validator(response)
```

### 响应模型

#### Base

基础响应模型，包含 `errcode` 和 `errmsg` 字段。

```python
from py_tjbrhk.speaker.responses import Base

response = Base(errcode=0, errmsg="success")
```

#### ERRCODE_EQ_0

成功响应模型，`errcode` 值必须为 0 或 "0"。

```python
from py_tjbrhk.speaker.responses import ERRCODE_EQ_0

response = ERRCODE_EQ_0(errcode=0, errmsg="success")
```

## 依赖

- **httpx** >= 0.27.0 - HTTP 客户端库，支持同步和异步请求
- **pydantic** >= 2.0 - 数据验证和序列化库
- **jsonpath-ng** >= 1.5.3 - JSONPath 表达式解析库
- **jsonschema** >= 4.21.0 - JSON Schema 校验库

### 开发依赖

```bash
pip install py_tjbrhk[dev]
```

开发依赖包括：
- pytest - 测试框架
- pytest-asyncio - 异步测试支持
- pytest-cov - 测试覆盖率
- flake8 - 代码风格检查
- black - 代码格式化
- isort - 导入排序
- mypy - 类型检查

## 项目结构

```
py_tjbrhk/
├── src/
│   └── py_tjbrhk/
│       ├── __init__.py          # 包初始化，版本信息
│       ├── py.typed             # 类型提示标记文件
│       └── speaker/
│           ├── __init__.py      # Speaker 客户端类
│           ├── utils.py         # 工具函数
│           └── responses.py     # 响应模型定义
├── pyproject.toml               # 项目配置
├── README.md                    # 项目文档
└── LICENSE                      # 许可证
```

## 开发指南

### 运行测试

```bash
pytest
```

### 检查代码风格

```bash
flake8 src
```

### 格式化代码

```bash
black src
isort src
```

### 类型检查

```bash
mypy src
```

## 许可证

MIT License

## 相关链接

- **项目主页**: [https://gitee.com/guolei19850528/py_tjbrhk](https://gitee.com/guolei19850528/py_tjbrhk)
- **代码仓库**: [https://gitee.com/guolei19850528/py_tjbrhk.git](https://gitee.com/guolei19850528/py_tjbrhk.git)
- **官网文档**: [https://www.yuque.com/lingdutuandui/ugcpag/umbzsd](https://www.yuque.com/lingdutuandui/ugcpag/umbzsd)
