chunkystreamsocket

A socket used to send and receive message chunks over a TCP connection. The chunks are assembled back together when receiving.

The class can be used with a ContextManager (e.g. using with … as):

with ChunkyStreamSocket(host='127.0.0.1', port=12345) as c:
    c.connect(timeout=None)
    c.send(b'This is a test sending raw bytes.')

Or without:

c = ChunkyStreamSocket(host='127.0.0.1', port=12345)
c.connect(timeout=None)
c.send(b'This is a test sending raw bytes.')
c.close()

class pymisclib.chunkystreamsocket.ChunkyStreamSocket(host: str = '127.0.0.1', port: int = 10000, sock: ~socket.socket | None = None, logger: ~logging.Logger = <Logger pymisclib.chunkystreamsocket (WARNING)>, debug: bool = False, log_n_bytes: int = 0, family: ~socket.AddressFamily = AddressFamily.AF_INET, _backlog_bytes: bytes | None = None, _client_address: tuple[str, int] | None = None, _connected: bool = False, _chunk_size: int = 4096, _is_server_socket: bool = False)

Socket used to send message chunks over a TCP connection.

accept() → tuple[socket, tuple[str, int]]

Accept a client connection on the (server) socket.

Returns:

The client socket and client address (host, port) tuple.

Return type:

tuple[socket.socket, tuple[str, int]]

Raises:

NoSocketError – No socket to accept connection from.
NotAServerSocketError – The socket is not a server socket.
TimeoutError – No connection accepted withing allowed time.

bind_and_listen(backlog: int = 5, timeout: float | None = None)

Bind to the host and port to make a server socket.

Parameters:

backlog¶ (int) – The maximum number of queued connections.
timeout¶ (float|None) – The number of seconds after which socket operations will time out. Set to None for a blocking socket.

close()

Close the socket.

The underlying OS socket is released and the sock member will be None.

connect(timeout: float | None = None)

Connect the client socket to a server at host:port.

Parameters:

timeout¶ (float|None) – The number of seconds after which socket operations will time out. Set to None for a blocking socket.

Raises:

BlockingIOError – A non-blocking connection attempt failed because establishing the connection takes some time. Try again later.
ConnectionError – Failed to establish connection.
InterruptedError – Connection attempt was interrrupted by a signal.
TimeoutError – Connection attempt timed out.

recv(length: int, timeout: float | None = None) → bytes

Receive length bytes from the socket.

This function handles chunked data (i.e. the data to receive is split into multiple packets). If more data than expected is received, it is placed into a backlog buffer until the next call to a receive function.

Parameters:

length¶ (int) – Number of bytes to read.
timeout¶ (float|None) – Timeout in seconds or None for blocking I/O.

Returns:

The received bytes.

Return type:

bytes

Raises:

ConnectionError – The connection was broken.
NoSocketError – No socket to accept connection from.
RuntimeError – The socket is not connected.
TimeoutError – Timeout while receiving.

recv_to_separator(separator: bytes) → bytes

Receive bytes until the given separator is found.

This function handles chunked data (i.e. the data to receive is split into multiple packets). If more data than expected is received, it is placed into a backlog buffer until the next call to a receive function.

Parameters:

separator¶ (bytes) – One or more bytes that separate messages in the TCP stream.

Returns:

The received bytes.

Return type:

bytes

Raises:

ConnectionError – The connection was broken.
NoSocketError – No socket to accept connection from.
TimeoutError – A timeout occurred while receiving.

send(msg_bytes: bytes) → int

Send the bytes.

Parameters:

msg_bytes¶ (bytes) – The bytes to send. If the receiver is expecting a separator, it must be appended to the message by the caller.

Returns:

The number of bytes sent.

Return type:

int

Raises:

ConnectionError – sending failed because the connection was broken.
NoSocketError – No socket to accept connection from.

property connected: bool: Return True if the connection is established.

property connection: str: Human-readable description of the underlying connection.

debug: bool = False: True to enable debug output.

family: AddressFamily = 2

Address family used by the socket.

Usually socket.AF_INET [default] or socket.AF_INET6.

host: str = '127.0.0.1': Host name or IP address.

log_n_bytes: int = 0: Number of communicated bytes to log.

logger: Logger = <Logger pymisclib.chunkystreamsocket (WARNING)>: Logger for diagnostics.

port: int = 10000: Port number.

property server_socket: bool

Is this a server socket (which accepts connections) or a client: socket, which connects to a server?

Returns:: True if server socket, False if client socket.

sock: socket | None = None: Socket to use.