Metadata-Version: 2.5
Name: py-tjbrhk-toolkit
Version: 4.1.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: all
Requires-Dist: mkdocs-material>=9.0.0; extra == 'all'
Requires-Dist: mkdocs>=1.5.0; extra == 'all'
Requires-Dist: mypy>=1.10.0; extra == 'all'
Requires-Dist: pre-commit>=3.7.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
Requires-Dist: pytest-cov>=5.0.0; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Requires-Dist: python-dotenv>=1.0.0; extra == 'all'
Requires-Dist: respx>=0.21.0; extra == 'all'
Requires-Dist: ruff>=0.8.0; extra == 'all'
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'
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'
Requires-Dist: respx>=0.21.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)

## 功能

- **博瑞云音箱 notify 接口**：提交通知语音播报，支持同步和异步客户端，均支持上下文管理器以自动关闭 HTTP 连接。
- **类型模型**：基于 Pydantic 定义响应模型。

## 安装

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

使用 uv：

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

需要开发与测试工具时，从仓库安装：

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

## 包结构

```text
py_tjbrhk_toolkit/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── py_tjbrhk_toolkit/
│       ├── __init__.py
│       ├── py.typed
│       └── speaker/
│           ├── __init__.py
│           ├── _clients.py      # 内部实现：同步与异步通知客户端
│           └── _models.py       # 内部实现：通知接口响应模型
├── examples/
│   └── speaker/
│       ├── .env.example
│       ├── notify_async.py
│       └── notify_sync.py
└── tests/
    └── speaker/
        ├── .env.example
        ├── conftest.py
        ├── test_notify_async.py
        └── test_notify_sync.py
```

包根导出 `speaker` 模块。各模块对外公开的名称带有 `Speaker` 前缀，避免名称冲突；`_` 开头的文件是内部实现模块。

## 使用

### 1. speaker 模块 - 云音箱通知

博瑞云音箱模块通过 Token 和 ID 初始化客户端。`notify` 支持发送语音播报通知。

#### 1.1 同步发送通知

```python
from py_tjbrhk_toolkit.speaker import SpeakerClient

with SpeakerClient(
    token="你的云音箱 Token",
    id="你的云音箱 ID",
) as client:
    response = client.notify(
        message="您好，欢迎光临",
        vol=80,
    )
    print(response.model_dump())
    print("发送成功:", response.ok)
```

#### 1.2 异步发送通知

```python
import asyncio

from py_tjbrhk_toolkit.speaker import SpeakerAsyncClient


async def main() -> None:
    async with SpeakerAsyncClient(
        token="你的云音箱 Token",
        id="你的云音箱 ID",
    ) as client:
        response = await client.notify(
            message="收到一笔新的付款",
            vol=80,
        )
        print(response.model_dump())
        print("发送成功:", response.ok)


asyncio.run(main())
```

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

#### 1.3 客户端配置

同步客户端 `SpeakerClient` 和异步客户端 `SpeakerAsyncClient` 使用相同的构造参数：

| 参数 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `token` | 是 | — | 云音箱 Token。 |
| `id` | 是 | — | 云音箱 ID。 |
| `base_url` | 否 | `https://speaker.17laimai.cn` | 云音箱服务接口地址。 |
| `version` | 否 | `1` | 接口版本。 |
| `timeout` | 否 | `30.0` | HTTP 请求超时时间，单位为秒。 |

#### 1.4 通知发送参数及响应

`notify(message, *, seq=None, vol=None, speed=None, trace_no=None, id=None, token=None, version=None)` 支持以下参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `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` | 否 | 覆盖客户端配置的接口版本 |

接口返回 `SpeakerNotifyResponse`，其属性 `errcode`、`errmsg`、`detail` 与接口响应字段一致；`response.ok` 在 `errcode` 等于 `0` 或 `"0"` 时为 `True`。

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

#### 1.5 使用环境变量运行示例

示例脚本从**仓库根目录**加载 `.env` 文件，且系统中已有的环境变量优先。复制配置模板并填写云音箱 ID 和 Token：

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

完成配置后运行同步或异步示例：

```bash
python examples/speaker/notify_sync.py
```

```bash
python examples/speaker/notify_async.py
```

`.env` 文件包含设备凭据，请勿提交到版本控制。

#### 1.6 异常处理

客户端配置无效或请求参数不符合校验时会产生 `ValueError`；HTTP 网络请求失败时会产生 `ConnectionError`。调用方可根据需要显式处理：

```python
try:
    # 在此处初始化客户端并调用 notify。
    ...
except (ValueError, ConnectionError) as exc:
    print(f"云音箱请求失败：{exc}")
```

## 配置示例与测试

示例脚本读取环境变量；仓库提供 [examples/speaker/.env.example](examples/speaker/.env.example) 作为配置模板。将所需变量设置在仓库根目录的 `.env` 中，或在运行脚本前导出环境变量。

测试配置位于 [tests/speaker/.env.example](tests/speaker/.env.example)。复制到对应测试目录的 `.env` 并填入有效凭证。配置包含 `BASE_URL`、`ID`、`TOKEN` 和 `VERSION`。

```bash
pytest
```

测试配置在缺少必需环境变量时会跳过相应测试。pytest 默认配置会输出终端、HTML 和 XML 覆盖率报告。

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

## 开发

```bash
ruff check .
ruff format --check .
python -m compileall -q src examples tests
```

项目支持 Python 3.9 及以上版本。核心依赖包括 httpx 和 Pydantic；开发、测试、文档工具可通过 `pyproject.toml` 中的可选依赖组安装。

## 作者信息

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

## 许可证

本项目基于 [MIT 许可证](LICENSE) 开源。
