WebSocket client for Python with low level API options
websocket-client is a WebSocket client for Python. It provides access to low level APIs for WebSockets. websocket-client implements version hybi-13 of the WebSocket protocol. This client does not currently support the permessage-deflate extension from RFC 7692.
This project's documentation can be found at https://websocket-client.readthedocs.io/
Please see the contribution guidelines
You can use either
python3 setup.py install or
pip3 install websocket-client
to install. This module is tested on Python 3.7+.
There are several optional dependencies that can be installed to enable specific websocket-client features.
- To install
python-socksfor proxy usage and
wsaccelfor a minor performance boost, use:
pip3 install websocket-client[optional]
- To install
websocketsto run unit tests using the local echo server, use:
pip3 install websocket-client[test]
- To install
sphinx_rtd_themeto build project documentation, use:
pip3 install websocket-client[docs]
While not a strict dependency, rel
is useful when using
run_forever with automatic reconnect. Install rel with
pip3 install rel.
Footnote: Some shells, such as zsh, require you to escape the
] characters with a
Check out the documentation's FAQ for additional guidelines: https://websocket-client.readthedocs.io/en/latest/faq.html
Known issues with this library include lack of WebSocket Compression support (RFC 7692) and minimal threading documentation/support.
validate_utf8 methods can sometimes be bottleneck.
You can disable UTF8 validation in this library (and receive a
performance enhancement) with the
If you want to get better performance, install wsaccel. While
websocket-client does not depend on wsaccel, it will be used if
available. wsaccel doubles the speed of UTF8 validation and
offers a very minor 10% performance boost when masking the
payload data as part of the
send process. Numpy used to
be a suggested performance enhancement alternative, but
found it didn't help.
Many more examples are found in the examples documentation.
Most real-world WebSockets situations involve longer-lived connections.
run_forever loop will automatically try to reconnect
to an open WebSocket connection when a network
connection is lost if it is provided with:
dispatcherargument (async dispatcher like rel or pyevent)
- a non-zero
reconnectargument (delay between disconnection and attempted reconnection)
run_forever provides a variety of event-based connection controls
using callbacks like
run_forever does not automatically reconnect if the server
closes the WebSocket gracefully (returning
a standard websocket close code).
This is the logic behind the decision.
Customizing behavior when the server closes
the WebSocket should be handled in the
This example uses rel
for the dispatcher to provide automatic reconnection.
import websocket import _thread import time import rel def on_message(ws, message): print(message) def on_error(ws, error): print(error) def on_close(ws, close_status_code, close_msg): print("### closed ###") def on_open(ws): print("Opened connection") if __name__ == "__main__": websocket.enableTrace(True) ws = websocket.WebSocketApp("wss://api.gemini.com/v1/marketdata/BTCUSD", on_open=on_open, on_message=on_message, on_error=on_error, on_close=on_close) ws.run_forever(dispatcher=rel, reconnect=5) # Set dispatcher to automatic reconnection, 5 second reconnect delay if connection closed unexpectedly rel.signal(2, rel.abort) # Keyboard Interrupt rel.dispatch()
This is if you want to communicate a short message and disconnect immediately when done. For example, if you want to confirm that a WebSocket server is running and responds properly to a specific request.
from websocket import create_connection ws = create_connection("ws://echo.websocket.events/") print(ws.recv()) print("Sending 'Hello, World'...") ws.send("Hello, World") print("Sent") print("Receiving...") result = ws.recv() print("Received '%s'" % result) ws.close()
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Hashes for websocket_client-1.5.2-py3-none-any.whl