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:

• ValueError – Negative timeout.

• TimeoutError – Operation timed out.

Returns:

some bytes.

Return type:

bytes

recv_with_ancillary(ancillary_bufsize: int, timeout: float) → tuple[bytes, Any]

Read and return the next available packet with ancillary data.

Added in version 1.2.

Parameters:

• ancillary_bufsize (int) – the maximum buffer size for ancillary data.

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

Raises:

• ValueError – Negative ancillary_bufsize.

• ValueError – Negative timeout.

• TimeoutError – Operation timed out.

• UnsupportedOperation – This transport does not have ancillary data support.

Returns:

a tuple with some bytes and the ancillary data.

Return type:

tuple[bytes, Any]

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:

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

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

Raises:

• ValueError – Negative timeout.

• TimeoutError – Operation timed out.

• OSError – Data too big to be sent at once.

send_with_ancillary(data: bytes | bytearray | memoryview, ancillary_data: Any, timeout: float) → None

Send the data bytes to the remote peer with ancillary data.

Added in version 1.2.

Parameters:

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

• ancillary_data (Any) – The ancillary data to send along with the message.

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

Raises:

• ValueError – Negative timeout.

• TimeoutError – Operation timed out.

• OSError – Data too big to be sent at once.

• UnsupportedOperation – This transport does not have ancillary data support.

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:

• ValueError – Negative bufsize.

• ValueError – Negative timeout.

• TimeoutError – Operation timed out.

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:

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

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

Raises:

• ValueError – Negative timeout.

• TimeoutError – Operation timed out.

Returns:

the number of bytes written.

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

Return type:

int

recv_with_ancillary(bufsize: int, ancillary_bufsize: int, timeout: float) → tuple[bytes, Any]

Read and return up to bufsize bytes with ancillary data.

Added in version 1.2.

Parameters:

• bufsize (int) – the maximum buffer size.

• ancillary_bufsize (int) – the maximum buffer size for ancillary data.

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

Raises:

• ValueError – Negative bufsize.

• ValueError – Negative ancillary_bufsize.

• ValueError – Negative timeout.

• TimeoutError – Operation timed out.

• UnsupportedOperation – This transport does not have ancillary data support.

Returns:

a tuple with some bytes and the ancillary data.

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

Return type:

tuple[bytes, Any]

recv_with_ancillary_into(buffer: bytearray | memoryview | collections.abc.Buffer, ancillary_bufsize: int, timeout: float) → tuple[int, Any]

Read into the given buffer with ancillary data.

Added in version 1.2.

Parameters:

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

• ancillary_bufsize (int) – the maximum buffer size for ancillary data.

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

Raises:

• ValueError – Negative ancillary_bufsize.

• ValueError – Negative timeout.

• TimeoutError – Operation timed out.

• UnsupportedOperation – This transport does not have ancillary data support.

Returns:

a tuple with the number of bytes written and the ancillary data.

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

Return type:

tuple[int, Any]

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:

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

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

Raises:

• ValueError – Negative timeout.

• TimeoutError – Operation timed out.

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:

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

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

Raises:

• ValueError – Negative timeout.

• TimeoutError – Operation timed out.

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:

• iterable_of_data (Iterable[bytes | bytearray | memoryview]) – An iterable yielding the bytes to send.

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

Raises:

• ValueError – Negative timeout.

• TimeoutError – Operation timed out.

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

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

Unlike send_all() and send_all_from_iterable(), this method tries to send all data at once. If not all could be sent, an exception is raised. 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.

Added in version 1.2.

Parameters:

• iterable_of_data (Iterable[bytes | bytearray | memoryview]) – An iterable yielding the bytes to send.

• ancillary_data (Any) – The ancillary data to send along with the message.

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

Raises:

• ValueError – Negative timeout.

• TimeoutError – Operation timed out.

• OSError – Data too big to be sent at once.

• UnsupportedOperation – This transport does not have ancillary data support.

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_interval (float) – The maximum wait time to wait for a blocking operation before retrying. Set it to math.inf to disable this feature.

• selector_factory (Callable[[], BaseSelector] | None) –

  If given, the callable object to use to create a new selectors.BaseSelector instance. Otherwise, the selector used by default is:

  • selectors.PollSelector on Unix platforms.

  • selectors.SelectSelector on Windows.

_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:

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

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

recv_noblock_with_ancillary(ancillary_bufsize: int) → tuple[bytes, Any]

Read and return the next available packet with ancillary data.

Added in version 1.2.

Parameters:

ancillary_bufsize (int) – the maximum buffer size for ancillary data.

Raises:

• ValueError – Negative ancillary_bufsize.

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

