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:
data (bytes) – payload containing the same kind of data as the initial frame.
fin (bool) – FIN bit; set it to
True
if this is the last frame of a fragmented message and toFalse
otherwise.
- Raises:
ProtocolError – If a fragmented message isn’t in progress.
- send_text(data, fin=True)[source]¶
Send a Text frame.
- Parameters:
data (bytes) – payload containing text encoded with UTF-8.
fin (bool) – FIN bit; set it to
False
if this is the first frame of a fragmented message.
- Raises:
ProtocolError – If a fragmented message is in progress.
- send_binary(data, fin=True)[source]¶
Send a Binary frame.
- Parameters:
data (bytes) – payload containing arbitrary binary data.
fin (bool) – FIN bit; set it to
False
if this is the first frame of a fragmented message.
- Raises:
ProtocolError – If a fragmented message is in progress.
- send_close(code=None, reason='')[source]¶
Send a Close frame.
- Parameters:
code (int | None) – close code.
reason (str) – close reason.
- 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:
code (int) – close code
reason (str) – close reason
- 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.- Returns:
Data to write to the connection.
- Return type:
list[bytes]
- 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:
bool
- id: UUID¶
Unique identifier of the connection. Useful in logs.
- logger: Logger | LoggerAdapter¶
Logger for this connection.
- property state: State¶
State of the WebSocket connection.
Defined in 4.1, 4.2, 7.1.3, and 7.1.4 of RFC 6455.
- property close_code: int | None¶
-
None
if the connection isn’t closed yet.
- property close_reason: str | None¶
-
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, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶
A WebSocket connection is either a server or a client.
- SERVER = 0¶
- CLIENT = 1¶
- class websockets.protocol.State(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[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.