py-tjbrhk-toolkit 1.0.0__tar.gz

py_tjbrhk_toolkit-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+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.

py_tjbrhk_toolkit-1.0.0/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: py-tjbrhk-toolkit
+Version: 1.0.0
+Summary: 一个用于与天津博瑞皓科 API 交互的 Python 客户端库
+Author-email: Guolei <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.git
+Keywords: 天津博瑞皓科,tjbrhk,python,client,智能云音箱,api
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: jsonpath-ng>=1.5.3
+Requires-Dist: jsonschema>=4.21.0
+Requires-Dist: py-httpx-toolkit>=1.0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: setuptools>=61.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# py-tjbrhk-toolkit
+
+天津博瑞皓科 Python 客户端库，提供与天津博瑞皓科 API 交互的完整功能支持。
+
+## 特性
+
+- 支持同步和异步两种请求模式
+- 提供通知发送功能
+- 基于 Pydantic 的数据验证
+- JSONPath 数据查询支持
+- JSON Schema 校验功能
+
+## 安装
+
+### 使用 uv（推荐）
+
+```bash
+uv add py-tjbrhk-toolkit
+```
+
+### 使用 pip
+
+```bash
+pip install py-tjbrhk-toolkit
+```
+
+
+## 依赖包
+
+| 依赖 | 版本要求 | 说明 |
+|------|----------|------|
+| httpx | >=0.27.0 | HTTP 客户端库 |
+| pydantic | >=2.0 | 数据验证库 |
+| jsonpath-ng | >=1.5.3 | JSONPath 查询库 |
+| jsonschema | >=4.21.0 | JSON Schema 校验库 |
+| py-httpx-toolkit | >=1.0.1 | HTTP 工具库 |
+
+## 快速开始
+
+### 同步模式
+
+```python
+from py_tjbrhk_toolkit.speaker import Speaker
+
+# 初始化客户端
+client = Speaker(
+    base_url="https://speaker.17laimai.cn",
+    token="your_token",
+    id="your_id",
+    version="1"
+)
+
+# 发送通知
+response = client.notify(message="Hello World")
+print(response.json())
+```
+
+### 异步模式
+
+```python
+import asyncio
+from py_tjbrhk_toolkit.speaker import Speaker
+
+async def main():
+    # 初始化客户端
+    client = Speaker(
+        base_url="https://speaker.17laimai.cn",
+        token="your_token",
+        id="your_id",
+        version="1"
+    )
+    
+    # 异步发送通知
+    response = await client.async_notify(message="Hello World")
+    print(response.json())
+
+asyncio.run(main())
+```
+
+## API 文档
+
+### Speaker 客户端
+
+#### 初始化参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| base_url | str | https://speaker.17laimai.cn | Speaker 服务器地址 |
+| token | str | "" | API 认证 Token |
+| id | str | "" | API 认证 ID |
+| version | str | "1" | API 版本号 |
+| client_kwargs | dict | None | httpx.Client 额外配置 |
+
+#### notify(message, client=None, client_kwargs=None, **kwargs)
+
+发送同步通知请求
+
+**参数**:
+- `message`: 要发送的内容
+- `client`: 自定义 httpx.Client 实例
+- `client_kwargs`: 客户端配置参数
+- `**kwargs`: 传递给 httpx 请求的额外参数
+
+**返回**: `httpx.Response` - HTTP 响应对象
+
+#### async_notify(message, client=None, client_kwargs=None, **kwargs)
+
+发送异步通知请求
+
+**参数**:
+- `message`: 要发送的内容
+- `client`: 自定义 httpx.AsyncClient 实例
+- `client_kwargs`: 客户端配置参数
+- `**kwargs`: 传递给 httpx 请求的额外参数
+
+**返回**: `httpx.Response` - HTTP 响应对象
+
+### 工具函数
+
+#### json_find_first(expression, data)
+
+使用 JSONPath 表达式从数据中查找第一个匹配项
+
+```python
+from py_tjbrhk_toolkit.speaker.utils import json_find_first
+
+data = {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}
+result = json_find_first("$.users[0].name", data)
+print(result)  # Alice
+```
+
+#### json_is_valid(schema, data)
+
+校验 JSON 数据是否符合指定的 JSON Schema
+
+```python
+from py_tjbrhk_toolkit.speaker.utils import json_is_valid
+
+schema = {"type": "object", "properties": {"name": {"type": "string"}}}
+data = {"name": "test"}
+valid = json_is_valid(schema, data)
+print(valid)  # True
+```
+
+#### build_success_instance(response)
+
+将 HTTP 响应或字典转换为 Success 模型对象
+
+```python
+from py_tjbrhk_toolkit.speaker.utils import build_success_instance
+
+response = {"errcode": 0, "errmsg": "success"}
+result = build_success_instance(response)
+print(result.errcode)  # 0
+```
+
+#### success_is_valid(response, schema=None)
+
+校验 HTTP 响应或字典是否符合成功响应的 JSON Schema
+
+```python
+from py_tjbrhk_toolkit.speaker.utils import success_is_valid
+
+response = {"errcode": 0, "errmsg": "success"}
+valid = success_is_valid(response)
+print(valid)  # True
+```
+
+### 响应模型
+
+#### Base
+
+响应基类，包含错误码和错误信息字段
+
+```python
+from py_tjbrhk_toolkit.speaker.responses import Base
+
+response = Base(errcode=0, errmsg="success")
+```
+
+#### Success
+
+成功响应模型，继承自 Base
+
+```python
+from py_tjbrhk_toolkit.speaker.responses import Success
+
+response = Success(errcode=0, errmsg="success")
+```
+
+## 示例代码
+
+### 完整示例
+
+```python
+from py_tjbrhk_toolkit.speaker import Speaker
+from py_tjbrhk_toolkit.speaker.utils import build_success_instance, success_is_valid
+
+# 初始化客户端
+client = Speaker(
+    token="your_token",
+    id="your_id"
+)
+
+# 发送通知
+response = client.notify(message="测试通知")
+
+# 验证响应
+if success_is_valid(response):
+    result = build_success_instance(response)
+    print(f"发送成功: {result.errmsg}")
+else:
+    print("发送失败")
+```
+
+### 异步完整示例
+
+```python
+import asyncio
+from py_tjbrhk_toolkit.speaker import Speaker
+from py_tjbrhk_toolkit.speaker.utils import build_success_instance, success_is_valid
+
+async def send_notification():
+    client = Speaker(
+        token="your_token",
+        id="your_id"
+    )
+    
+    response = await client.async_notify(message="异步测试通知")
+    
+    if success_is_valid(response):
+        result = build_success_instance(response)
+        print(f"发送成功: {result.errmsg}")
+    else:
+        print("发送失败")
+
+asyncio.run(send_notification())
+```
+
+## 作者
+
+Guolei <174000902@qq.com>
+
+## 项目主页
+
+[https://gitee.com/guolei19850528/py_tjbrhk_toolkit](https://gitee.com/guolei19850528/py_tjbrhk_toolkit)
+
+## 官方文档
+
+[https://www.yuque.com/lingdutuandui/ugcpag/umbzsd](https://www.yuque.com/lingdutuandui/ugcpag/umbzsd)
+
+## 许可证
+
+MIT License

py_tjbrhk_toolkit-1.0.0/README.md

@@ -0,0 +1,254 @@
+# py-tjbrhk-toolkit
+
+天津博瑞皓科 Python 客户端库，提供与天津博瑞皓科 API 交互的完整功能支持。
+
+## 特性
+
+- 支持同步和异步两种请求模式
+- 提供通知发送功能
+- 基于 Pydantic 的数据验证
+- JSONPath 数据查询支持
+- JSON Schema 校验功能
+
+## 安装
+
+### 使用 uv（推荐）
+
+```bash
+uv add py-tjbrhk-toolkit
+```
+
+### 使用 pip
+
+```bash
+pip install py-tjbrhk-toolkit
+```
+
+
+## 依赖包
+
+| 依赖 | 版本要求 | 说明 |
+|------|----------|------|
+| httpx | >=0.27.0 | HTTP 客户端库 |
+| pydantic | >=2.0 | 数据验证库 |
+| jsonpath-ng | >=1.5.3 | JSONPath 查询库 |
+| jsonschema | >=4.21.0 | JSON Schema 校验库 |
+| py-httpx-toolkit | >=1.0.1 | HTTP 工具库 |
+
+## 快速开始
+
+### 同步模式
+
+```python
+from py_tjbrhk_toolkit.speaker import Speaker
+
+# 初始化客户端
+client = Speaker(
+    base_url="https://speaker.17laimai.cn",
+    token="your_token",
+    id="your_id",
+    version="1"
+)
+
+# 发送通知
+response = client.notify(message="Hello World")
+print(response.json())
+```
+
+### 异步模式
+
+```python
+import asyncio
+from py_tjbrhk_toolkit.speaker import Speaker
+
+async def main():
+    # 初始化客户端
+    client = Speaker(
+        base_url="https://speaker.17laimai.cn",
+        token="your_token",
+        id="your_id",
+        version="1"
+    )
+    
+    # 异步发送通知
+    response = await client.async_notify(message="Hello World")
+    print(response.json())
+
+asyncio.run(main())
+```
+
+## API 文档
+
+### Speaker 客户端
+
+#### 初始化参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| base_url | str | https://speaker.17laimai.cn | Speaker 服务器地址 |
+| token | str | "" | API 认证 Token |
+| id | str | "" | API 认证 ID |
+| version | str | "1" | API 版本号 |
+| client_kwargs | dict | None | httpx.Client 额外配置 |
+
+#### notify(message, client=None, client_kwargs=None, **kwargs)
+
+发送同步通知请求
+
+**参数**:
+- `message`: 要发送的内容
+- `client`: 自定义 httpx.Client 实例
+- `client_kwargs`: 客户端配置参数
+- `**kwargs`: 传递给 httpx 请求的额外参数
+
+**返回**: `httpx.Response` - HTTP 响应对象
+
+#### async_notify(message, client=None, client_kwargs=None, **kwargs)
+
+发送异步通知请求
+
+**参数**:
+- `message`: 要发送的内容
+- `client`: 自定义 httpx.AsyncClient 实例
+- `client_kwargs`: 客户端配置参数
+- `**kwargs`: 传递给 httpx 请求的额外参数
+
+**返回**: `httpx.Response` - HTTP 响应对象
+
+### 工具函数
+
+#### json_find_first(expression, data)
+
+使用 JSONPath 表达式从数据中查找第一个匹配项
+
+```python
+from py_tjbrhk_toolkit.speaker.utils import json_find_first
+
+data = {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}
+result = json_find_first("$.users[0].name", data)
+print(result)  # Alice
+```
+
+#### json_is_valid(schema, data)
+
+校验 JSON 数据是否符合指定的 JSON Schema
+
+```python
+from py_tjbrhk_toolkit.speaker.utils import json_is_valid
+
+schema = {"type": "object", "properties": {"name": {"type": "string"}}}
+data = {"name": "test"}
+valid = json_is_valid(schema, data)
+print(valid)  # True
+```
+
+#### build_success_instance(response)
+
+将 HTTP 响应或字典转换为 Success 模型对象
+
+```python
+from py_tjbrhk_toolkit.speaker.utils import build_success_instance
+
+response = {"errcode": 0, "errmsg": "success"}
+result = build_success_instance(response)
+print(result.errcode)  # 0
+```
+
+#### success_is_valid(response, schema=None)
+
+校验 HTTP 响应或字典是否符合成功响应的 JSON Schema
+
+```python
+from py_tjbrhk_toolkit.speaker.utils import success_is_valid
+
+response = {"errcode": 0, "errmsg": "success"}
+valid = success_is_valid(response)
+print(valid)  # True
+```
+
+### 响应模型
+
+#### Base
+
+响应基类，包含错误码和错误信息字段
+
+```python
+from py_tjbrhk_toolkit.speaker.responses import Base
+
+response = Base(errcode=0, errmsg="success")
+```
+
+#### Success
+
+成功响应模型，继承自 Base
+
+```python
+from py_tjbrhk_toolkit.speaker.responses import Success
+
+response = Success(errcode=0, errmsg="success")
+```
+
+## 示例代码
+
+### 完整示例
+
+```python
+from py_tjbrhk_toolkit.speaker import Speaker
+from py_tjbrhk_toolkit.speaker.utils import build_success_instance, success_is_valid
+
+# 初始化客户端
+client = Speaker(
+    token="your_token",
+    id="your_id"
+)
+
+# 发送通知
+response = client.notify(message="测试通知")
+
+# 验证响应
+if success_is_valid(response):
+    result = build_success_instance(response)
+    print(f"发送成功: {result.errmsg}")
+else:
+    print("发送失败")
+```
+
+### 异步完整示例
+
+```python
+import asyncio
+from py_tjbrhk_toolkit.speaker import Speaker
+from py_tjbrhk_toolkit.speaker.utils import build_success_instance, success_is_valid
+
+async def send_notification():
+    client = Speaker(
+        token="your_token",
+        id="your_id"
+    )
+    
+    response = await client.async_notify(message="异步测试通知")
+    
+    if success_is_valid(response):
+        result = build_success_instance(response)
+        print(f"发送成功: {result.errmsg}")
+    else:
+        print("发送失败")
+
+asyncio.run(send_notification())
+```
+
+## 作者
+
+Guolei <174000902@qq.com>
+
+## 项目主页
+
+[https://gitee.com/guolei19850528/py_tjbrhk_toolkit](https://gitee.com/guolei19850528/py_tjbrhk_toolkit)
+
+## 官方文档
+
+[https://www.yuque.com/lingdutuandui/ugcpag/umbzsd](https://www.yuque.com/lingdutuandui/ugcpag/umbzsd)
+
+## 许可证
+
+MIT License

py_tjbrhk_toolkit-1.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+[project]
+name = "py-tjbrhk-toolkit"
+version = "1.0.0"
+requires-python = ">=3.10"
+authors = [
+    { name = "Guolei", email = "174000902@qq.com" }
+]
+description = "一个用于与天津博瑞皓科 API 交互的 Python 客户端库"
+keywords = ["天津博瑞皓科", "tjbrhk", "python", "client","智能云音箱", "api"]
+license = { file = "LICENSE" }
+readme = "README.md"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0",
+    "jsonpath-ng>=1.5.3",
+    "jsonschema>=4.21.0",
+    "py-httpx-toolkit>=1.0.1",
+]
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "setuptools>=61.0",
+    "twine>=4.0",
+]
+
+[project.urls]
+"Homepage" = "https://gitee.com/guolei19850528/py_tjbrhk_toolkit"
+"Repository" = "https://gitee.com/guolei19850528/py_tjbrhk_toolkit.git"
+
+[tool.setuptools.packages.find]
+where = ["src"]

py_tjbrhk_toolkit-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

py_tjbrhk_toolkit-1.0.0/src/py_tjbrhk_toolkit/__init__.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+py_tjbrhk - 天津博瑞皓科 Python 客户端库
+
+提供与天津博瑞皓科 API 交互的完整功能支持。
+
+官方文档: https://www.yuque.com/lingdutuandui/ugcpag/umbzsd
+"""

py_tjbrhk_toolkit-1.0.0/src/py_tjbrhk_toolkit/speaker/__init__.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+天津博瑞皓科 Speaker 客户端库
+
+提供与天津博瑞皓科 Speaker API 交互的 Python 客户端实现。
+支持同步和异步两种请求模式，提供通知发送功能。
+
+官方文档: https://www.yuque.com/lingdutuandui/ugcpag/umbzsd
+"""
+
+from typing import Optional
+
+import httpx
+from pydantic import HttpUrl
+
+from py_httpx_toolkit import Httpx
+
+
+class Speaker(Httpx):
+    def __init__(
+            self,
+            base_url: Optional[str] = "https://speaker.17laimai.cn",
+            token: Optional[str] = "",
+            id: Optional[str] = "",
+            version: Optional[str] = "1",
+            client_kwargs: Optional[dict] = None,
+    ):
+        """
+        初始化 Speaker 客户端
+
+        创建与 Speaker 交互的客户端实例，配置连接参数和认证密钥。
+
+        参数:
+            base_url (Optional[HttpUrl]): Speaker 服务器地址，如 "https://speaker.17laimai.cn"
+            token (Optional[str]): Token，用于 API 认证
+            id (Optional[str]): ID，用于 API 认证
+            version (Optional[str]): 版本号，用于 API 认证
+            client_kwargs (Optional[dict]): 传递给 httpx.Client 的额外配置参数
+
+        配置说明:
+            - base_url 会自动去除末尾的斜杠
+            - 默认配置: base_url=base_url, verify=False, timeout=60
+            - client_kwargs 中的参数会覆盖默认配置
+        """
+        self.base_url = base_url or ""
+        self.base_url = self.base_url[:-1] if self.base_url.endswith("/") else self.base_url
+        self.token = token or ""
+        self.id = id or ""
+        self.version = version or "1"
+        self.client_kwargs = client_kwargs or {}
+        self.client_kwargs = {
+            **{
+                "base_url": self.base_url,
+                "verify": False,
+                "timeout": 60,
+            },
+            **self.client_kwargs,
+        }
+
+    def notify(
+            self,
+            message: str = "",
+            client: Optional[httpx.Client] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        发送同步 HTTP 请求
+
+        支持传入自定义客户端或使用内置客户端。
+
+        参数:
+            client (Optional[httpx.Client]): 自定义的 httpx.Client 实例，若为 None 则自动创建
+            message (str): 要发送的内容，将作为 POST 请求体的 message 字段发送
+            **kwargs: 传递给 httpx.Client.request 的参数，包括 method、url、headers、data、json 等
+
+        返回:
+            httpx.Response: HTTP 响应对象
+        """
+        client = client or None
+        client_kwargs = client_kwargs or {}
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "method": "POST",
+                "url": "/notify.php",
+                "data": {
+                    "token": self.token,
+                    "id": self.id,
+                    "version": self.version,
+                    "message": message,
+                }
+            },
+            **kwargs
+        }
+        return self.request(client=client, client_kwargs=client_kwargs, **kwargs)
+
+    async def async_notify(
+            self,
+            message: str = "",
+            client: Optional[httpx.AsyncClient] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        发送异步 HTTP 请求
+
+        支持传入自定义客户端或使用内置客户端。
+
+        参数:
+            client (Optional[httpx.AsyncClient]): 自定义的 httpx.AsyncClient 实例，若为 None 则自动创建
+            message (str): 要发送的内容，将作为 POST 请求体的 message 字段发送
+            **kwargs: 传递给 httpx.Client.request 的参数，包括 method、url、headers、data、json 等
+
+        返回:
+            httpx.Response: HTTP 响应对象
+        """
+        client = client or None
+        client_kwargs = client_kwargs or {}
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "method": "POST",
+                "url": "/notify.php",
+                "data": {
+                    "token": self.token,
+                    "id": self.id,
+                    "version": self.version,
+                    "message": message,
+                }
+            },
+            **kwargs
+        }
+        return await self.async_request(client=client, client_kwargs=client_kwargs, **kwargs)

py_tjbrhk_toolkit-1.0.0/src/py_tjbrhk_toolkit/speaker/responses.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+响应模型模块
+
+定义 API 响应的数据模型，基于 Pydantic 实现数据验证和类型提示。
+
+官方文档: https://www.yuque.com/lingdutuandui/ugcpag/umbzsd
+"""
+
+from pydantic import BaseModel
+from pydantic import Field
+from typing import Literal, Union, Any, Optional
+
+
+class Base(BaseModel):
+    """
+    iSecure Center响应基类
+    
+    所有API响应都包含错误码和错误信息字段
+    """
+    errcode: Union[int, str] = Field(..., title="错误码", description="错误码，0表示成功，非0表示失败")
+    errmsg: Optional[str] = Field(default=None, title="错误信息", description="错误信息描述")
+
+    model_config = {
+        "extra": "allow"  # 允许额外动态字段
+    }
+
+
+class Success(Base):
+    """
+    成功响应模型
+    
+    继承自Base，用于成功接口的响应
+    """
+    errcode: Literal[0, "0"] = Field(..., title="错误码", description="成功，值为0")

py_tjbrhk_toolkit-1.0.0/src/py_tjbrhk_toolkit/speaker/utils.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+工具函数模块
+
+提供 JSON 数据处理、数据校验等通用工具函数。
+
+官方文档: https://www.yuque.com/lingdutuandui/ugcpag/umbzsd
+"""
+
+import base64
+import hashlib
+import uuid
+from datetime import datetime
+from typing import Any, Optional, Tuple, Union
+
+import httpx
+from jsonpath_ng import parse
+from jsonschema.validators import Draft202012Validator
+
+from .responses import Success
+
+
+def json_find_first(expression: str, data: Any) -> Any:
+    """
+    使用 JSONPath 表达式从数据中查找第一个匹配项
+
+    Args:
+        expression: JSONPath 表达式，用于指定要查找的数据路径
+        data: 待查询的 JSON 数据
+
+    Returns:
+        Any: 第一个匹配的值，如果没有匹配项则返回 None
+    """
+    results = [i.value for i in parse(expression).find(data)]
+    if isinstance(results, list) and len(results) > 0:
+        return results[0]
+    return None
+
+
+def json_is_valid(schema: Optional[dict], data: Any) -> bool:
+    """
+    校验 JSON 数据是否符合指定的 JSON Schema
+
+    Args:
+        schema: JSON Schema 字典
+        data: 待校验的 JSON 数据
+
+    Returns:
+        bool: 校验是否成功
+    """
+    return Draft202012Validator(schema).is_valid(data)
+
+
+def build_success_instance(response: Union[httpx.Response, dict]) -> Success:
+    """
+    将 HTTP 响应或字典转换为 Success 模型对象
+
+    统一处理 httpx.Response 对象和字典，将其转换为标准化的 Success 模型对象。
+
+    参数:
+        response (Union[httpx.Response, dict]): HTTP 响应对象或字典数据
+
+    返回:
+        Success: 标准化的响应模型对象，包含 errcode 和 errmsg 字段
+
+    处理逻辑:
+        - 如果输入是 httpx.Response 对象，先调用 json() 方法解析响应体
+        - 如果输入是字典，直接传入 Success 构造函数
+    """
+    if isinstance(response, httpx.Response):
+        return Success(**response.json())
+    return Success(**response)
+
+
+def success_is_valid(
+        response: Union[httpx.Response, dict] = None,
+        schema: dict = {
+            "type": "object",
+            "properties": {
+                "errcode": {
+                    "oneOf": [
+                        {"type": "integer", "const": 0},
+                        {"type": "string", "const": "0"}
+                    ]
+                },
+            },
+            "required": ["errcode"]
+        }
+):
+    """
+    校验 HTTP 响应或字典是否符合指定的 JSON Schema
+
+    :param response: HTTP 响应对象或字典数据
+    :param schema: JSON Schema 字典
+    :return: 校验是否成功
+    """
+    if isinstance(response, httpx.Response):
+        return json_is_valid(schema, response.json())
+    return json_is_valid(schema, response)

py_tjbrhk_toolkit-1.0.0/src/py_tjbrhk_toolkit.egg-info/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: py-tjbrhk-toolkit
+Version: 1.0.0
+Summary: 一个用于与天津博瑞皓科 API 交互的 Python 客户端库
+Author-email: Guolei <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.git
+Keywords: 天津博瑞皓科,tjbrhk,python,client,智能云音箱,api
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: jsonpath-ng>=1.5.3
+Requires-Dist: jsonschema>=4.21.0
+Requires-Dist: py-httpx-toolkit>=1.0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: setuptools>=61.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# py-tjbrhk-toolkit
+
+天津博瑞皓科 Python 客户端库，提供与天津博瑞皓科 API 交互的完整功能支持。
+
+## 特性
+
+- 支持同步和异步两种请求模式
+- 提供通知发送功能
+- 基于 Pydantic 的数据验证
+- JSONPath 数据查询支持
+- JSON Schema 校验功能
+
+## 安装
+
+### 使用 uv（推荐）
+
+```bash
+uv add py-tjbrhk-toolkit
+```
+
+### 使用 pip
+
+```bash
+pip install py-tjbrhk-toolkit
+```
+
+
+## 依赖包
+
+| 依赖 | 版本要求 | 说明 |
+|------|----------|------|
+| httpx | >=0.27.0 | HTTP 客户端库 |
+| pydantic | >=2.0 | 数据验证库 |
+| jsonpath-ng | >=1.5.3 | JSONPath 查询库 |
+| jsonschema | >=4.21.0 | JSON Schema 校验库 |
+| py-httpx-toolkit | >=1.0.1 | HTTP 工具库 |
+
+## 快速开始
+
+### 同步模式
+
+```python
+from py_tjbrhk_toolkit.speaker import Speaker
+
+# 初始化客户端
+client = Speaker(
+    base_url="https://speaker.17laimai.cn",
+    token="your_token",
+    id="your_id",
+    version="1"
+)
+
+# 发送通知
+response = client.notify(message="Hello World")
+print(response.json())
+```
+
+### 异步模式
+
+```python
+import asyncio
+from py_tjbrhk_toolkit.speaker import Speaker
+
+async def main():
+    # 初始化客户端
+    client = Speaker(
+        base_url="https://speaker.17laimai.cn",
+        token="your_token",
+        id="your_id",
+        version="1"
+    )
+    
+    # 异步发送通知
+    response = await client.async_notify(message="Hello World")
+    print(response.json())
+
+asyncio.run(main())
+```
+
+## API 文档
+
+### Speaker 客户端
+
+#### 初始化参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| base_url | str | https://speaker.17laimai.cn | Speaker 服务器地址 |
+| token | str | "" | API 认证 Token |
+| id | str | "" | API 认证 ID |
+| version | str | "1" | API 版本号 |
+| client_kwargs | dict | None | httpx.Client 额外配置 |
+
+#### notify(message, client=None, client_kwargs=None, **kwargs)
+
+发送同步通知请求
+
+**参数**:
+- `message`: 要发送的内容
+- `client`: 自定义 httpx.Client 实例
+- `client_kwargs`: 客户端配置参数
+- `**kwargs`: 传递给 httpx 请求的额外参数
+
+**返回**: `httpx.Response` - HTTP 响应对象
+
+#### async_notify(message, client=None, client_kwargs=None, **kwargs)
+
+发送异步通知请求
+
+**参数**:
+- `message`: 要发送的内容
+- `client`: 自定义 httpx.AsyncClient 实例
+- `client_kwargs`: 客户端配置参数
+- `**kwargs`: 传递给 httpx 请求的额外参数
+
+**返回**: `httpx.Response` - HTTP 响应对象
+
+### 工具函数
+
+#### json_find_first(expression, data)
+
+使用 JSONPath 表达式从数据中查找第一个匹配项
+
+```python
+from py_tjbrhk_toolkit.speaker.utils import json_find_first
+
+data = {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}
+result = json_find_first("$.users[0].name", data)
+print(result)  # Alice
+```
+
+#### json_is_valid(schema, data)
+
+校验 JSON 数据是否符合指定的 JSON Schema
+
+```python
+from py_tjbrhk_toolkit.speaker.utils import json_is_valid
+
+schema = {"type": "object", "properties": {"name": {"type": "string"}}}
+data = {"name": "test"}
+valid = json_is_valid(schema, data)
+print(valid)  # True
+```
+
+#### build_success_instance(response)
+
+将 HTTP 响应或字典转换为 Success 模型对象
+
+```python
+from py_tjbrhk_toolkit.speaker.utils import build_success_instance
+
+response = {"errcode": 0, "errmsg": "success"}
+result = build_success_instance(response)
+print(result.errcode)  # 0
+```
+
+#### success_is_valid(response, schema=None)
+
+校验 HTTP 响应或字典是否符合成功响应的 JSON Schema
+
+```python
+from py_tjbrhk_toolkit.speaker.utils import success_is_valid
+
+response = {"errcode": 0, "errmsg": "success"}
+valid = success_is_valid(response)
+print(valid)  # True
+```
+
+### 响应模型
+
+#### Base
+
+响应基类，包含错误码和错误信息字段
+
+```python
+from py_tjbrhk_toolkit.speaker.responses import Base
+
+response = Base(errcode=0, errmsg="success")
+```
+
+#### Success
+
+成功响应模型，继承自 Base
+
+```python
+from py_tjbrhk_toolkit.speaker.responses import Success
+
+response = Success(errcode=0, errmsg="success")
+```
+
+## 示例代码
+
+### 完整示例
+
+```python
+from py_tjbrhk_toolkit.speaker import Speaker
+from py_tjbrhk_toolkit.speaker.utils import build_success_instance, success_is_valid
+
+# 初始化客户端
+client = Speaker(
+    token="your_token",
+    id="your_id"
+)
+
+# 发送通知
+response = client.notify(message="测试通知")
+
+# 验证响应
+if success_is_valid(response):
+    result = build_success_instance(response)
+    print(f"发送成功: {result.errmsg}")
+else:
+    print("发送失败")
+```
+
+### 异步完整示例
+
+```python
+import asyncio
+from py_tjbrhk_toolkit.speaker import Speaker
+from py_tjbrhk_toolkit.speaker.utils import build_success_instance, success_is_valid
+
+async def send_notification():
+    client = Speaker(
+        token="your_token",
+        id="your_id"
+    )
+    
+    response = await client.async_notify(message="异步测试通知")
+    
+    if success_is_valid(response):
+        result = build_success_instance(response)
+        print(f"发送成功: {result.errmsg}")
+    else:
+        print("发送失败")
+
+asyncio.run(send_notification())
+```
+
+## 作者
+
+Guolei <174000902@qq.com>
+
+## 项目主页
+
+[https://gitee.com/guolei19850528/py_tjbrhk_toolkit](https://gitee.com/guolei19850528/py_tjbrhk_toolkit)
+
+## 官方文档
+
+[https://www.yuque.com/lingdutuandui/ugcpag/umbzsd](https://www.yuque.com/lingdutuandui/ugcpag/umbzsd)
+
+## 许可证
+
+MIT License

py_tjbrhk_toolkit-1.0.0/src/py_tjbrhk_toolkit.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/py_tjbrhk_toolkit/__init__.py
+src/py_tjbrhk_toolkit.egg-info/PKG-INFO
+src/py_tjbrhk_toolkit.egg-info/SOURCES.txt
+src/py_tjbrhk_toolkit.egg-info/dependency_links.txt
+src/py_tjbrhk_toolkit.egg-info/requires.txt
+src/py_tjbrhk_toolkit.egg-info/top_level.txt
+src/py_tjbrhk_toolkit/speaker/__init__.py
+src/py_tjbrhk_toolkit/speaker/responses.py
+src/py_tjbrhk_toolkit/speaker/utils.py

py_tjbrhk_toolkit-1.0.0/src/py_tjbrhk_toolkit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

py_tjbrhk_toolkit-1.0.0/src/py_tjbrhk_toolkit.egg-info/requires.txt

@@ -0,0 +1,11 @@
+httpx>=0.27.0
+pydantic>=2.0
+jsonpath-ng>=1.5.3
+jsonschema>=4.21.0
+py-httpx-toolkit>=1.0.1
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0
+setuptools>=61.0
+twine>=4.0

py_tjbrhk_toolkit-1.0.0/src/py_tjbrhk_toolkit.egg-info/top_level.txt

@@ -0,0 +1 @@
+py_tjbrhk_toolkit