• UnsupportedOperation – This transport does not have ancillary data support.

Returns:

a tuple with some bytes and the ancillary data.

Return type:

tuple[bytes, Any]

recv_with_ancillary(ancillary_bufsize: int, timeout: float) → tuple[bytes, Any]

Read and return the next available packet with ancillary data.

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

Added in version 1.2.

Return type:

tuple[bytes, Any]

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:

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

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.

send_noblock_with_ancillary(data: bytes | bytearray | memoryview, ancillary_data: Any) → None

Send the data bytes with ancillary data to the remote peer.

Added in version 1.2.

Parameters:

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

• ancillary_data (Any) – The ancillary data to send along with the message.

Raises:

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

• UnsupportedOperation – This transport does not have ancillary data support.

send_with_ancillary(data: bytes | bytearray | memoryview, ancillary_data: Any, timeout: float) → None

Send the data bytes with ancillary data to the remote peer.

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

Added in version 1.2.

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:

• ValueError – Negative bufsize.

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

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:

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

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

recv_noblock_with_ancillary(bufsize: int, ancillary_bufsize: int) → tuple[bytes, Any]

Read and return up to bufsize bytes with ancillary data.

Added in version 1.2.

Parameters:

• bufsize (int) – the maximum buffer size.

• ancillary_bufsize (int) – the maximum buffer size for ancillary data.

Raises:

• ValueError – Negative bufsize.

• ValueError – Negative ancillary_bufsize.

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

• UnsupportedOperation – This transport does not have ancillary data support.

Returns:

a tuple with some bytes and the ancillary data.

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

Return type:

tuple[bytes, Any]

recv_with_ancillary(bufsize: int, ancillary_bufsize: int, timeout: float) → tuple[bytes, Any]

Read and return up to bufsize bytes with ancillary data.

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

Added in version 1.2.

Return type:

tuple[bytes, Any]

recv_noblock_with_ancillary_into(buffer: bytearray | memoryview | collections.abc.Buffer, ancillary_bufsize: int) → tuple[int, Any]

Read into the given buffer with ancillary data.

Added in version 1.2.

Parameters:

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

• ancillary_bufsize (int) – the maximum buffer size for ancillary data.

Raises:

• ValueError – Negative ancillary_bufsize.

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

• UnsupportedOperation – This transport does not have ancillary data support.

Returns:

a tuple with the number of bytes written and the ancillary data.

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

Return type:

tuple[int, Any]

recv_with_ancillary_into(buffer: bytearray | memoryview | collections.abc.Buffer, ancillary_bufsize: int, timeout: float) → tuple[int, Any]

Read into the given buffer with ancillary data.

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

Added in version 1.2.

Return type:

tuple[int, Any]

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:

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

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

send_all_noblock_with_ancillary(iterable_of_data: Iterable[bytes | bytearray | memoryview], ancillary_data: Any) → None

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

Added in version 1.2.

Parameters:

• iterable_of_data (Iterable[bytes | bytearray | memoryview]) – An iterable yielding the bytes to send.

• ancillary_data (Any) – The ancillary data to send along with the message.

Raises:

• OSError – Data too big to be sent at once.

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

• UnsupportedOperation – This transport does not have ancillary data support.

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

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

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

Added in version 1.2.

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

recv_with_ancillary(ancillary_bufsize: int, timeout: float) → tuple[bytes, Any]

Calls self.receive_transport.recv_with_ancillary().

Added in version 1.2.

Return type:

tuple[bytes, Any]

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

Calls self.send_transport.send().

send_with_ancillary(data: bytes | bytearray | memoryview, ancillary_data: Any, timeout: float) → None

Calls self.send_transport.send_with_ancillary().

Added in version 1.2.

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

recv_with_ancillary(bufsize: int, ancillary_bufsize: int, timeout: float) → tuple[bytes, Any]

Calls self.receive_transport.recv_with_ancillary().

Added in version 1.2.

Return type:

tuple[bytes, Any]

recv_with_ancillary_into(buffer: bytearray | memoryview | collections.abc.Buffer, ancillary_bufsize: int, timeout: float) → tuple[int, Any]

Calls self.receive_transport.recv_with_ancillary_into().

Added in version 1.2.

Return type:

tuple[int, Any]

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_all_with_ancillary(iterable_of_data: Iterable[bytes | bytearray | memoryview], ancillary_data: Any, timeout: float) → None

Calls self.send_transport.send_all_with_ancillary().

Added in version 1.2.

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:

• ValueError – Negative bufsize.

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

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:

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

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:

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

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:

• iterable_of_data (Iterable[bytes | bytearray | memoryview]) – An iterable yielding the bytes to send.

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

Raises:

