Data Transport Adapters

Low-level transports module.

Abstract Base Classes

Low-level transports interfaces module.

class easynetwork.lowlevel.api_sync.transports.abc.BaseTransport

Bases: TypedAttributeProvider

Base class for a data transport.

__exit__(exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None) → None

Calls close().

abstractmethod close() → None

Closes the transport.

abstractmethod is_closed() → bool

Checks if close() has been called.

Returns:

True if the transport is closed.

Return type:

bool

class easynetwork.lowlevel.api_sync.transports.abc.DatagramReadTransport

Bases: BaseTransport

A reader transport of unreliable packets of data.

abstractmethod recv(timeout: float) → bytes

Read and return the next available packet.

Parameters:

timeout (float) – the allowed time (in seconds) for blocking operations. Can be set to math.inf.

Raises:
Returns:

some bytes.

Return type:

bytes

class easynetwork.lowlevel.api_sync.transports.abc.DatagramTransport

Bases: DatagramWriteTransport, DatagramReadTransport

A transport of unreliable packets of data.

class easynetwork.lowlevel.api_sync.transports.abc.DatagramWriteTransport

Bases: BaseTransport

A writer transport of unreliable packets of data.

abstractmethod send(data: bytes | bytearray | memoryview, timeout: float) → None

Send the data bytes to the remote peer.

Parameters:
Raises:
class easynetwork.lowlevel.api_sync.transports.abc.StreamReadTransport

Bases: BaseTransport

A continuous stream data reader transport.

recv(bufsize: int, timeout: float) → bytes

Read and return up to bufsize bytes.

Parameters:

  • bufsize (int) – the maximum buffer size.

  • timeout (float) – the allowed time (in seconds) for blocking operations. Can be set to math.inf.

Raises:
Returns:

some bytes.

If bufsize is greater than zero and an empty byte buffer is returned, this indicates an EOF.

Return type:

bytes

abstractmethod recv_into(buffer: bytearray | memoryview | collections.abc.Buffer, timeout: float) → int

Read into the given buffer.

Parameters:
Raises:
Returns:

the number of bytes written.

Returning 0 for a non-zero buffer indicates an EOF.

Return type:

int

class easynetwork.lowlevel.api_sync.transports.abc.StreamTransport

Bases: StreamWriteTransport, StreamReadTransport

A continuous stream data transport.

abstractmethod send_eof() → None

Closes the write end of the stream after the buffered write data is flushed.

This method does nothing if the transport is closed.

class easynetwork.lowlevel.api_sync.transports.abc.StreamWriteTransport

Bases: BaseTransport

A continuous stream data writer transport.

abstractmethod send(data: bytes | bytearray | memoryview, timeout: float) → int

Send the data bytes to the remote peer.

Parameters:
Raises:
Returns:

the number of sent bytes.

Return type:

int

send_all(data: bytes | bytearray | memoryview, timeout: float) → None

Send the data bytes to the remote peer.

Unlike send(), this method continues to send data from bytes until either all data has been sent or an error occurs. None is returned on success. On error, an exception is raised, and there is no way to determine how much data, if any, was successfully sent.

Parameters:
Raises:
send_all_from_iterable(iterable_of_data: Iterable[bytes | bytearray | memoryview], timeout: float) → None

An efficient way to send a bunch of data via the transport.

Like send_all(), this method continues to send data from bytes until either all data has been sent or an error occurs. None is returned on success. On error, an exception is raised, and there is no way to determine how much data, if any, was successfully sent.

Parameters:
Raises:

selectors-based Transports

selectors transports module.

Here are abstract base classes which use selectors module to perform I/O polling.

See also

selectors — High-level I/O multiplexing

High-level interface for I/O polling

class easynetwork.lowlevel.api_sync.transports.base_selector.SelectorBaseTransport

Bases: BaseTransport

Base class for transports using the selectors module for blocking operations polling.

__init__(retry_interval: float, selector_factory: Callable[[], BaseSelector] | None = None) → None
Parameters:
_retry(callback: Callable[[], _T_Return], timeout: float) → tuple[_T_Return, float]

