aaugustin/websockets
Websockets
websockets is a Python library for building WebSocket servers and clients using coroutines and the asyncio framework. It provides a complete toolkit for creating production-ready WebSocket applications, including a coroutine-based framework for handling connections, messages, and lifecycle events, as well as a client library for opening persistent bidirectional connections to remote endpoints.
The library manages the full lifecycle of WebSocket connections, including handshake, message exchange, and graceful closure, with support for path-based routing to organize server logic across multiple endpoints. It implements the WebSocket RFC 6455 protocol as a deterministic state machine, with automatic ping/pong keepalive to maintain connection health and a connection-level send queue with backpressure handling. The framework also includes a pluggable transport abstraction that separates TCP and TLS socket handling from the protocol logic.
For production deployment, websockets offers configuration for reverse proxies, Kubernetes, and cloud platforms, along with auto-reloading during development. It integrates with Django through an ASGI bridge, enabling real-time endpoints alongside traditional HTTP views. The library also supports broadcast messaging, multi-client state coordination, and includes a command-line interactive client for testing.
Features
- Coroutine-Based WebSocket Frameworks - A coroutine-based framework for handling WebSocket connections, messages, and lifecycle events in Python.
- WebSocket Clients and Servers - Open a persistent bidirectional connection to a remote server and exchange messages over it.
- WebSocket Servers - Start a server that listens for WebSocket connections and handles messages asynchronously using coroutines.
- Coroutine-Based Connection Handlers - Manages each WebSocket connection lifecycle within an async coroutine, enabling cooperative multitasking for message send/receive.
- Connection Lifecycle Management - Manage the lifecycle of WebSocket connections, including handshake, message exchange, and graceful closure.
- Protocol State Machines - Implements the WebSocket RFC 6455 handshake, framing, masking, and closure as a deterministic state machine.
- WebSocket Message Exchanges - Send and receive text or binary messages through an open WebSocket connection using a simple send and receive interface.
- WebSocket Clients - Provides a coroutine-based client library for establishing persistent bidirectional WebSocket connections.
- Coroutine-Based Asynchronous I/O - Drives concurrent connections by awaiting coroutines on Python's asyncio event loop for non-blocking send and receive.
- Asynchronous Event Loops - Drives concurrent WebSocket connections using Python's asyncio event loop for non-blocking I/O and coroutine-based handlers.
- WebSocket Backends - Provides a complete coroutine-based WebSocket server and client library for real-time web applications.
- Django ASGI Bridges - Bridges WebSocket connections into Django's ASGI interface, enabling real-time endpoints alongside HTTP views.
- Application State Management - Provides a coroutine-based framework for managing and synchronizing application state across WebSocket connections.
- WebSocket State Coordinators - Provides multi-client state coordination and broadcast messaging over WebSocket connections.
- Connection-Level Send Queues - Buffers outgoing messages per connection with backpressure handling to prevent overwhelming slow consumers.
- WebSocket Reverse Proxy Deployments - Provides configuration for reverse proxies and cloud platforms to deploy WebSocket servers reliably.
- Server Configurations - Provides production-ready server configuration settings for reliable WebSocket deployment.
- Broadcast Messaging - Ships a broadcast messaging capability to send messages to all connected clients simultaneously.
- WebSocket Ping/Pong Keepalives - Maintains connection health by sending periodic WebSocket ping frames and awaiting pong responses with configurable timeouts.
- WebSocket Path Routings - Direct incoming WebSocket connections to different handlers based on the request path, organizing server logic.
- ASGI Bridges - Bridges WebSocket connections into Django's ASGI interface, allowing real-time endpoints alongside traditional HTTP views.
- Path-Based Routers - Maps incoming WebSocket upgrade requests to handler coroutines based on the request URI path, enabling multi-endpoint servers.
- WebSocket Routers - Maps incoming WebSocket upgrade requests to handler coroutines based on the request URI path.
- Web Frameworks - Library for building WebSocket servers and clients with focus on correctness.
- WebSocket Tools - Library for building WebSocket servers and clients.
