py-tjbrhk-toolkit

天津博瑞皓科 Python 客户端库，提供与天津博瑞皓科 API 交互的完整功能支持。

特性

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

安装

使用 uv（推荐）

uv add py-tjbrhk-toolkit

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

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

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

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

使用 pip

pip install py-tjbrhk-toolkit

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

pip install -e .

快速开始

同步模式

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()

异步模式

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 客户端。

返回码（errcode）

依赖包

测试

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

目录结构

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  # 异步示例：更改语音信息

项目信息

许可证

MIT License