Calls callback without argument and returns the output.

If the callable raises WouldBlockOnRead or WouldBlockOnWrite, waits for fileno to be available for reading or writing respectively, and retries to call the callback.

Parameters:

  • callback (Callable[[], _T_Return]) – the function to call.

  • timeout (float) – the maximum amount of seconds to wait for the file descriptor to be available.

Raises:

TimeoutError – timed out

Returns:

a tuple with the result of the callback and the timeout which is deduced from the waited time.

Return type:

tuple[_T_Return, float]

class easynetwork.lowlevel.api_sync.transports.base_selector.SelectorDatagramReadTransport

Bases: SelectorBaseTransport, DatagramReadTransport

A reader transport of unreliable packets of data using the selectors module for blocking operations polling.

abstractmethod recv_noblock() → bytes

Read and return the next available packet.

Raises:
Returns:

some bytes.

Return type:

bytes

recv(timeout: float) → bytes

Read and return the next available packet.

The default implementation will retry to call recv_noblock() until it succeeds under the given timeout.

Return type:

bytes

class easynetwork.lowlevel.api_sync.transports.base_selector.SelectorDatagramTransport

Bases: SelectorDatagramWriteTransport, SelectorDatagramReadTransport, DatagramTransport

A transport of unreliable packets of data using the selectors module for blocking operations polling.

class easynetwork.lowlevel.api_sync.transports.base_selector.SelectorDatagramWriteTransport

Bases: SelectorBaseTransport, DatagramWriteTransport

A writer transport of unreliable packets of data using the selectors module for blocking operations polling.

abstractmethod send_noblock(data: bytes | bytearray | memoryview) → None

Send the data bytes to the remote peer.

Parameters:

data (bytes | bytearray | memoryview) – the bytes to send.

Raises:
send(data: bytes | bytearray | memoryview, timeout: float) → None

Send the data bytes to the remote peer.

The default implementation will retry to call send_noblock() until it succeeds under the given timeout.

class easynetwork.lowlevel.api_sync.transports.base_selector.SelectorStreamReadTransport

Bases: SelectorBaseTransport, StreamReadTransport

A continuous stream data reader transport using the selectors module for blocking operations polling.

recv_noblock(bufsize: int) → bytes

Read and return up to bufsize bytes.

Parameters:

bufsize (int) – the maximum buffer size.

Raises:
Returns:

some bytes.

If bufsize is greater than zero and an empty byte buffer is returned, this indicates an EOF.

Return type:

bytes

recv(bufsize: int, timeout: float) → bytes

Read and return up to bufsize bytes.

The default implementation will retry to call recv_noblock() until it succeeds under the given timeout.

Return type:

bytes

abstractmethod recv_noblock_into(buffer: bytearray | memoryview | collections.abc.Buffer) → int

Read into the given buffer.

Parameters:

buffer (bytearray | memoryview | collections.abc.Buffer) – where to write the received bytes.

Raises:
Returns:

the number of bytes written.

Returning 0 for a non-zero buffer indicates an EOF.

Return type:

int

recv_into(buffer: bytearray | memoryview | collections.abc.Buffer, timeout: float) → int

Read into the given buffer.

The default implementation will retry to call recv_noblock_into() until it succeeds under the given timeout.

Return type:

int

class easynetwork.lowlevel.api_sync.transports.base_selector.SelectorStreamTransport

Bases: SelectorStreamWriteTransport, SelectorStreamReadTransport, StreamTransport

A continuous stream data transport using the selectors module for blocking operations polling.

class easynetwork.lowlevel.api_sync.transports.base_selector.SelectorStreamWriteTransport

Bases: SelectorBaseTransport, StreamWriteTransport

A continuous stream data writer transport using the selectors module for blocking operations polling.

abstractmethod send_noblock(data: bytes | bytearray | memoryview) → int

Send the data bytes to the remote peer.

Parameters:

data (bytes | bytearray | memoryview) – the bytes to send.

Raises:
Return type:

int

