Metadata-Version: 2.4
Name: py-tjbrhk-toolkit
Version: 3.0.5
Summary: 天津博瑞皓科 Python 客户端库，提供与天津博瑞皓科 API 交互的完整功能支持
Author-email: 郭磊 <174000902@qq.com>
License: MIT
Project-URL: Homepage, https://gitee.com/guolei19850528/py_tjbrhk_toolkit
Project-URL: Repository, https://gitee.com/guolei19850528/py_tjbrhk_toolkit.git
Project-URL: PyPI Homepage, https://pypi.org/project/py-tjbrhk-toolkit/
Keywords: 天津博瑞皓科,tjbrhk,python,client,智能云音箱,api
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
Dynamic: license-file

# py-tjbrhk-toolkit

#### 介绍

天津博瑞皓科博瑞云音箱 Python 客户端库，实现官方《博瑞云音箱 API 对接文档》中定义的全部接口。

`py-tjbrhk-toolkit` 是天津博瑞皓科博瑞云音箱 API 的 Python 客户端库。它严格基于 [官方文档（语雀）](https://www.yuque.com/lingdutuandui/ugcpag/umbzsd) 实现，覆盖以下全部接口：

| 接口 | 版本 | 类型 | 官方说明 |
|------|------|------|----------|
| notify.php | 3.1 | 流量版专用 | 将通知消息提交到云音箱服务器，云音箱接收后通过 TTS 播报。仅适用于流量版（2G/4G）音箱。 |
| bind.php | 2.1 | 基础接口 | 云音箱绑定或解绑，支持绑定（m=1）、解绑（m=0）和强制解绑（m=4）。 |
| add.php | 2.2 | 基础接口 | 将支付结果提交到云音箱服务器，云音箱播报收款提示语音。price 单位为分。 |
| modify_bootvoicewav.php | 3.2 | 灰度测试 | 更改开机语音、自定义播报前缀。仅适用于 402、404、502、504 型号。 |

**接口约定（来自官方文档）：**
- 所有接口均为 `POST` 请求，以 `application/x-www-form-urlencoded` 提交表单数据。
- 返回 JSON 格式 `{"errcode", "errmsg", "detail"}`，`errcode` 为 0 即视为业务成功。
- 本库不涉及登录与 Token 缓存，Token 由调用方自行管理并传入。

#### 软件架构

```text
py_tjbrhk_toolkit/
├── pyproject.toml
├── README.md
├── README.en.md
├── LICENSE
├── src/
│   └── py_tjbrhk_toolkit/
│       ├── __init__.py
│       ├── py.typed
│       └── speaker/
│           ├── __init__.py
│           ├── client.py     # SpeakerClient（同步）与 AsyncSpeakerClient（异步）
│           └── models.py     # Pydantic 响应模型
├── tests/
│   └── speaker/
│       ├── __init__.py
│       ├── conftest.py
│       ├── test_speaker_sync.py
│       └── test_speaker_async.py
└── examples/
    └── speaker/
        ├── __init__.py
        ├── .env.example
        ├── example_common.py
        ├── example_notify.py
        ├── example_bind.py
        ├── example_add.py
        ├── example_modify_boot_voice_wav.py
        ├── example_async_notify.py
        ├── example_async_bind.py
        ├── example_async_add.py
        └── example_async_modify_boot_voice_wav.py
```

#### 安装教程

推荐使用 `uv` 安装：

```bash
uv add py-tjbrhk-toolkit
```

或使用 `pip` 安装：

```bash
pip install py-tjbrhk-toolkit
```

从本地源码安装（开发模式）：

```bash
uv venv .venv
source .venv/bin/activate
uv pip install -e .
uv pip install -e ".[dev]"
```

#### 使用说明

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

client = SpeakerClient(
    base_url="https://speaker.17laimai.cn/",
    token="your_token",
    id="your_speaker_id",
    version="1",
)

# 通知语音播报（流量版专用）
response = client.notify(message="[123]收款66元", vol=80)
print(response.json())

# 云音箱绑定（m=1 绑定，0 解绑，4 强制解绑）
response = client.bind(m=1, uid="user_123")

# 支付语音播报（price 单位为分）
response = client.add(price="3879", pt=1, vol=80)

# 更改语音信息（灰度测试，仅 402/404/502/504）
response = client.modify_boot_voice_wav(sound="欢迎光临", type=0, off_text="谢谢使用")

client.close()
```

异步模式：

```python
import asyncio
from py_tjbrhk_toolkit.speaker.client import AsyncSpeakerClient


async def main():
    client = AsyncSpeakerClient(
        base_url="https://speaker.17laimai.cn/",
        token="your_token",
        id="your_speaker_id",
        version="1",
    )
    response = await client.async_notify(message="Hello World")
    print(response.json())
    await client.close()


asyncio.run(main())
```

所有客户端均支持 `with` / `async with` 上下文管理器，退出时自动关闭底层 httpx 客户端。

#### 参与贡献

欢迎提交 Issue 和 Pull Request。在提交 PR 之前，请先运行测试并确保代码符合项目规范。

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

```bash
uv pip install -e ".[dev]"
pytest
```

#### 特技

1. 基于 `httpx` 与 `pydantic`，提供同步（`SpeakerClient`）与异步（`AsyncSpeakerClient`）两种客户端。
2. 严格基于官方 API 文档实现全部接口，支持 `with` / `async with` 上下文管理器，退出时自动关闭底层客户端。
3. 提供中英文双语 README（`README.md` / `README.en.md`）。
4. 采用 MIT 开源许可协议。
