Metadata-Version: 2.4
Name: py-tjbrhk-toolkit
Version: 3.0.6
Summary: 天津博瑞皓科 Python 客户端库，提供与天津博瑞皓科博瑞云音箱 API 交互的完整功能支持 / Tianjin Bojrhao Ke Cloud Speaker Python Client Library
Author-email: 郭磊 <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_toolkit
Project-URL: Repository, https://gitee.com/guolei19850528/py_tjbrhk_toolkit
Project-URL: Package, https://pypi.org/project/py-tjbrhk-toolkit/
Keywords: tjbrhk,天津博瑞皓科,博瑞云音箱,cloud-speaker,speaker,python,client,api,httpx,pydantic,sync,async
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
Dynamic: license-file

# py-tjbrhk-toolkit

[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![PyPI](https://img.shields.io/badge/pypi-py--tjbrhk--toolkit-blue.svg)](https://pypi.org/project/py-tjbrhk-toolkit/) [![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/) [![Tianjin Bojrhao Ke](https://img.shields.io/badge/Tianjin%20Bojrhao%20Ke-Cloud%20Speaker-green.svg)](https://www.yuque.com/lingdutuandui/ugcpag/umbzsd)

## 文档语言
- [中文 (README.md)](README.md)
- [English (README.en.md)](README.en.md)

## 介绍

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

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

### 核心特性
- **基于官方 API 文档**：严格基于《博瑞云音箱 API 对接文档》实现全部接口，包括 notify.php、bind.php、add.php、modify_bootvoicewav.php。
- **同步 / 异步双模客户端**：同时提供同步（`SpeakerClient`）与异步（`AsyncSpeakerClient`）客户端，方法名完全一致，支持 `with` / `async with` 上下文管理器。
- **基于 httpx**：底层 HTTP 客户端使用 httpx，支持同步与异步请求。
- **Pydantic 响应模型**：所有 API 响应基于 Pydantic 构建，字段自动校验，类型安全。
- **自动关闭连接池**：客户端退出时自动关闭底层 httpx 客户端连接。

### 参考文档
- [博瑞云音箱 API 对接文档（语雀）](https://www.yuque.com/lingdutuandui/ugcpag/umbzsd)

## 软件架构

```text
py_tjbrhk_toolkit/
├── pyproject.toml          # 项目构建配置（PEP 621 / setuptools）
├── README.md               # 项目说明文档（中文）
├── README.en.md            # 项目说明文档（英文）
├── LICENSE                 # MIT 许可证
├── uv.lock                 # 依赖锁定文件
├── src/
│   └── py_tjbrhk_toolkit/  # 源代码包
│       ├── __init__.py     # 包入口，导出主要客户端类
│       ├── py.typed        # PEP 561 类型标记
│       └── 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](https://github.com/astral-sh/uv) 进行安装：

### 1. 基础安装（推荐 uv）

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

### 2. 开发环境安装（包含测试、代码检查工具）

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

### 3. 从源码安装

```bash
git clone https://gitee.com/guolei19850528/py_tjbrhk_toolkit.git
cd py_tjbrhk_toolkit
uv venv .venv
source .venv/bin/activate
uv pip install -e .
uv pip install -e ".[dev]"
```

## 使用说明

### 一、接口列表

| 接口 | 版本 | 类型 | 官方说明 |
|------|------|------|----------|
| 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 由调用方自行管理并传入。

### 二、快速开始

#### 1. 创建客户端

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

# 同步客户端
client = SpeakerClient(
    base_url="https://speaker.17laimai.cn/",
    token="your_token",
    id="your_speaker_id",
    version="1",
)

# 异步客户端
async_client = AsyncSpeakerClient(
    base_url="https://speaker.17laimai.cn/",
    token="your_token",
    id="your_speaker_id",
    version="1",
)
```

推荐使用上下文管理器，自动管理 HTTP 连接池：

```python
with SpeakerClient(
    base_url="https://speaker.17laimai.cn/",
    token="your_token",
    id="your_speaker_id",
    version="1",
) as client:
    # 使用 client 调用接口
    pass

import asyncio

async def main():
    async with AsyncSpeakerClient(
        base_url="https://speaker.17laimai.cn/",
        token="your_token",
        id="your_speaker_id",
        version="1",
    ) as client:
        # 使用 client 调用接口
        pass

asyncio.run(main())
```

#### 2. 通知语音播报（流量版专用）

```python
with SpeakerClient(
    base_url="https://speaker.17laimai.cn/",
    token="your_token",
    id="your_speaker_id",
    version="1",
) as client:
    response = client.notify(message="[123]收款66元", vol=80)
    print(response.json())
```

#### 3. 云音箱绑定（m=1 绑定，0 解绑，4 强制解绑）

```python
with SpeakerClient(
    base_url="https://speaker.17laimai.cn/",
    token="your_token",
    id="your_speaker_id",
    version="1",
) as client:
    response = client.bind(m=1, uid="user_123")
    print(response.json())
```

#### 4. 支付语音播报（price 单位为分）

```python
with SpeakerClient(
    base_url="https://speaker.17laimai.cn/",
    token="your_token",
    id="your_speaker_id",
    version="1",
) as client:
    response = client.add(price="3879", pt=1, vol=80)
    print(response.json())
```

#### 5. 更改语音信息（灰度测试，仅 402/404/502/504）

```python
with SpeakerClient(
    base_url="https://speaker.17laimai.cn/",
    token="your_token",
    id="your_speaker_id",
    version="1",
) as client:
    response = client.modify_boot_voice_wav(sound="欢迎光临", type=0, off_text="谢谢使用")
    print(response.json())
```

异步模式示例：

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


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


asyncio.run(main())
```

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

### 三、异常处理

所有 API 调用失败时会抛出相应异常，建议使用 try/except 进行捕获：

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

try:
    with SpeakerClient(
        base_url="https://speaker.17laimai.cn/",
        token="your_token",
        id="your_speaker_id",
        version="1",
    ) as client:
        response = client.notify(message="Hello", vol=80)
        print(response.json())
except Exception as e:
    print(f"调用失败: {e}")
```

### 四、贡献指南

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

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

### 五、许可证

本项目采用 [MIT 许可证](LICENSE)。