send(data: bytes | bytearray | memoryview, timeout: float) → int

Send the data bytes to the remote peer.

The default implementation will retry to call send_noblock() until it succeeds under the given timeout.

Return type:

int

exception easynetwork.lowlevel.api_sync.transports.base_selector.WouldBlockOnRead

Bases: Exception

The operation would block when reading the pipe.

fileno: int

The file descriptor to wait for.

exception easynetwork.lowlevel.api_sync.transports.base_selector.WouldBlockOnWrite

Bases: Exception

The operation would block when writing on the pipe.

fileno: int

The file descriptor to wait for.

Composite Data Transports

Low-level synchronous transport composite module.

Added in version 1.1.

final class easynetwork.lowlevel.api_sync.transports.composite.StapledDatagramTransport

Bases: DatagramTransport, Generic[_T_SendDatagramTransport, _T_ReceiveDatagramTransport]

A transport of unreliable packets of data that merges two transports.

Extra attributes will be provided from both transports, with the receive stream providing the values in case of a conflict.

Added in version 1.1.

send_transport: _T_SendDatagramTransport

The write part of the transport.

receive_transport: _T_ReceiveDatagramTransport

The read part of the transport.

close() → None

Closes both transports.

is_closed() → bool

Checks if close() has been called on both transports.

Returns:

True if the transports are closed.

Return type:

bool

recv(timeout: float) → bytes

Calls self.receive_transport.recv().

Return type:

bytes

send(data: bytes | bytearray | memoryview, timeout: float) → None

Calls self.send_transport.send().

property extra_attributes: Mapping[Any, Callable[[], Any]]

A mapping of the extra attributes to callables that return the corresponding values.

If the provider wraps another provider, the attributes from that wrapper should also be included in the returned mapping (but the wrapper may override the callables from the wrapped instance).

The callables should raise TypedAttributeLookupError if it is not possible to get the value.

final class easynetwork.lowlevel.api_sync.transports.composite.StapledStreamTransport

Bases: StreamTransport, Generic[_T_SendStreamTransport, _T_ReceiveStreamTransport]

A continous stream data transport that merges two transports.

Extra attributes will be provided from both transports, with the receive stream providing the values in case of a conflict.

Added in version 1.1.

send_transport: _T_SendStreamTransport

The write part of the transport.

receive_transport: _T_ReceiveStreamTransport

The read part of the transport.

close() → None

Closes both transports.

is_closed() → bool

Checks if close() has been called on both transports.

Returns:

True if the transports are closed.

Return type:

bool

recv(bufsize: int, timeout: float) → bytes

Calls self.receive_transport.recv().

Return type:

bytes

recv_into(buffer: bytearray | memoryview | collections.abc.Buffer, timeout: float) → int

Calls self.receive_transport.recv_into().

Return type:

int

send(data: bytes | bytearray | memoryview, timeout: float) → int

Calls self.send_transport.send().

Return type:

int

send_all(data: bytes | bytearray | memoryview, timeout: float) → None

Calls self.send_transport.send_all().

send_all_from_iterable(iterable_of_data: Iterable[bytes | bytearray | memoryview], timeout: float) → None

Calls self.send_transport.send_all_from_iterable().

send_eof() → None

Closes the write end of the stream after the buffered write data is flushed.

If self.send_transport.send_eof() then this calls it. Otherwise, this calls self.send_transport.close().

Note

This method handles the case where self.send_transport.send_eof() raises NotImplementedError or UnsupportedOperation; self.send_transport.close() will be called as a fallback.

property extra_attributes: Mapping[Any, Callable[[], Any]]

A mapping of the extra attributes to callables that return the corresponding values.

If the provider wraps another provider, the attributes from that wrapper should also be included in the returned mapping (but the wrapper may override the callables from the wrapped instance).

The callables should raise TypedAttributeLookupError if it is not possible to get the value.

easynetwork.lowlevel.api_sync.transports.composite._T_SendStreamTransport

Type:    TypeVar

Invariant TypeVar bound to easynetwork.lowlevel.api_sync.transports.abc.StreamWriteTransport.

