73 lines
2.4 KiB
Markdown
73 lines
2.4 KiB
Markdown
# NixMsg Python SDK
|
||
|
||
包名 `nixmsg`，最低 Python 3.10。同步接口为主，同包提供 `AsyncClient` asyncio 包装。
|
||
|
||
## 安装
|
||
|
||
发布后（阶段 3）：
|
||
|
||
```bash
|
||
pip install nixmsg --index-url https://git.asio.asia/api/packages/nixevol/pypi/simple/
|
||
```
|
||
|
||
本地开发：
|
||
|
||
```bash
|
||
cd sdk/python
|
||
python -m venv .venv
|
||
# Windows: .venv\Scripts\activate
|
||
pip install -e ".[dev]"
|
||
```
|
||
|
||
## 最小示例
|
||
|
||
```python
|
||
from nixmsg import Body, Client, SendOptions, Target
|
||
|
||
c = Client()
|
||
c.on_session(lambda token: print("session", token))
|
||
c.on_message(lambda msg: print("msg", msg.id, msg.body.data))
|
||
c.connect("ws://127.0.0.1:7443/mqtt", "device-1", password="secret")
|
||
c.send(
|
||
Target(kind="endpoint", id="device-2"),
|
||
Body(data="hello"),
|
||
SendOptions(delay_ms=0),
|
||
)
|
||
c.close()
|
||
```
|
||
|
||
更完整的命令行示例见 `examples/minimal.py`。
|
||
|
||
## 行为约定
|
||
|
||
四种 SDK 同一套对外语义，详见仓库 `docs/DEVELOPMENT.md` 第 9 节附录「SDK 行为约定」。要点：
|
||
|
||
- 首次连接默认 30 秒内未握手则停止重连，抛出 `not_connected`；Client 可再次 `connect`。
|
||
- 顶号原因一律 `taken_over`；DISCONNECT `0x8B` 可重试；CONNECT 不带 Receive Maximum；心跳默认 30 秒。
|
||
- 重连退避只维护一个计数 n：第 n 次等待 `min(1s×2^(n-1), 30s)×随机(0.7,1.3)`。仅 `connect` 后第一次可不等待；断线后首次重连也约 1 秒；在线不足 60 秒断开则 n+1，稳定 60 秒后断开 n=1。
|
||
- `rate_limited` 与断线重交：每次重新生成 `rid` 并重新序列化；消息 `id`、正文、`send_at_ms` 不变。
|
||
- `logout` 请求失败抛给应用；本地仍停止重连、清空令牌、结束队列并发 `offline`。
|
||
- 时长与时间戳用 64 位整数。`send_at` 是本机时间（会加时钟偏差写成 `send_at_ms`）；`send_at_ms` 是服务器时间。两者与 `delay_ms` 同时给时本地 `bad_request`。停止重连后再 `send` 立即失败。
|
||
- 取消尚未发出的条目即出队；已发出的返回 `result_unknown`，应用应以同一消息号重试。
|
||
|
||
## 打包（不发布）
|
||
|
||
```bash
|
||
pip install build
|
||
python -m build
|
||
# 产物在 dist/，勿上传 PyPI；正式发布由总控在阶段 3 执行
|
||
```
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
# 单元测试（假传输）+ 接入清单（会编译并启动真实 nixmsg）
|
||
pytest
|
||
```
|
||
|
||
接入清单覆盖 DEVELOPMENT 第 9 节（跳过仅 JS 的跨域项）。可用环境变量 `NIXMSG_BIN` 指定已编译二进制。
|
||
|
||
## 许可证
|
||
|
||
见 `LICENSE`（专有 / Proprietary）。
|