Both sides (Sans-I/O)¶
- class websockets.protocol.Protocol(side, *, state=State.OPEN, max_size=1048576, logger=None)[source]¶
Sans-I/O implementation of a WebSocket connection.
- Parameters:
state (State) – Initial state of the WebSocket connection.
max_size (int | None) – Maximum size of incoming messages in bytes;
None
disables the limit.logger (LoggerLike | None) – Logger for this connection; depending on
side
, defaults tologging.getLogger("websockets.client")
orlogging.getLogger("websockets.server")
; see the logging guide for details.
- receive_data(data)[source]¶
Receive data from the network.
After calling this method:
You must call
data_to_send()
and send this data to the network.You should call
events_received()
and process resulting events.
- Raises:
EOFError – If
receive_eof()
was called earlier.
- receive_eof()[source]¶
Receive the end of the data stream from the network.
After calling this method:
You must call
data_to_send()
and send this data to the network; it will return[b""]
, signaling the end of the stream, or[]
.You aren’t expected to call
events_received()
; it won’t return any new events.
receive_eof()
is idempotent.
- send_continuation(data, fin)[source]¶
Send a Continuation frame.
- Parameters:
- Raises:
ProtocolError – If a fragmented message isn’t in progress.
- send_text(data, fin=True)[source]¶
Send a Text frame.
- Parameters:
- Raises:
ProtocolError – If a fragmented message is in progress.
- send_binary(data, fin=True)[source]¶
Send a Binary frame.
- Parameters:
- Raises:
ProtocolError – If a fragmented message is in progress.
- send_close(code=None, reason='')[source]¶
Send a Close frame.
- Parameters:
- Raises:
ProtocolError – If the code isn’t valid or if a reason is provided without a code.
- send_ping(data)[source]¶
Send a Ping frame.
- Parameters:
data (bytes) – payload containing arbitrary binary data.
- send_pong(data)[source]¶
Send a Pong frame.
- Parameters:
data (bytes) – payload containing arbitrary binary data.
- fail(code, reason='')[source]¶
Fail the WebSocket connection.
- Parameters:
- Raises:
ProtocolError – If the code isn’t valid.
- events_received()[source]¶
Fetch events generated from data received from the network.
Call this method immediately after any of the
receive_*()
methods.Process resulting events, likely by passing them to the application.
- data_to_send()[source]¶
Obtain data to send to the network.
Call this method immediately after any of the
receive_*()
,send_*()
, orfail()
methods.Write resulting data to the connection.
The empty bytestring
SEND_EOF
signals the end of the data stream. When you receive it, half-close the TCP connection.
- close_expected()[source]¶
Tell if the TCP connection is expected to close soon.
Call this method immediately after any of the
receive_*()
,send_close()
, orfail()
methods.If it returns
True
, schedule closing the TCP connection after a short timeout if the other side hasn’t already closed it.- Returns:
Whether the TCP connection is expected to close soon.
- Return type:
- logger: Logger | LoggerAdapter¶
Logger for this connection.
- property close_code: int | None¶
WebSocket close code received from the remote endpoint.
None
if the connection isn’t closed yet.
- property close_reason: str | None¶
WebSocket close reason received from the remote endpoint.
None
if the connection isn’t closed yet.
- property close_exc: ConnectionClosed¶
Exception to raise when trying to interact with a closed connection.
Don’t raise this exception while the connection
state
isCLOSING
; wait until it’sCLOSED
.Indeed, the exception includes the close code and reason, which are known only once the connection is closed.
- Raises:
AssertionError – If the connection isn’t closed yet.
- class websockets.protocol.Side(value)[source]¶
A WebSocket connection is either a server or a client.
- SERVER = 0¶
- CLIENT = 1¶
- class websockets.protocol.State(value)[source]¶
A WebSocket connection is in one of these four states.
- CONNECTING = 0¶
- OPEN = 1¶
- CLOSING = 2¶
- CLOSED = 3¶
- websockets.protocol.SEND_EOF = b''¶
Sentinel signaling that the TCP connection must be half-closed.