easynetwork.lowlevel.api_sync.transports.composite._T_ReceiveStreamTransport

Type:    TypeVar

Invariant TypeVar bound to easynetwork.lowlevel.api_sync.transports.abc.StreamReadTransport.

easynetwork.lowlevel.api_sync.transports.composite._T_SendDatagramTransport

Type:    TypeVar

Invariant TypeVar bound to easynetwork.lowlevel.api_sync.transports.abc.DatagramWriteTransport.

easynetwork.lowlevel.api_sync.transports.composite._T_ReceiveDatagramTransport

Type:    TypeVar

Invariant TypeVar bound to easynetwork.lowlevel.api_sync.transports.abc.DatagramReadTransport.

Socket Transport Implementations

Transport implementations module wrapping sockets.

class easynetwork.lowlevel.api_sync.transports.socket.SSLStreamTransport

Bases: SelectorStreamTransport

A stream data transport implementation which wraps a stream socket.

__init__(sock: socket.socket, ssl_context: SSLContext, retry_interval: float, *, handshake_timeout: float | None = None, shutdown_timeout: float | None = None, server_side: bool | None = None, server_hostname: str | None = None, standard_compatible: bool = True, session: SSLSession | None = None, selector_factory: Callable[[], selectors.BaseSelector] | None = None) → None
Parameters:

  • sock (socket.socket) – The SOCK_STREAM socket to wrap.

  • ssl_context (SSLContext) – a ssl.SSLContext object to use to create the transport.

  • retry_interval (float) – The maximum wait time to wait for a blocking operation before retrying. Set it to math.inf to disable this feature.

  • handshake_timeout (float | None) – The time in seconds to wait for the TLS handshake to complete before aborting the connection. 60.0 seconds if None (default).

  • shutdown_timeout (float | None) – The time in seconds to wait for the SSL shutdown to complete before aborting the connection. 30.0 seconds if None (default).

  • server_side (bool | None) – Indicates whether we are a client or a server for the handshake part. If it is set to None, it is deduced according to server_hostname.

  • server_hostname (str | None) – sets or overrides the hostname that the target server’s certificate will be matched against. If server_side is True, you must pass a value for server_hostname.

  • standard_compatible (bool) – If False, skip the closing handshake when closing the connection, and don’t raise an exception if the peer does the same.

  • session (SSLSession | None) – If an SSL session already exits, use it insead.

  • selector_factory (Callable[[], selectors.BaseSelector] | None) – If given, the callable object to use to create a new selectors.BaseSelector instance.

is_closed() → bool

Checks if close() has been called.

Returns:

True if the transport is closed.

Return type:

bool

close() → None

Closes the transport.

recv_noblock(bufsize: int) → bytes

Read and return up to bufsize bytes.

Parameters:

bufsize (int) – the maximum buffer size.

Raises:
Returns:

some bytes.

If bufsize is greater than zero and an empty byte buffer is returned, this indicates an EOF.

Return type:

bytes

recv_noblock_into(buffer: bytearray | memoryview | collections.abc.Buffer) → int

Read into the given buffer.

Parameters:

buffer (bytearray | memoryview | collections.abc.Buffer) – where to write the received bytes.

Raises:
Returns:

the number of bytes written.

Returning 0 for a non-zero buffer indicates an EOF.

Return type:

int

send_noblock(data: bytes | bytearray | memoryview) → int

Send the data bytes to the remote peer.

Parameters:

data (bytes | bytearray | memoryview) – the bytes to send.

Raises:
Return type:

int

send_all_from_iterable(iterable_of_data: Iterable[bytes | bytearray | memoryview], timeout: float) → None

An efficient way to send a bunch of data via the transport.

Like send_all(), this method continues to send data from bytes until either all data has been sent or an error occurs. None is returned on success. On error, an exception is raised, and there is no way to determine how much data, if any, was successfully sent.

Parameters:
Raises:
send_eof() → None

Closes the write end of the stream after the buffered write data is flushed.

This method does nothing if the transport is closed.

