wsproto

wsproto is a pure-Python, pure-state-machine implementation of the WebSocket protocol. It implements RFC6455 (WebSocket) and RFC7692 (per-message compression) as an in-memory library that deals only in bytes-in and events-out, with no networking or concurrency assumptions of its own.

Because it is “sans-IO,” you drive it by feeding received bytes and reading back protocol events, then send the bytes it produces over whatever transport you like — sync, async, or otherwise. This makes it a reusable protocol core that async frameworks and servers can build on.

What You Get

• A complete RFC6455 WebSocket protocol state machine
• Per-message compression support via RFC7692
• An event-based API (Request, AcceptConnection, TextMessage, BytesMessage, Ping, CloseConnection)
• Client and server connection handling including the HTTP upgrade handshake
• A sans-IO design usable with any sync or async transport

Common Use Cases

• Implementing WebSocket support inside an async web framework or server
• Building a custom WebSocket client or server over a chosen transport
• Adding spec-compliant framing and compression to a networking stack
• Testing WebSocket logic without real sockets by driving the state machine directly

Under The Hood

Architecture - The core is split into a low-level frame_protocol.py (framing, masking, RFC7692 compression) and higher-level connection.py/handshake.py that manage the HTTP upgrade and connection lifecycle, exposing byte input and typed events.py output. extensions.py handles negotiated extensions. Nothing performs I/O; the WSConnection object is a pure state machine you feed and drain.

Tech Stack - Pure Python (3.6.1+), packaged via pyproject.toml, with an h11-style sans-IO design and no runtime networking dependencies. It ships a py.typed marker and inline type hints.

Code Quality - The library is fully typed (typing.py, py.typed), has a dedicated tests/ suite (with autobahn-style conformance testing), docs on Read the Docs, benchmarks under bench/, and a maintained CHANGELOG, reflecting a mature, well-tested protocol implementation.

API Design - The API is small and explicit: instantiate WSConnection, send() events to get bytes, receive_data() to feed bytes, and iterate events(). The event objects are clearly named and typed, and the sans-IO contract keeps the surface stable across very different I/O environments.