websocket-client

websocket-client is a pure-Python WebSocket client library implementing the RFC 6455 (hybi-13) protocol with zero required dependencies. It exposes both a low-level WebSocket class for direct socket-level control and a higher-level WebSocketApp that mirrors the JavaScript WebSocket API with callback-based event handling (on_open, on_message, on_error, on_close).

Widely used as a standard choice for WebSocket connectivity in Python — from IoT device clients to market-data feeds to internal service tooling — the library has been maintained continuously since 2010, with the current maintainer team shipping regular releases, SSL/TLS and proxy support, automatic reconnection, and optional performance and testing extras via pip extras.

What You Get

• A low-level WebSocket class exposing connect, send, recv, and close for direct protocol control
• A WebSocketApp class mirroring the browser WebSocket API with on_open/on_message/on_error/on_close callbacks
• Built-in SSL/TLS support plus HTTP/SOCKS proxy connection handling via _http.py
• Automatic reconnection support via run_forever(dispatcher=..., reconnect=N) when paired with a dispatcher like rel
• Optional wsaccel and python-socks extras for UTF-8 validation speedups and proxy support

Common Use Cases

• Real-time market data feeds - trading and fintech developers use WebSocketApp.run_forever with automatic reconnect to maintain always-on connections to exchange data streams
• IoT and device telemetry - device integrators embed the low-level WebSocket class to send/receive framed messages over constrained network links without pulling in async framework dependencies
• Internal service-to-service push channels - backend engineers use the library for lightweight, synchronous WebSocket clients in scripts and services that don’t require an async event loop
• Debugging and manual protocol testing - the bundled wsdump CLI utility (_wsdump.py) lets developers connect to and inspect a WebSocket endpoint interactively from the terminal

Under The Hood

Architecture The library separates protocol framing (_abnf.py, implementing RFC 6455 frame parsing), low-level socket handling (_core.py, the WebSocket class managing connect/send/recv over raw sockets), HTTP handshake and proxy tunneling (_http.py, _handshake.py), and a higher-level event-driven wrapper (_app.py, the WebSocketApp class) that composes the core WebSocket internally and drives it through a run_forever loop with pluggable dispatchers (_dispatcher.py) for reconnect and async-runtime integration. This is a modular, layered design — protocol layer, transport layer, handshake layer, then a high-level app layer — with __init__.py re-exporting the public surface via wildcard imports. Because both WebSocket and WebSocketApp ultimately depend on the same frame_buffer/continuous_frame primitives in _abnf.py, changes to core framing logic ripple through both API levels.

Tech Stack Pure Python 3.10+, with zero required runtime dependencies — install_requires is empty, relying entirely on the standard library’s socket, ssl, threading, and struct modules. Optional extras cover python-socks and wsaccel for proxy support and a C-accelerated UTF-8 validation/masking speedup, websockets for running the test suite’s local echo server, and Sphinx/sphinx_rtd_theme/myst-parser for documentation builds. Packaging uses setuptools>=77 via a pyproject.toml build-backend paired with a setup.py carrying the actual package metadata. Static typing is enforced separately through mypy.ini, targeting the websocket/ package while excluding tests and the _wsdump.py CLI tool. CI runs dedicated GitHub Actions workflows for linting, building, doctests, and code coverage via Codecov.

Code Quality An extensive test suite lives under websocket/tests/, spanning ABNF framing, app-level behavior, cookiejar handling, dispatcher logic, handshake edge cases, HTTP, large payloads, logging helpers, reconnect-on-bad-fd scenarios, socket bugs, SSL compatibility and edge cases, URL parsing, and general utilities — run with pytest. Core modules carry typed function signatures throughout (Optional/Union/Callable annotations in _core.py and _app.py) and are checked with mypy in CI. A custom exception hierarchy in _exceptions.py (WebSocketException, WebSocketProtocolException, WebSocketConnectionClosedException, WebSocketTimeoutException) gives callers granular error handling instead of bare exceptions, and code formatting follows the black style declared in the README.

API Design The library’s central developer-experience choice is offering two coexisting API levels under one import: a low-level WebSocket class for raw send/recv/close control, and a WebSocketApp deliberately modeled on the browser’s JavaScript WebSocket object so web developers can transfer intuition directly. A zero-required-dependency footprint keeps integration friction minimal, and optional extras are cleanly namespaced (pip install websocket-client[optional], [test], [docs]). It doesn’t extend the protocol itself — WebSocket Compression (RFC 7692) is explicitly unsupported — but the dual-API ergonomics and dependency-free design are its clearest differentiator against async-first alternatives like websockets or aiohttp.