WebsocketConnection

class WebsocketConnection(**properties: Any)

Superclasses: Object

The WebSocket Protocol

Provides support for the WebSocket protocol.

To connect to a WebSocket server, create a Session and call websocket_connect_async. To accept WebSocket connections, create a Server and add a handler to it with add_websocket_handler.

(Lower-level support is available via websocket_client_prepare_handshake and websocket_client_verify_handshake, for handling the client side of the WebSocket handshake, and websocket_server_process_handshake for handling the server side.)

WebsocketConnection handles the details of WebSocket communication. You can use send_text and send_binary to send data, and the message signal to receive data. (WebsocketConnection currently only supports asynchronous I/O.)

Constructors

class WebsocketConnection

classmethod new(stream: IOStream, uri: Uri, type: WebsocketConnectionType, origin: str | None, protocol: str | None, extensions: list[WebsocketExtension]) → WebsocketConnection

Creates a WebsocketConnection on stream with the given active extensions.

This should be called after completing the handshake to begin using the WebSocket protocol.

Parameters:

• stream – a IOStream connected to the WebSocket server

• uri – the URI of the connection

• type – the type of connection (client/side)

• origin – the Origin of the client

• protocol – the subprotocol in use

• extensions – a List of WebsocketExtension objects

Methods

class WebsocketConnection

close(code: int, data: str | None = None) → None

Close the connection in an orderly fashion.

Note that until the closed signal fires, the connection is not yet completely closed. The close message is not even sent until the main loop runs.

The code and data are sent to the peer along with the close request. If code is NO_STATUS a close message with no body (without code and data) is sent. Note that the data must be UTF-8 valid.

Parameters:

• code – close code

• data – close data

get_close_code() → int

Get the close code received from the WebSocket peer.

This only becomes valid once the WebSocket is in the CLOSED state. The value will often be in the WebsocketCloseCode enumeration, but may also be an application defined close code.

get_close_data() → str

Get the close data received from the WebSocket peer.

This only becomes valid once the WebSocket is in the CLOSED state. The data may be freed once the main loop is run, so copy it if you need to keep it around.

get_connection_type() → WebsocketConnectionType

Get the connection type (client/server) of the connection.

get_extensions() → list[WebsocketExtension]

Get the extensions chosen via negotiation with the peer.

get_io_stream() → IOStream

Get the I/O stream the WebSocket is communicating over.

get_keepalive_interval() → int

Gets the keepalive interval in seconds or 0 if disabled.

get_keepalive_pong_timeout() → int

Gets the keepalive pong timeout in seconds or 0 if disabled.

Added in version 3.6.

get_max_incoming_payload_size() → int

Gets the maximum payload size allowed for incoming packets.

get_origin() → str | None

Get the origin of the WebSocket.

get_protocol() → str | None

Get the protocol chosen via negotiation with the peer.

get_state() → WebsocketState

Get the current state of the WebSocket.

get_uri() → Uri

Get the URI of the WebSocket.

For servers this represents the address of the WebSocket, and for clients it is the address connected to.

send_binary(data: list[int] | None = None) → None

Send a binary message to the peer.

If length is 0, data may be None.

The message is queued to be sent and will be sent when the main loop is run.

Parameters:

data – the message contents

send_message(type: WebsocketDataType, message: Bytes) → None

Send a message of the given type to the peer. Note that this method, allows to send text messages containing None characters.

The message is queued to be sent and will be sent when the main loop is run.

Parameters:

• type – the type of message contents

• message – the message data as Bytes

send_text(text: str) → None

Send a None-terminated text (UTF-8) message to the peer.

If you need to send text messages containing None characters use send_message instead.

The message is queued to be sent and will be sent when the main loop is run.

Parameters:

text – the message contents

set_keepalive_interval(interval: int) → None

Sets the interval in seconds on when to send a ping message which will serve as a keepalive message.

If set to 0 the keepalive message is disabled.

Parameters:

interval – the interval to send a ping message or 0 to disable it

set_keepalive_pong_timeout(pong_timeout: int) → None

Set the timeout in seconds for when the absence of a pong from a keepalive ping is assumed to be caused by a faulty connection.

If set to 0 then the absence of pongs from keepalive pings is ignored.

Added in version 3.6.

Parameters:

pong_timeout – the timeout in seconds

set_max_incoming_payload_size(max_incoming_payload_size: int) → None

Sets the maximum payload size allowed for incoming packets.

It does not limit the outgoing packet size.

Parameters:

max_incoming_payload_size – the maximum payload size

Properties

class WebsocketConnection

props.connection_type: WebsocketConnectionType

The type of the None singleton.

props.extensions: Any

The type of the None singleton.

props.io_stream: IOStream

The type of the None singleton.

props.keepalive_interval: int

The type of the None singleton.

props.keepalive_pong_timeout: int

The type of the None singleton.

Added in version 3.6.

props.max_incoming_payload_size: int

The type of the None singleton.

props.origin: str

The type of the None singleton.

props.protocol: str

The type of the None singleton.

props.state: WebsocketState

The type of the None singleton.

props.uri: Uri

The type of the None singleton.

Signals

class WebsocketConnection.signals

closed() → None

The type of the None singleton.

closing() → None

The type of the None singleton.

error(error: GError) → None

The type of the None singleton.

Parameters:

error – the error that occured

message(type: int, message: Bytes) → None

The type of the None singleton.

Parameters:

• type – the type of message contents

• message – the message data

pong(message: Bytes) → None

The type of the None singleton.

Parameters:

message – the application data (if any)