websocket/_app.py

The _app.py file

class websocket._app.WebSocketApp(url: str, header: list[str] | dict[str, str] | Callable[[], list[str] | dict[str, str]] | None = None, on_open: Callable[[WebSocketApp], None] | None = None, on_reconnect: Callable[[WebSocketApp], None] | None = None, on_message: Callable[[WebSocketApp, Any], None] | None = None, on_error: Callable[[WebSocketApp, Any], None] | None = None, on_close: Callable[[WebSocketApp, Any, Any], None] | None = None, on_ping: Callable | None = None, on_pong: Callable | None = None, on_cont_message: Callable | None = None, keep_running: bool = True, get_mask_key: Callable | None = None, cookie: str | None = None, subprotocols: list[str] | None = None, on_data: Callable | None = None, socket: socket | None = None)

Higher level of APIs are provided. The interface is like JavaScript WebSocket object.

__init__(url: str, header: list[str] | dict[str, str] | Callable[[], list[str] | dict[str, str]] | None = None, on_open: Callable[[WebSocketApp], None] | None = None, on_reconnect: Callable[[WebSocketApp], None] | None = None, on_message: Callable[[WebSocketApp, Any], None] | None = None, on_error: Callable[[WebSocketApp, Any], None] | None = None, on_close: Callable[[WebSocketApp, Any, Any], None] | None = None, on_ping: Callable | None = None, on_pong: Callable | None = None, on_cont_message: Callable | None = None, keep_running: bool = True, get_mask_key: Callable | None = None, cookie: str | None = None, subprotocols: list[str] | None = None, on_data: Callable | None = None, socket: socket | None = None) → None

WebSocketApp initialization

Parameters:

• url (str) – Websocket url.

• header (list or dict or Callable) – Custom header for websocket handshake. If the parameter is a callable object, it is called just before the connection attempt. The returned dict or list is used as custom header value. This could be useful in order to properly setup timestamp dependent headers.

• on_open (function) – Callback object which is called at opening websocket. on_open has one argument. The 1st argument is this class object.

• on_reconnect (function) – Callback object which is called at reconnecting websocket. on_reconnect has one argument. The 1st argument is this class object.

• on_message (function) – Callback object which is called when received data. on_message has 2 arguments. The 1st argument is this class object. The 2nd argument is utf-8 data received from the server.

• on_error (function) – Callback object which is called when we get error. on_error has 2 arguments. The 1st argument is this class object. The 2nd argument is exception object. Called for every error, including errors during reconnect attempts (since 1.10.0). To distinguish reconnect-phase errors from the initial failure, track state with the on_reconnect and on_open callbacks.

• on_close (function) – Callback object which is called when connection is closed. on_close has 3 arguments. The 1st argument is this class object. The 2nd argument is close_status_code. The 3rd argument is close_msg.

• on_cont_message (function) – Callback object which is called when a continuation frame is received. on_cont_message has 3 arguments. The 1st argument is this class object. The 2nd argument is utf-8 string which we get from the server. The 3rd argument is continue flag. if 0, the data continue to next frame data

• on_data (function) – Callback object which is called when a message received. This is called before on_message or on_cont_message, and then on_message or on_cont_message is called. on_data has 4 argument. The 1st argument is this class object. The 2nd argument is utf-8 string which we get from the server. The 3rd argument is data type. ABNF.OPCODE_TEXT or ABNF.OPCODE_BINARY will be came. The 4th argument is continue flag. If 0, the data continue

• keep_running (bool) – This parameter is obsolete and ignored.

• get_mask_key (function) – A callable function to get new mask keys, see the WebSocket.set_mask_key’s docstring for more information.

• cookie (str) – Cookie value.

• subprotocols (list) – List of available sub protocols. Default is None.

• socket (socket) – Pre-initialized stream socket. With a wss:// URL, a socket that is not already an ssl.SSLSocket is wrapped in TLS using sslopt.

close(**kwargs: Any) → None

Close websocket connection.

run_forever(sockopt: list | None = None, sslopt: dict | None = None, ping_interval: float | int = 0, ping_timeout: int | float | None = None, ping_payload: str = '', http_proxy_host: str | None = None, http_proxy_port: int | str | None = None, http_no_proxy: list | None = None, http_proxy_auth: tuple | None = None, http_proxy_timeout: float | None = None, skip_utf8_validation: bool = False, host: str | None = None, origin: str | None = None, dispatcher: Any = None, suppress_origin: bool = False, suppress_host: bool = False, proxy_type: str | None = None, reconnect: int | None = None, redirect_limit: int = 3) → bool

Run event loop for WebSocket framework.

This loop is an infinite loop and is alive while websocket is available.

Parameters:

• sockopt (tuple) – Values for socket.setsockopt. sockopt must be tuple and each element is argument of sock.setsockopt.

• sslopt (dict) – Optional dict object for ssl socket option.

• ping_interval (int or float) – Automatically send “ping” command every specified period (in seconds). If set to 0, no ping is sent periodically.

• ping_timeout (int or float) – Timeout (in seconds) if the pong message is not received.

• ping_payload (str) – Payload message to send with each ping.

• http_proxy_host (str) – HTTP proxy host name.

• http_proxy_port (int or str) – HTTP proxy port. Required when http_proxy_host is set. Proxies from environment variables default to port 80.

• http_no_proxy (list) – Whitelisted host names that don’t use the proxy.

• http_proxy_timeout (int or float) – HTTP proxy timeout, default is 60 sec as per python-socks.

• http_proxy_auth (tuple) – HTTP proxy auth information. tuple of username and password. Default is None.

• skip_utf8_validation (bool) – skip utf8 validation.

• host (str) – update host header.

• origin (str) – update origin header.

• dispatcher (Dispatcher object) – customize reading data from socket.

• suppress_origin (bool) – suppress outputting origin header.

• suppress_host (bool) – suppress outputting host header.

• proxy_type (str) – type of proxy from: http, socks4, socks4a, socks5, socks5h

• reconnect (int) – delay interval when reconnecting

• redirect_limit (int) – Number of HTTP redirects to follow during each opening handshake, the same as WebSocket.connect(redirect_limit=...). Default is 3. Set it to 0 to refuse redirects, for example when the URL was validated against an allowlist and a redirect could point the connection at another host. A refused redirect is reported to on_error as a WebSocketException.

Returns:

teardown – False if the WebSocketApp is closed gracefully, True if an error was handled during the loop.

Return type:

bool

Raises:

KeyboardInterrupt – If interrupted during the loop. The connection is torn down before the interrupt is propagated to the caller.

send(data: bytes | str, opcode: int = 1) → None

send message

Parameters:

• data (str) – Message to send. If you set opcode to OPCODE_TEXT, data must be utf-8 string or unicode.

• opcode (int) – Operation code of data. Default is OPCODE_TEXT.

send_bytes(data: bytes | bytearray) → None

Sends a sequence of bytes.

send_text(text_data: str) → None

Sends UTF-8 encoded text.