API Reference

The Server class

class simple_websocket.Server(environ, subprotocols=None, receive_bytes=4096, ping_interval=None, max_message_size=None, thread_class=None, event_class=None, selector_class=None)

This class implements a WebSocket server.

Instead of creating an instance of this class directly, use the accept() class method to create individual instances of the server, each bound to a client request.

classmethod accept(environ, subprotocols=None, receive_bytes=4096, ping_interval=None, max_message_size=None, thread_class=None, event_class=None, selector_class=None)

Accept a WebSocket connection from a client.

Parameters:

  • environ – A WSGI environ dictionary with the request details. Among other things, this class expects to find the low-level network socket for the connection somewhere in this dictionary. Since the WSGI specification does not cover where or how to store this socket, each web server does this in its own different way. Werkzeug, Gunicorn, Eventlet and Gevent are the only web servers that are currently supported.

  • subprotocols – A list of supported subprotocols, or None (the default) to disable subprotocol negotiation.

  • receive_bytes – The size of the receive buffer, in bytes. The default is 4096.

  • ping_interval – Send ping packets to clients at the requested interval in seconds. Set to None (the default) to disable ping/pong logic. Enable to prevent disconnections when the line is idle for a certain amount of time, or to detect unresponsive clients and disconnect them. A recommended interval is 25 seconds.

  • max_message_size – The maximum size allowed for a message, in bytes, or None for no limit. The default is None.

  • thread_class – The Thread class to use when creating background threads. The default is the threading.Thread class from the Python standard library.

  • event_class – The Event class to use when creating event objects. The default is the threading.Event` class from the Python standard library.

  • selector_class – The Selector class to use when creating selectors. The default is the selectors.DefaultSelector class from the Python standard library.

choose_subprotocol(request)

Choose a subprotocol to use for the WebSocket connection.

The default implementation selects the first protocol requested by the client that is accepted by the server. Subclasses can override this method to implement a different subprotocol negotiation algorithm.

Parameters:

request – A Request object.

The method should return the subprotocol to use, or None if no subprotocol is chosen.

close(reason=None, message=None)

Close the WebSocket connection.

Parameters:

  • reason – A numeric status code indicating the reason of the closure, as defined by the WebSocket specification. The default is 1000 (normal closure).

  • message – A text message to be sent to the other side.

receive(timeout=None)

Receive data over the WebSocket connection.

Parameters:

timeout – Amount of time to wait for the data, in seconds. Set to None (the default) to wait indefinitely. Set to 0 to read without blocking.

The data received is returned, as bytes or str, depending on the type of the incoming message.

send(data)

Send data over the WebSocket connection.

Parameters:

data – The data to send. If data is of type bytes, then a binary message is sent. Else, the message is sent in text format.

subprotocol

The name of the subprotocol chosen for the WebSocket connection.

The AioServer class

class simple_websocket.AioServer(request, subprotocols=None, receive_bytes=4096, ping_interval=None, max_message_size=None)

This class implements a WebSocket server.

Instead of creating an instance of this class directly, use the accept() class method to create individual instances of the server, each bound to a client request.

async classmethod accept(aiohttp=None, asgi=None, sock=None, headers=None, subprotocols=None, receive_bytes=4096, ping_interval=None, max_message_size=None)

Accept a WebSocket connection from a client.

Parameters:

  • aiohttp – The request object from aiohttp. If this argument is provided, asgi, sock and headers must not be set.

  • asgi – A (scope, receive, send) tuple from an ASGI request. If this argument is provided, aiohttp, sock and headers must not be set.

  • sock – A connected socket to use. If this argument is provided, aiohttp and asgi must not be set. The headers argument must be set with the incoming request headers.

  • headers – A dictionary with the incoming request headers, when sock is used.

  • subprotocols – A list of supported subprotocols, or None (the default) to disable subprotocol negotiation.

  • receive_bytes – The size of the receive buffer, in bytes. The default is 4096.

  • ping_interval – Send ping packets to clients at the requested interval in seconds. Set to None (the default) to disable ping/pong logic. Enable to prevent disconnections when the line is idle for a certain amount of time, or to detect unresponsive clients and disconnect them. A recommended interval is 25 seconds.

  • max_message_size – The maximum size allowed for a message, in bytes, or None for no limit. The default is None.

choose_subprotocol(request)

Choose a subprotocol to use for the WebSocket connection.

The default implementation selects the first protocol requested by the client that is accepted by the server. Subclasses can override this method to implement a different subprotocol negotiation algorithm.

Parameters:

request – A Request object.

The method should return the subprotocol to use, or None if no subprotocol is chosen.

async close(reason=None, message=None)

Close the WebSocket connection.

Parameters:

  • reason – A numeric status code indicating the reason of the closure, as defined by the WebSocket specification. The default is 1000 (normal closure).

  • message – A text message to be sent to the other side.

async receive(timeout=None)

Receive data over the WebSocket connection.

Parameters:

timeout – Amount of time to wait for the data, in seconds. Set to None (the default) to wait indefinitely. Set to 0 to read without blocking.

The data received is returned, as bytes or str, depending on the type of the incoming message.

async send(data)

Send data over the WebSocket connection.

Parameters:

data – The data to send. If data is of type bytes, then a binary message is sent. Else, the message is sent in text format.

subprotocol

The name of the subprotocol chosen for the WebSocket connection.

The Client class

class simple_websocket.Client(url, subprotocols=None, headers=None, receive_bytes=4096, ping_interval=None, max_message_size=None, ssl_context=None, thread_class=None, event_class=None)

This class implements a WebSocket client.

Instead of creating an instance of this class directly, use the connect() class method to create an instance that is connected to a server.

receive(timeout=None)

Receive data over the WebSocket connection.

Parameters:

timeout – Amount of time to wait for the data, in seconds. Set to None (the default) to wait indefinitely. Set to 0 to read without blocking.

The data received is returned, as bytes or str, depending on the type of the incoming message.

send(data)

Send data over the WebSocket connection.

Parameters:

data – The data to send. If data is of type bytes, then a binary message is sent. Else, the message is sent in text format.

subprotocol

The name of the subprotocol chosen for the WebSocket connection.

classmethod connect(url, subprotocols=None, headers=None, receive_bytes=4096, ping_interval=None, max_message_size=None, ssl_context=None, thread_class=None, event_class=None)

Returns a WebSocket client connection.

Parameters:

  • url – The connection URL. Both ws:// and wss:// URLs are accepted.

  • subprotocols – The name of the subprotocol to use, or a list of subprotocol names in order of preference. Set to None (the default) to not use a subprotocol.

  • headers – A dictionary or list of tuples with additional HTTP headers to send with the connection request. Note that custom headers are not supported by the WebSocket protocol, so the use of this parameter is not recommended.

  • receive_bytes – The size of the receive buffer, in bytes. The default is 4096.

  • ping_interval – Send ping packets to the server at the requested interval in seconds. Set to None (the default) to disable ping/pong logic. Enable to prevent disconnections when the line is idle for a certain amount of time, or to detect an unresponsive server and disconnect. A recommended interval is 25 seconds. In general it is preferred to enable ping/pong on the server, and let the client respond with pong (which it does regardless of this setting).

  • max_message_size – The maximum size allowed for a message, in bytes, or None for no limit. The default is None.

  • ssl_context – An SSLContext instance, if a default SSL context isn’t sufficient.

  • thread_class – The Thread class to use when creating background threads. The default is the threading.Thread class from the Python standard library.

  • event_class – The Event class to use when creating event objects. The default is the threading.Event` class from the Python standard library.

