Client (threading
)¶
Opening a connection¶
- websockets.sync.client.connect(uri, *, sock=None, ssl=None, server_hostname=None, origin=None, extensions=None, subprotocols=None, additional_headers=None, user_agent_header='Python/3.10 websockets/14.0.dev32+g76f6f57', compression='deflate', open_timeout=10, close_timeout=10, max_size=1048576, max_queue=16, logger=None, create_connection=None, **kwargs)[source]¶
Connect to the WebSocket server at
uri
.This function returns a
ClientConnection
instance, which you can use to send and receive messages.connect()
may be used as a context manager:from websockets.sync.client import connect with connect(...) as websocket: ...
The connection is closed automatically when exiting the context.
- Parameters:
uri (str) – URI of the WebSocket server.
sock (socket | None) – Preexisting TCP socket.
sock
overrides the host and port fromuri
. You may callsocket.create_connection()
to create a suitable TCP socket.ssl (SSLContext | None) – Configuration for enabling TLS on the connection.
server_hostname (str | None) – Host name for the TLS handshake.
server_hostname
overrides the host name fromuri
.origin (Origin | None) – Value of the
Origin
header, for servers that require it.extensions (Sequence[ClientExtensionFactory] | None) – List of supported extensions, in order in which they should be negotiated and run.
subprotocols (Sequence[Subprotocol] | None) – List of supported subprotocols, in order of decreasing preference.
additional_headers (HeadersLike | None) – Arbitrary HTTP headers to add to the handshake request.
user_agent_header (str | None) – Value of the
User-Agent
request header. It defaults to"Python/x.y.z websockets/X.Y"
. Setting it toNone
removes the header.compression (str | None) – The “permessage-deflate” extension is enabled by default. Set
compression
toNone
to disable it. See the compression guide for details.open_timeout (float | None) – Timeout for opening the connection in seconds.
None
disables the timeout.close_timeout (float | None) – Timeout for closing the connection in seconds.
None
disables the timeout.max_size (int | None) – Maximum size of incoming messages in bytes.
None
disables the limit.max_queue (int | tuple[int, int | None]) – High-water mark of the buffer where frames are received. It defaults to 16 frames. The low-water mark defaults to
max_queue // 4
. You may pass a(high, low)
tuple to set the high-water and low-water marks.logger (Logger | LoggerAdapter | None) – Logger for this client. It defaults to
logging.getLogger("websockets.client")
. See the logging guide for details.create_connection (type[ClientConnection] | None) – Factory for the
ClientConnection
managing the connection. Set it to a wrapper or a subclass to customize connection handling.
Any other keyword arguments are passed to
create_connection()
.- Raises:
InvalidURI – If
uri
isn’t a valid WebSocket URI.OSError – If the TCP connection fails.
InvalidHandshake – If the opening handshake fails.
TimeoutError – If the opening handshake times out.
Using a connection¶
- class websockets.sync.client.ClientConnection(socket, protocol, *, close_timeout=10, max_queue=16)[source]¶
threading
implementation of a WebSocket client connection.ClientConnection
providesrecv()
andsend()
methods for receiving and sending messages.It supports iteration to receive messages:
for message in websocket: process(message)
The iterator exits normally when the connection is closed with close code 1000 (OK) or 1001 (going away) or without a close code. It raises a
ConnectionClosedError
when the connection is closed with any other code.The
close_timeout
andmax_queue
arguments have the same meaning as inconnect()
.- Parameters:
socket (socket.socket) – Socket connected to a WebSocket server.
protocol (ClientProtocol) – Sans-I/O connection.
- for ... in __iter__()[source]¶
Iterate on incoming messages.
The iterator calls
recv()
and yields messages in an infinite loop.It exits when the connection is closed normally. It raises a
ConnectionClosedError
exception after a protocol error or a network failure.
- recv(timeout=None, decode=None)[source]¶
Receive the next message.
When the connection is closed,
recv()
raisesConnectionClosed
. Specifically, it raisesConnectionClosedOK
after a normal closure andConnectionClosedError
after a protocol error or a network failure. This is how you detect the end of the message stream.If
timeout
isNone
, block until a message is received. Iftimeout
is set and no message is received withintimeout
seconds, raiseTimeoutError
. Settimeout
to0
to check if a message was already received.If the message is fragmented, wait until all fragments are received, reassemble them, and return the whole message.
- Parameters:
- Returns:
A string (
str
) for a Text frame or a bytestring (bytes
) for a Binary frame.You may override this behavior with the
decode
argument:Set
decode=False
to disable UTF-8 decoding of Text frames and return a bytestring (bytes
). This improves performance when decoding isn’t needed, for example if the message contains JSON and you’re using a JSON library that expects a bytestring.Set
decode=True
to force UTF-8 decoding of Binary frames and return a string (str
). This may be useful for servers that send binary frames instead of text frames.
- Raises:
ConnectionClosed – When the connection is closed.
ConcurrencyError – If two threads call
recv()
orrecv_streaming()
concurrently.
- Return type:
- for ... in recv_streaming(decode=None)[source]¶
Receive the next message frame by frame.
This method is designed for receiving fragmented messages. It returns an iterator that yields each fragment as it is received. This iterator must be fully consumed. Else, future calls to
recv()
orrecv_streaming()
will raiseConcurrencyError
, making the connection unusable.recv_streaming()
raises the same exceptions asrecv()
.- Parameters:
decode (bool | None) – Set this flag to override the default behavior of returning
str
orbytes
. See below for details.- Returns:
An iterator of strings (
str
) for a Text frame or bytestrings (bytes
) for a Binary frame.You may override this behavior with the
decode
argument:Set
decode=False
to disable UTF-8 decoding of Text frames and return bytestrings (bytes
). This may be useful to optimize performance when decoding isn’t needed.Set
decode=True
to force UTF-8 decoding of Binary frames and return strings (str
). This is useful for servers that send binary frames instead of text frames.
- Raises:
ConnectionClosed – When the connection is closed.
ConcurrencyError – If two threads call
recv()
orrecv_streaming()
concurrently.
- Return type:
- send(message, text=None)[source]¶
Send a message.
A string (
str
) is sent as a Text frame. A bytestring or bytes-like object (bytes
,bytearray
, ormemoryview
) is sent as a Binary frame.You may override this behavior with the
text
argument:Set
text=True
to send a bytestring or bytes-like object (bytes
,bytearray
, ormemoryview
) as a Text frame. This improves performance when the message is already UTF-8 encoded, for example if the message contains JSON and you’re using a JSON library that produces a bytestring.Set
text=False
to send a string (str
) in a Binary frame. This may be useful for servers that expect binary frames instead of text frames.
send()
also accepts an iterable of strings, bytestrings, or bytes-like objects to enable fragmentation. Each item is treated as a message fragment and sent in its own frame. All items must be of the same type, or elsesend()
will raise aTypeError
and the connection will be closed.send()
rejects dict-like objects because this is often an error. (If you really want to send the keys of a dict-like object as fragments, call itskeys()
method and pass the result tosend()
.)When the connection is closed,
send()
raisesConnectionClosed
. Specifically, it raisesConnectionClosedOK
after a normal connection closure andConnectionClosedError
after a protocol error or a network failure.- Parameters:
message (str | bytes | Iterable[str | bytes]) – Message to send.
- Raises:
ConnectionClosed – When the connection is closed.
ConcurrencyError – If the connection is sending a fragmented message.
TypeError – If
message
doesn’t have a supported type.
- close(code=CloseCode.NORMAL_CLOSURE, reason='')[source]¶
Perform the closing handshake.
close()
waits for the other end to complete the handshake, for the TCP connection to terminate, and for all incoming messages to be read withrecv()
.close()
is idempotent: it doesn’t do anything once the connection is closed.
- ping(data=None)[source]¶
Send a Ping.
A ping may serve as a keepalive or as a check that the remote endpoint received all messages up to this point
- Parameters:
data (str | bytes | None) – Payload of the ping. A
str
will be encoded to UTF-8. Ifdata
isNone
, the payload is four random bytes.- Returns:
An event that will be set when the corresponding pong is received. You can ignore it if you don’t intend to wait.
pong_event = ws.ping() pong_event.wait() # only if you want to wait for the pong
- Raises:
ConnectionClosed – When the connection is closed.
ConcurrencyError – If another ping was sent with the same data and the corresponding pong wasn’t received yet.
- Return type:
- pong(data=b'')[source]¶
Send a Pong.
An unsolicited pong may serve as a unidirectional heartbeat.
- Parameters:
data (str | bytes) – Payload of the pong. A
str
will be encoded to UTF-8.- Raises:
ConnectionClosed – When the connection is closed.
WebSocket connection objects also provide these attributes:
- logger: LoggerLike¶
Logger for this connection.
- property local_address: Any¶
Local address of the connection.
For IPv4 connections, this is a
(host, port)
tuple.The format of the address depends on the address family. See
getsockname()
.
- property remote_address: Any¶
Remote address of the connection.
For IPv4 connections, this is a
(host, port)
tuple.The format of the address depends on the address family. See
getpeername()
.
The following attributes are available after the opening handshake, once the WebSocket connection is open:
- property subprotocol: Subprotocol | None¶
Subprotocol negotiated during the opening handshake.
None
if no subprotocol was negotiated.