• ValueError – Negative timeout.

• TimeoutError – Operation timed out.

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:

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

Returns:

some bytes.

Return type:

bytes

recv_noblock_with_ancillary(ancillary_bufsize: int) → tuple[bytes, list[tuple[int, int, bytes]]]

Read and return the next available packet with ancillary data.

Added in version 1.2.

Parameters:

ancillary_bufsize (int) – the maximum buffer size for ancillary data.

Raises:

• ValueError – Negative ancillary_bufsize.

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

• UnsupportedOperation – This transport does not have ancillary data support.

Returns:

a tuple with some bytes and the ancillary data.

Return type:

tuple[bytes, list[tuple[int, int, 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:

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

send_noblock_with_ancillary(data: bytes | bytearray | memoryview, ancillary_data: Iterable[tuple[int, int, TypeAliasForwardRef('bytes | bytearray | memoryview | collections.abc.Buffer')]]) → None

Send the data bytes with ancillary data to the remote peer.

Added in version 1.2.

Parameters:

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

• ancillary_data (Iterable[tuple[int, int, TypeAliasForwardRef('bytes | bytearray | memoryview | collections.abc.Buffer')]]) – The ancillary data to send along with the message.

Raises:

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

• UnsupportedOperation – This transport does not have ancillary data support.

send_with_ancillary(data: bytes | bytearray | memoryview, ancillary_data: Iterable[tuple[int, int, TypeAliasForwardRef('bytes | bytearray | memoryview | collections.abc.Buffer')]], timeout: float) → None

Send the data bytes with ancillary data to the remote peer.

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

Added in version 1.2.

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:

• sock (socket) – The SOCK_STREAM 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.

• 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(bufsize: int) → bytes

Read and return up to bufsize bytes.

Parameters:

bufsize (int) – the maximum buffer size.

Raises:

• ValueError – Negative bufsize.

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

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:

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

Returns:

the number of bytes written.

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

Return type:

int

recv_noblock_with_ancillary(bufsize: int, ancillary_bufsize: int) → tuple[bytes, list[tuple[int, int, bytes]]]

Read and return up to bufsize bytes with ancillary data.

Added in version 1.2.

Parameters:

• bufsize (int) – the maximum buffer size.

• ancillary_bufsize (int) – the maximum buffer size for ancillary data.

Raises:

• ValueError – Negative bufsize.

• ValueError – Negative ancillary_bufsize.

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

• UnsupportedOperation – This transport does not have ancillary data support.

Returns:

a tuple with some bytes and the ancillary data.

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

Return type:

tuple[bytes, list[tuple[int, int, bytes]]]

recv_noblock_with_ancillary_into(buffer: bytearray | memoryview | collections.abc.Buffer, ancillary_bufsize: int) → tuple[int, list[tuple[int, int, bytes]]]

Read into the given buffer with ancillary data.

Added in version 1.2.

Parameters:

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

• ancillary_bufsize (int) – the maximum buffer size for ancillary data.

Raises:

• ValueError – Negative ancillary_bufsize.

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

• UnsupportedOperation – This transport does not have ancillary data support.

Returns:

a tuple with the number of bytes written and the ancillary data.

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

Return type:

tuple[int, list[tuple[int, int, bytes]]]

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:

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

Return type:

int

send_all_noblock_with_ancillary(iterable_of_data: Iterable[bytes | bytearray | memoryview], ancillary_data: Iterable[tuple[int, int, TypeAliasForwardRef('bytes | bytearray | memoryview | collections.abc.Buffer')]]) → None

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

Added in version 1.2.

Parameters:

• iterable_of_data (Iterable[bytes | bytearray | memoryview]) – An iterable yielding the bytes to send.

• ancillary_data (Iterable[tuple[int, int, TypeAliasForwardRef('bytes | bytearray | memoryview | collections.abc.Buffer')]]) – The ancillary data to send along with the message.

Raises:

• OSError – Data too big to be sent at once.

• WouldBlockOnRead – the operation would block when reading the pipe.

• WouldBlockOnWrite – the operation would block when writing on the pipe.

• UnsupportedOperation – This transport does not have ancillary data support.

send_all_with_ancillary(iterable_of_data: Iterable[bytes | bytearray | memoryview], ancillary_data: Iterable[tuple[int, int, TypeAliasForwardRef('bytes | bytearray | memoryview | collections.abc.Buffer')]], timeout: float) → None

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

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

Added in version 1.2.

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:

• iterable_of_data (Iterable[bytes | bytearray | memoryview]) – An iterable yielding the bytes to send.

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

Raises:

• ValueError – Negative timeout.

• TimeoutError – Operation timed out.

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.