WebSocket-for-Python (ws4py)

Common errors

• ImportError: No module named 'gevent'

  cause Attempting to use `ws4py.server.geventserver.WebSocketServer` or `geventserver.WSGIWebSocketServer` without `gevent` installed.
  fix Install the `gevent` package: `pip install gevent`.

• TypeError: __init__() missing 1 required positional argument: 'sock'

  cause This error often occurs when you try to instantiate a `WebSocket` subclass directly without passing the socket object, which is usually handled by the server wrapper (e.g., `WebSocketWSGIRequestHandler`).
  fix Ensure your `WebSocket` subclass is instantiated by the `WebSocketWSGIRequestHandler` or similar server component, not directly. If you're building a client, use `WebSocketClient`.

• WebSocket connection to 'ws://localhost:8000/' failed: Error during WebSocket handshake: Unexpected response code: 404

  cause The client attempted to connect to a WebSocket URL that either doesn't exist, is incorrect, or where no WebSocket server is running or properly configured to handle WebSocket requests.
  fix Verify the WebSocket server is running and listening on the correct host and port, and that the URL path (`/` in this example) is correctly mapped to a WebSocket handler on the server side.

Warnings

• breaking Version 0.6.0 dropped official support for Python versions older than 3.6. Code relying on Python 2.x or 3.0-3.5 will break.
  Fix: Upgrade your Python environment to 3.6 or newer. If you must use older Python, pin ws4py to <0.6.0 (e.g., `pip install ws4py==0.5.1`).
• gotcha Using `ws4py.server.geventserver` or `ws4py.server.eventletserver` requires the respective `gevent` or `eventlet` library to be installed separately. An `ImportError` will occur if they are missing.
  Fix: Install the required dependency: `pip install gevent` for `geventserver` or `pip install eventlet` for `eventletserver`.
• gotcha The library's development is slow, with the last release in 2021. It might not include the latest WebSocket protocol extensions or offer modern asyncio-based concurrency patterns.
  Fix: For new projects or high-performance/asyncio requirements, consider more actively maintained alternatives like `websockets` (for asyncio) or `autobahn`.

Install

• pip install ws4py Install ws4py

Imports

• WebSocketClient
  wrong:

  from ws4py import WebSocketClient

  correct:

  from ws4py.client.threadedclient import WebSocketClient

  WebSocketClient is located in a submodule; direct import from 'ws4py' will fail.
• WebSocket
  wrong:

  from ws4py.server import WebSocket

  correct:

  from ws4py.websocket import WebSocket

  The base WebSocket handler class is directly under ws4py.websocket.
• WebSocketServer

  from ws4py.server.wsgirefserver import WebSocketWSGIRequestHandler, WSGIServer

  For a simple WSGI-compatible server using wsgiref. Other servers (gevent, eventlet) have their own specific imports and require additional dependencies.

Quickstart

A basic WebSocket client example using ws4py's threaded client. It connects to a server, sends a few messages, and closes. Note that a server must be running at `ws://localhost:9000/` for this client to successfully connect.

import time
from ws4py.client.threadedclient import WebSocketClient

class DummyClient(WebSocketClient):
    def opened(self):
        print("WebSocket opened. Sending messages...")
        for i in range(0, 5):
            self.send('Hello %d' % i)
            time.sleep(0.5)
        self.send('Bye')

    def closed(self, code, reason=None):
        print("WebSocket closed: %d %s" % (code, reason))

    def received_message(self, m):
        print("Received: %s" % m)
        if m.data == b'Bye':
            self.close()

# Note: This client expects a WebSocket server to be running at ws://localhost:9000/
# For a full runnable example, you'd also need a server like:
# from ws4py.server.wsgirefserver import WSGIServer, WebSocketWSGIRequestHandler
# from ws4py.websocket import WebSocket
# from threading import Thread
# class EchoWebSocket(WebSocket):
#    def received_message(self, message):
#        self.send(message.data, message.is_binary)
# server = WSGIServer(('localhost', 9000), WebSocketWSGIRequestHandler, websocket_class=EchoWebSocket)
# Thread(target=server.serve_forever).start()

if __name__ == '__main__':
    try:
        ws = DummyClient('ws://localhost:9000/', protocols=['http-only', 'chat'])
        ws.connect()
        ws.run_forever()
    except KeyboardInterrupt:
        ws.close()