WebSocket¶
Abstract websocket functionality.
-
class
lomond.websocket.
WebSocket
(url, proxies=None, protocols=None, agent=None, compress=False)¶ IO independent websocket functionality.
Parameters: - url (str) – A websocket URL, must have a
ws://
orwss://
protocol. - proxies (dict) – A dict containing
'http'
or'https'
urls to a proxy server, orNone
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 inlomond.constants
.
-
add_header
(header, value)¶ Add a custom header to the websocket request.
Parameters: - header (bytes) – Name of the header.
- value (bytes) – Value of the header.
-
build_request
()¶ 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.
Parameters: - code (int) – A closing code, which should probably be one of
the enumerations in
lomond.status.Status
or a valid value as specified in https://tools.ietf.org/html/rfc6455#section-7.4 - reason (str) – A short descriptive reason why the websocket is closing. This value is intended for the remote end to help in debugging.
Note
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.
- code (int) – A closing code, which should probably be one of
the enumerations in
-
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.
Parameters: - 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.
Returns: An iterable of
Event
instances.
-
feed
(data)¶ 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_disconnect
()¶ Force the socket to disconnect.
-
is_active
¶ Boolean that indicates the socket is ‘active’ i.e. not in a closing state.
-
is_closed
¶ Flag that indicates if the websocket is closed.
-
is_closing
¶ Boolean that indicates if the websocket is in a closing state. No further messages may be sent when a websocket is closing.
-
is_secure
¶ Boolean that indicates if the websocket is over ssl (i.e. the wss protocol).
-
on_disconnect
()¶ Called on disconnect.
-
on_response
(response)¶ Called when the HTTP response has been received.
-
process_extensions
(extensions)¶ Process extension headers.
-
reset
()¶ Reset the state.
-
send_binary
(data, compress=True)¶ Send a binary message.
Parameters: - data (bytes) – Binary data to send.
- compress (bool) – Send data in compressed form, if compression is enabled on the server.
Raises: 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'}) 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_ping
(data='')¶ Send a ping packet.
Parameters: data (bytes) – Data to send in the ping message (must be <= 125 bytes).
Raises: - TypeError – If data is not bytes.
- ValueError – If data is > 125 bytes.
-
send_pong
(data)¶ 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.
Raises: - TypeError – If data is not bytes.
- ValueError – If data is > 125 bytes.
-
send_text
(text, compress=True)¶ Send a text message.
Parameters: - text (str) – Text to send.
- compress (bool) – Send the text in compressed form, if compression is enabled on the server.
Raises: TypeError – If data is not str (or unicode on Py2).
-
sent_close_time
¶ The time (seconds since session start) when a close packet was sent (or None if no close packet has been sent).
-
supports_compression
¶ Boolean that indicates if the server has compression enabled.
- url (str) – A websocket URL, must have a