property extra_attributes: Mapping[Any, Callable[[], Any]]

A mapping of the extra attributes to callables that return the corresponding values.

If the provider wraps another provider, the attributes from that wrapper should also be included in the returned mapping (but the wrapper may override the callables from the wrapped instance).

The callables should raise TypedAttributeLookupError if it is not possible to get the value.

class easynetwork.lowlevel.api_sync.transports.socket.SocketDatagramTransport

Bases: SelectorDatagramTransport

A datagram transport implementation which wraps a datagram socket.

__init__(sock: socket, retry_interval: float, *, max_datagram_size: int = constants.MAX_DATAGRAM_BUFSIZE, selector_factory: Callable[[], BaseSelector] | None = None) → None
Parameters:

  • sock (socket) – The SOCK_DGRAM socket to wrap.

  • retry_interval (float) – The maximum wait time to wait for a blocking operation before retrying. Set it to math.inf to disable this feature.

  • max_datagram_size (int) – The maximum packet size supported by recvfrom(2) for the current socket.

  • selector_factory (Callable[[], BaseSelector] | None) – If given, the callable object to use to create a new selectors.BaseSelector instance.

is_closed() → bool

Checks if close() has been called.

Returns:

True if the transport is closed.

Return type:

bool

close() → None

Closes the transport.

recv_noblock() → bytes

Read and return the next available packet.

Raises:
Returns:

some bytes.

Return type:

bytes

send_noblock(data: bytes | bytearray | memoryview) → None

Send the data bytes to the remote peer.

Parameters:

data (bytes | bytearray | memoryview) – the bytes to send.

Raises:
property extra_attributes: Mapping[Any, Callable[[], Any]]

A mapping of the extra attributes to callables that return the corresponding values.

If the provider wraps another provider, the attributes from that wrapper should also be included in the returned mapping (but the wrapper may override the callables from the wrapped instance).

The callables should raise TypedAttributeLookupError if it is not possible to get the value.

class easynetwork.lowlevel.api_sync.transports.socket.SocketStreamTransport

Bases: SelectorStreamTransport

A stream data transport implementation which wraps a stream socket.

__init__(sock: socket, retry_interval: float, *, selector_factory: Callable[[], BaseSelector] | None = None) → None
Parameters:
is_closed() → bool

Checks if close() has been called.

Returns:

True if the transport is closed.

Return type:

bool

close() → None

Closes the transport.

recv_noblock(bufsize: int) → bytes

Read and return up to bufsize bytes.

Parameters:

bufsize (int) – the maximum buffer size.

Raises:
Returns:

some bytes.

If bufsize is greater than zero and an empty byte buffer is returned, this indicates an EOF.

Return type:

bytes

recv_noblock_into(buffer: bytearray | memoryview | collections.abc.Buffer) → int

Read into the given buffer.

Parameters:

buffer (bytearray | memoryview | collections.abc.Buffer) – where to write the received bytes.

Raises:
Returns:

the number of bytes written.

Returning 0 for a non-zero buffer indicates an EOF.

Return type:

int

send_noblock(data: bytes | bytearray | memoryview) → int

Send the data bytes to the remote peer.

Parameters:

data (bytes | bytearray | memoryview) – the bytes to send.

Raises:
Return type:

int

send_all_from_iterable(iterable_of_data: Iterable[bytes | bytearray | memoryview], timeout: float) → None

An efficient way to send a bunch of data via the transport.

Like send_all(), this method continues to send data from bytes until either all data has been sent or an error occurs. None is returned on success. On error, an exception is raised, and there is no way to determine how much data, if any, was successfully sent.

Parameters:
Raises:
send_eof() → None

Closes the write end of the stream after the buffered write data is flushed.

This method does nothing if the transport is closed.

property extra_attributes: Mapping[Any, Callable[[], Any]]

A mapping of the extra attributes to callables that return the corresponding values.

If the provider wraps another provider, the attributes from that wrapper should also be included in the returned mapping (but the wrapper may override the callables from the wrapped instance).

The callables should raise TypedAttributeLookupError if it is not possible to get the value.