NixMsg/sdk/python/README.md

NixMsg Python SDK

包名 nixmsg，最低 Python 3.10。同步接口为主，同包提供 AsyncClient asyncio 包装。

安装

发布后（阶段 3）：

pip install nixmsg --index-url https://git.asio.asia/api/packages/nixevol/pypi/simple/

本地开发：

cd sdk/python
python -m venv .venv
# Windows: .venv\Scripts\activate
pip install -e ".[dev]"

最小示例

from nixmsg import Body, Client, SendOptions, Target

c = Client()
c.on_session(lambda token: print("session", token[:8]))
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，应用应以同一消息号重试。

打包（不发布）

pip install build
python -m build
# 产物在 dist/，勿上传 PyPI；正式发布由总控在阶段 3 执行

测试

# 单元测试（假传输）+ 接入清单（会编译并启动真实 nixmsg）
pytest

接入清单覆盖 DEVELOPMENT 第 9 节（跳过仅 JS 的跨域项）。可用环境变量 NIXMSG_BIN 指定已编译二进制。

许可证

见 LICENSE（专有 / Proprietary）。