close(reason=None, message=None)

Close the WebSocket connection.

Parameters:

  • reason – A numeric status code indicating the reason of the closure, as defined by the WebSocket specification. The default is 1000 (normal closure).

  • message – A text message to be sent to the other side.

The AioClient class

class simple_websocket.AioClient(url, subprotocols=None, headers=None, receive_bytes=4096, ping_interval=None, max_message_size=None, ssl_context=None)

This class implements a WebSocket client.

Instead of creating an instance of this class directly, use the connect() class method to create an instance that is connected to a server.

async classmethod connect(url, subprotocols=None, headers=None, receive_bytes=4096, ping_interval=None, max_message_size=None, ssl_context=None, thread_class=None, event_class=None)

Returns a WebSocket client connection.

Parameters:

  • url – The connection URL. Both ws:// and wss:// URLs are accepted.

  • subprotocols – The name of the subprotocol to use, or a list of subprotocol names in order of preference. Set to None (the default) to not use a subprotocol.

  • headers – A dictionary or list of tuples with additional HTTP headers to send with the connection request. Note that custom headers are not supported by the WebSocket protocol, so the use of this parameter is not recommended.

  • receive_bytes – The size of the receive buffer, in bytes. The default is 4096.

  • ping_interval – Send ping packets to the server at the requested interval in seconds. Set to None (the default) to disable ping/pong logic. Enable to prevent disconnections when the line is idle for a certain amount of time, or to detect an unresponsive server and disconnect. A recommended interval is 25 seconds. In general it is preferred to enable ping/pong on the server, and let the client respond with pong (which it does regardless of this setting).

  • max_message_size – The maximum size allowed for a message, in bytes, or None for no limit. The default is None.

  • ssl_context – An SSLContext instance, if a default SSL context isn’t sufficient.

async receive(timeout=None)

Receive data over the WebSocket connection.

Parameters:

timeout – Amount of time to wait for the data, in seconds. Set to None (the default) to wait indefinitely. Set to 0 to read without blocking.

The data received is returned, as bytes or str, depending on the type of the incoming message.

async send(data)

Send data over the WebSocket connection.

Parameters:

data – The data to send. If data is of type bytes, then a binary message is sent. Else, the message is sent in text format.

subprotocol

The name of the subprotocol chosen for the WebSocket connection.

async close(reason=None, message=None)

Close the WebSocket connection.

Parameters:

  • reason – A numeric status code indicating the reason of the closure, as defined by the WebSocket specification. The default is 1000 (normal closure).

  • message – A text message to be sent to the other side.

Exceptions

class simple_websocket.ConnectionError(status_code=None)

Connection error exception class.

class simple_websocket.ConnectionClosed(reason=CloseReason.NO_STATUS_RCVD, message=None)

Connection closed exception class.