Abstract websocket functionality.

class lomond.websocket.WebSocket(url, proxies=None, protocols=None, agent=None, compress=False)

IO independent websocket functionality.

  • url (str) – A websocket URL, must have a ws:// or wss:// protocol.
  • proxies (dict) – A dict containing 'http' or 'https' urls to a proxy server, or None to attempt to auto-detect proxies from environment. Pass an empty dict to disable proxy.
  • protocols (list) – A list of supported protocols (defaults to no protocols).
  • agent (str) – A user agent string to be sent in the header. The default uses the value USER_AGENT defined in lomond.constants.
add_header(header, value)

Add a custom header to the websocket request.

  • header (bytes) – Name of the header.
  • value (bytes) – Value of the header.

Get the websocket request (in bytes).

This method is called from the session, and should not be invoked explicitly.

close(code=1000, reason='goodbye')

Close the websocket.



Closing the websocket won’t exit the main loop immediately; it will put the websocket in to a closing state while it waits for the server to echo back a close packet. No data may be sent by the application when the websocket is closing.

connect(session_class=<class 'lomond.session.WebsocketSession'>, poll=5.0, ping_rate=30.0, ping_timeout=None, auto_pong=True, close_timeout=30.0)

Connect the websocket to a session.

  • session_class – An object to manage the session. This object is an extension mechanism that will allow the WebSocket to be driven by different back-ends. For now, treat it as an implementation detail and leave it as the default.
  • poll (float) – Rate (in seconds) that poll events should be generated.
  • ping_rate (float) – Rate that ping packets should be sent. Set to 0 to disable auto pings.
  • ping_timeout (float) – Maximum time in seconds to wait for a pong response before disconnecting. Set to None (default) to disable. If set, double ping_rate would be a good starting point.
  • auto_pong (bool) – Enable (default) automatic response to ping events.
  • close_timeout (float) – Seconds to wait for server to respond to a close packet, before closing the socket. Set to None or 0 to disable the timeout.

An iterable of Event instances.


Feed with data from the socket, and yield any events.

This method is called by the Session object, and is not needed for normal use.

Parameters:data (bytes) – data received over a socket.

Force the socket to disconnect.


Boolean that indicates the socket is ‘active’ i.e. not in a closing state.


Flag that indicates if the websocket is closed.


Boolean that indicates if the websocket is in a closing state. No further messages may be sent when a websocket is closing.


Boolean that indicates if the websocket is over ssl (i.e. the wss protocol).


Called on disconnect.


Called when the HTTP response has been received.


Process extension headers.


Reset the state.

send_binary(data, compress=True)

Send a binary message.

  • data (bytes) – Binary data to send.
  • compress (bool) – Send data in compressed form, if compression is enabled on the server.

TypeError – If data is not bytes.

send_json(_obj=Ellipsis, **kwargs)

Encode an object as JSON and send a text message.

The object to encode may be specified as a single positional argument OR if as keyword arguments which will be encoded as a JSON object. The following two lines will send the same JSON:

websocket.send_json({'foo': 'bar'})
Parameters:obj – An object to be encoded as JSON.
Raises:TypeError – If obj could not be encoded as JSON.

Send a ping packet.


data (bytes) – Data to send in the ping message (must be <= 125 bytes).

  • TypeError – If data is not bytes.
  • ValueError – If data is > 125 bytes.

Send a pong packet.

Parameters:data (bytes) – Data to send in the ping message (must be <= 125 bytes).

A pong may be sent in response to a ping, or unsolicited to keep the connection alive.

  • TypeError – If data is not bytes.
  • ValueError – If data is > 125 bytes.
send_text(text, compress=True)

Send a text message.

  • text (str) – Text to send.
  • compress (bool) – Send the text in compressed form, if compression is enabled on the server.

TypeError – If data is not str (or unicode on Py2).


The time (seconds since session start) when a close packet was sent (or None if no close packet has been sent).


Boolean that indicates if the server has compression enabled.