python-socketio

python-socketio is a Python implementation of the Socket.IO realtime communication protocol, providing both server and client APIs that support synchronous and asyncio-based usage. It integrates with WSGI and ASGI web servers (Flask, aiohttp, Sanic, Tornado, FastAPI via ASGI) and can scale across multiple processes using Redis, Kafka, or RabbitMQ-backed pub/sub managers, making it suitable for anything from a single-process prototype to a horizontally scaled realtime backend.

The library closely tracks the official JavaScript Socket.IO implementation’s protocol revisions, with an explicit compatibility chart mapping package versions to Socket.IO and Engine.IO protocol versions so Python servers and clients can interoperate with JavaScript ones. Namespaces, rooms, event acknowledgements, and binary payloads are all supported, giving Python applications the same feature set developers expect from the JavaScript ecosystem.

What You Get

• Synchronous and asyncio Server/Client classes for building realtime applications in either style
• WSGI and ASGI middleware for integrating with Flask, aiohttp, Sanic, Tornado, and other Python web frameworks
• Pub/sub manager backends (Redis, Kafka, RabbitMQ/Kombu, ZeroMQ) for scaling a Socket.IO server across multiple worker processes
• Namespaces, rooms, event acknowledgements, and binary payload support matching the JavaScript Socket.IO feature set
• A documented protocol compatibility chart mapping this package’s versions to Socket.IO/Engine.IO protocol revisions

Common Use Cases

• Adding realtime bidirectional events (chat, live dashboards, notifications) to a Flask or FastAPI/ASGI application
• Building a Python backend that must interoperate with an existing JavaScript Socket.IO client in the browser
• Scaling a Socket.IO server horizontally across multiple worker processes using a Redis- or Kafka-backed manager
• Prototyping realtime multiplayer or collaborative features with rooms and namespaces

Under The Hood

Architecture - The package splits cleanly into synchronous (server.py, client.py, manager.py, namespace.py) and asyncio-native (async_server.py, async_client.py, async_manager.py, async_namespace.py) implementations that share common base classes (base_server.py, base_client.py, base_manager.py, base_namespace.py). Scaling across processes is handled by pluggable manager backends (redis_manager.py, kafka_manager.py, kombu_manager.py, zmq_manager.py, pubsub_manager.py) that broadcast events between server instances, and asgi.py/middleware.py adapt the core server to WSGI and ASGI runtimes.

Tech Stack - Pure Python (99.97% of the codebase), depending on bidict for bidirectional session-id mappings and python-engineio (the same author’s lower-level transport package) for the underlying long-polling/WebSocket transport. Optional extras add requests/websocket-client for the sync client, aiohttp for the asyncio client, and framework-specific manager backends are opt-in via extras.

Code Quality - 31 test files under tests/ cover both sync and async server/client/manager code paths, run via tox across supported Python versions per tox.ini. The codebase is long-lived (created 2015, 786 total commits) and maintained solely by Miguel Grinberg with a consistent module-per-concern layout that keeps sync and async implementations parallel and easy to cross-reference.

API Design - The Server/Client classes mirror the JavaScript Socket.IO API closely (@sio.event, sio.emit(), namespaces, rooms), which makes the library approachable for anyone coming from the JS ecosystem, while the separate AsyncServer/AsyncClient classes keep the sync/async split explicit rather than overloading one API with both behaviors.