Metadata-Version: 2.5
Name: py-tjbrhk-toolkit
Version: 4.0.1
Summary: Python client library for the Tianjin Bojrhao Ke Cloud Speaker API / 天津博瑞皓科博瑞云音箱 Python 客户端库
Project-URL: Homepage, https://gitee.com/guolei19850528/py_tjbrhk_toolkit
Project-URL: Repository, https://gitee.com/guolei19850528/py_tjbrhk_toolkit
Author-email: 郭磊 <174000902@qq.com>
License: MIT
License-File: LICENSE
Keywords: 云音箱接口,博瑞云音箱,支付播报,语音播报
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx<1.0,>=0.24.0
Requires-Dist: pydantic<3.0,>=2.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Requires-Dist: python-dotenv>=1.0.0; extra == 'test'
Description-Content-Type: text/markdown

# py-tjbrhk-toolkit

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

[中文](./README.md) | [English](./README.en.md)

文档：
- [博瑞云音箱 API 对接文档（语雀）](https://www.yuque.com/lingdutuandui/ugcpag/umbzsd)
- [httpx](https://www.python-httpx.org/)
- [Pydantic](https://docs.pydantic.dev/)

## 项目介绍

**py-tjbrhk-toolkit** 是天津博瑞皓科博瑞云音箱 API 的 Python 客户端库，提供同步和异步客户端，用于向云音箱发送通知语音播报请求。

当前实现 `notify.php` 通知接口。客户端使用 `httpx` 发送表单 POST 请求，并使用 Pydantic 模型解析接口响应。

## 软件架构

```text
py_tjbrhk_toolkit/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── py_tjbrhk_toolkit/
│       ├── __init__.py
│       ├── py.typed
│       └── speaker/
│           ├── __init__.py
│           ├── client.py       # 同步与异步通知客户端
│           ├── exception.py    # 配置错误与网络错误
│           └── response.py     # 通知接口响应模型
└── tests/
    └── speaker/
        ├── .env.example
        ├── conftest.py
        └── test_notify.py
```

### 主要类与方法

| 类 | 说明 |
|------|----------|
| `Client` | 同步云音箱客户端，提供 `notify()` 方法 |
| `AsyncClient` | 异步云音箱客户端，提供 `notify()` 方法 |
| `NotifyResponse` | 通知接口响应模型，提供 `ok` 属性判断业务结果 |
| `ConfigError` | 客户端配置无效时抛出 |
| `NetworkError` | HTTP 请求失败时抛出 |

### 支持的接口

| 接口 | 客户端方法 | HTTP 请求 | 说明 |
|------|------------|-----------|------|
| `notify.php` | `Client.notify()` | 同步 POST | 发送通知语音播报 |
| `notify.php` | `AsyncClient.notify()` | 异步 POST | 异步发送通知语音播报 |

通知消息最长为 128 个 UTF-8 字节。接口表单支持 `id`、`token`、`version`、`message`、`seq`、`vol`、`speed` 和 `trace_no` 字段。

## 安装方式

推荐使用 **uv**：

```bash
# 添加为项目依赖
uv add py-tjbrhk-toolkit

# 或使用 pip 安装
pip install py-tjbrhk-toolkit
```

从源码安装并配置测试环境：

```bash
uv sync --extra dev --extra test
```

## 使用说明

### 1. 同步发送通知

```python
from py_tjbrhk_toolkit.speaker.client import Client

with Client(
    token="your_speaker_token",
    id="your_speaker_id",
) as client:
    response = client.notify(
        message="您好，欢迎光临",
        vol=80,
    )
    print(response.model_dump())
    print("发送成功:", response.ok)
```

### 2. 异步发送通知

```python
import asyncio

from py_tjbrhk_toolkit.speaker.client import AsyncClient


async def main() -> None:
    async with AsyncClient(
        token="your_speaker_token",
        id="your_speaker_id",
    ) as client:
        response = await client.notify(
            message="收到一笔新的付款",
            vol=80,
        )
        print(response.model_dump())
        print("发送成功:", response.ok)


asyncio.run(main())
```

同步客户端可用 `with` 管理连接；异步客户端可用 `async with` 管理连接。也可以分别调用 `Client.close()` 和 `AsyncClient.aclose()` 手动关闭。

### 3. 通知参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `message` | `str` | 是 | 播报内容，最长 128 个 UTF-8 字节 |
| `seq` | `int \| str` | 否 | 通讯去重顺序号 |
| `vol` | `int \| str` | 否 | 音量设置 |
| `speed` | `int \| str` | 否 | 语速设置 |
| `trace_no` | `str` | 否 | 请求追踪字符串 |
| `id` | `str` | 否 | 覆盖客户端配置的云音箱 ID |
| `token` | `str` | 否 | 覆盖客户端配置的 Token |
| `version` | `str` | 否 | 覆盖客户端配置的接口版本 |

消息中的数字默认按金额播报；如需按号码或编号播报，可按接口约定使用方括号，例如 `"[123]"`。音箱型号和接口版本对 `speed` 等参数的支持可能不同，请以官方接口文档为准。

## 测试

测试配置从 `tests/speaker/.env` 读取。先复制模板并填写有效的设备 ID 和 Token：

```bash
cp tests/speaker/.env.example tests/speaker/.env
```

在 `.env` 中设置：

```ini
BASE_URL=https://speaker.17laimai.cn
ID=your_speaker_id
TOKEN=your_speaker_token
VERSION=1
ALLOW_REAL_REQUESTS=true
```

运行同步和异步测试：

```bash
uv run --extra test pytest -v tests/speaker
```

> **注意：**这些测试会向真实云音箱发送请求并触发语音播报。只有在 `.env` 中显式设置 `ALLOW_REAL_REQUESTS=true` 且配置有效凭据时才会运行；否则 pytest 会跳过测试。请勿在不适合播报的设备或环境中执行。

## 贡献指南

欢迎提交问题和贡献代码：

1. Fork 本仓库
2. 创建特性分支：`git checkout -b feature/your-feature`
3. 提交修改：`git commit -m "feat: add your feature"`
4. 推送分支并提交合并请求

提交前请运行 Ruff 检查，并确认测试符合预期。

## 作者信息

- 作者：郭磊
- 邮箱：174000902@qq.com

## 许可证

[MIT License](LICENSE)