OctoWebsocket-Client

This is a fork of websocket-client with a few very minor changes made for OctoEverywhere.com and Homeway.io.

The goal is to keep the changes as small as possible, and to stay up to date as much as possible.

Changes made: (in commit order) - Added a flag on send to use a zero-value frame mask without XORing the payload, which gives us a 30% CPU reduction on Pi4 - Kept support for PY 3.7 and 3.8 because we need it for the Sonic Pad - We had to rename the root folder octowebsocket to avoid conflicts. - We had to remove some syntax not supported in 3.7. - Make a small change in send_frame to avoid a slice that's not needed. - Enabled PYlint and disabled a few warnings that aren't important to fix - Added buffer optimizations to allow for passing buffer fragments to be sent and preventing buffer copies. - Added logic to allow zero copy buffer reads - Fixed a bug with handling the close packet

To Update: - Git pull to a release version commit - Rebase our octo branch on top of it. - Search for the current version string and update all instances. - Commit the changes, allow the GitHub Actions to run and turn green. - Run the uplaod.

Source Repo: https://github.com/websocket-client/websocket-client

websocket-client

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.

Documentation

This project's documentation can be found at https://websocket-client.readthedocs.io/

Contributing

Please see the contribution guidelines

Installation

You can use pip install websocket-client to install, or pip install -e . to install from a local copy of the code. This module is tested on Python 3.9+.

There are several optional dependencies that can be installed to enable specific websocket-client features.

• To install python-socks for proxy usage and wsaccel for a minor performance boost, use: pip install websocket-client[optional]
• To install websockets to run unit tests using the local echo server, use: pip install websocket-client[test]
• To install Sphinx and sphinx_rtd_theme to build project documentation, use: pip install websocket-client[docs]

While not a strict dependency, rel is useful when using run_forever with automatic reconnect. Install rel with pip install rel.

Footnote: Some shells, such as zsh, require you to escape the [ and ] characters with a \.

Usage Tips

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.

Performance

The send and validate_utf8 methods can sometimes be bottleneck. You can disable UTF8 validation in this library (and receive a performance enhancement) with the skip_utf8_validation parameter. 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 issue #687 found it didn't help.

Examples

Many more examples are found in the examples documentation.

Long-lived Connection

Most real-world WebSockets situations involve longer-lived connections. The WebSocketApp run_forever loop will automatically try to reconnect to an open WebSocket connection when a network connection is lost if it is provided with:

• a dispatcher argument (async dispatcher like rel or pyevent)
• a non-zero reconnect argument (delay between disconnection and attempted reconnection)

run_forever provides a variety of event-based connection controls using callbacks like on_message and on_error. 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 on_close callback. 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()

Short-lived Connection

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()