Metadata-Version: 2.4
Name: py-tjbrhk-toolkit
Version: 3.0.0
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 交互的完整功能支持。

## 特性

- 支持同步和异步两种请求模式
- 基于 Pydantic 的数据验证
- 实现博瑞云音箱 API 对接文档（https://www.yuque.com/lingdutuandui/ugcpag/umbzsd）中的全部接口
- 所有接口均返回 JSON ``{errcode, errmsg, detail}``，``errcode`` 为 0 即视为成功
- 不涉及登录与 Token 缓存

## 安装

### 使用 uv（推荐）

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

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

```bash
# 创建并激活 .venv 环境
uv venv .venv
source .venv/bin/activate

# 安装生产依赖（开发模式）
uv pip install -e .

# 安装开发依赖（pytest / pytest-asyncio / python-dotenv 等）
uv pip install -e ".[dev]"
```

### 使用 pip

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

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

```bash
pip install -e .
```

## 快速开始

### 同步模式

```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",
)

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

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

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

# 4. 更改语音信息（灰度测试，仅 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())
```

## 接口列表

| 接口 | 同步方法 | 异步方法 | URL | 说明 |
|------|----------|----------|-----|------|
| 通知语音播报 | `notify(message, ...)` | `async_notify(message, ...)` | `/notify.php` | 流量版（2G/4G）专用，TTS 播报 |
| 云音箱绑定/解绑 | `bind(m, uid, ...)` | `async_bind(m, uid, ...)` | `/bind.php` | m: 0解绑/1绑定/4强制解绑 |
| 支付语音播报 | `add(price, ...)` | `async_add(price, ...)` | `/add.php` | price 单位为分 |
| 更改语音信息 | `modify_boot_voice_wav(sound, type, ...)` | `async_modify_boot_voice_wav(sound, type, ...)` | `/modify_bootvoicewav.php` | 灰度测试，仅 402/404/502/504 |

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

### 返回码（errcode）

| 码 | 说明 |
|---|------|
| 0 | 成功 |
| 1 | 未知错误 |
| 2 | SPEAKERID 不存在 |
| 3 | SPEAKERID 已经被其它用户 ID 绑定 |
| 4 | SPEAKERID 已经被同一用户 ID 绑定 |
| 5 | SPEAKERID 未被任何用户 ID 绑定 |
| 6 | 未提供 SPEAKERID |
| 8 | 此 token 无此 SPEAKERID 权限 |
| 9 | 无效的 token |
| 17 | 重复的请求 |

## 依赖包

| 依赖 | 版本要求 | 说明 |
|------|----------|------|
| httpx | >=0.24.0 | HTTP 客户端库 |
| pydantic | >=2.0 | 数据验证库 |

## 测试

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

## 目录结构

```text
py_tjbrhk_toolkit/
├── pyproject.toml
├── README.md
├── 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  # 异步示例：更改语音信息
```

## 项目信息

| 项目 | 说明 |
|------|------|
| 作者 | 郭磊 |
| 邮箱 | 174000902@qq.com |
| 项目主页 | https://gitee.com/guolei19850528/py_tjbrhk_toolkit |
| 仓库 | https://gitee.com/guolei19850528/py_tjbrhk_toolkit.git |
| PyPI | https://pypi.org/project/py-tjbrhk-toolkit/ |
| 官方文档 | https://www.yuque.com/lingdutuandui/ugcpag/umbzsd |

## 许可证

MIT License
