centrifuge-python：给 Python 用的 WebSocket 实时 SDK

centrifuge-python：给 Python 用的 WebSocket 实时 SDK

centrifuge-python 在 GitHub 上拿到了 58 个 Star。

这是 Centrifugal 组织官方维护的 Python 客户端 SDK，基于 asyncio 实现，用来连接 Centrifugo 实时消息服务器。如果你需要在 Python 项目里接入 WebSocket 推送、订阅频道、处理实时数据，这是目前最对口的官方选择。

1、这玩意儿是干嘛的

核心功能就一个：让 Python 程序通过 WebSocket 与 Centrifugo 服务器保持长连接，实现实时消息收发。

它封装了连接管理、频道订阅、消息发布、在线状态、历史消息回溯等完整协议能力。开发者不需要自己处理 WebSocket 重连、心跳、序列化这些底层细节，直接调用高层 API 就行。

SDK 兼容 Centrifugo 服务器的完整客户端协议，功能覆盖度可以参考官方文档里的 SDK 特性矩阵。

2、两种协议怎么选

默认走 JSON 协议，所有 payload 会在内部自动做 json.dumps 和 json.loads，你传进去 Python 字典，收到的也是 Python 字典。

如果需要 Protobuf，在初始化 Client 时传 use_protobuf=True。此时所有 payload 必须是 bytes 类型，收到的也是 bytes。你仍然可以在 Protobuf 模式下传 JSON 数据，只要提前 encode 成 bytes 就行。

两种协议在功能上没有差异，选哪种取决于你的后端配置和数据格式偏好。

3、安装与基础用法

安装：

pip install centrifuge-python

基础导入：

from centrifuge import Client

代码里的 example.py 展示了完整用法，包括连接、订阅、回调处理。官方也提供了 Docker Compose 配置，可以直接拉起测试用的 Centrifugo 服务器跑通示例。

4、一个容易踩的坑

事件回调是在 WebSocket 读取循环里用 await 调用的。如果你的回调里做了耗时操作，整个连接读取就会卡住。

更麻烦的是，你不能在回调里直接调用 SDK 的其他 awaitable API，因为读取循环被阻塞，根本没有机会收服务端响应，最后会抛 OperationTimeoutError。

解决办法：把耗时工作丢给独立的 coroutine 或 task，回调里尽快 return。

5、适合哪些人用

• 在用 Centrifugo 做实时推送、需要 Python 接入后端的开发者
• 在搭聊天系统、实时通知、数据看板，需要 WebSocket 客户端的项目
• 已经用惯了 asyncio 生态、不想自己维护 WebSocket 连接池的 Python 工程师