Generic Endpoints

Low-level asynchronous endpoints module.

---

Stream Endpoints

Low-level asynchronous endpoints module for connection-oriented communication.

class easynetwork.lowlevel.api_async.endpoints.stream.AsyncStreamEndpoint

Bases: AsyncBaseTransport, Generic[_T_SentPacket, _T_ReceivedPacket]

A full-duplex communication endpoint based on continuous stream data transport.

__init__(transport: AsyncStreamTransport, protocol: StreamProtocol[_T_SentPacket, _T_ReceivedPacket] | BufferedStreamProtocol[_T_SentPacket, _T_ReceivedPacket, Any], max_recv_size: int) → None

Parameters:

• transport (AsyncStreamTransport) – The data transport to use.

• protocol (StreamProtocol[_T_SentPacket, _T_ReceivedPacket] | BufferedStreamProtocol[_T_SentPacket, _T_ReceivedPacket, Any]) – The protocol object to use.

• max_recv_size (int) – Read buffer size.

is_closing() → bool

Checks if the endpoint is closed or in the process of being closed.

Returns:

True if the endpoint is closed.

Return type:

bool

async aclose() → None

Closes the endpoint.

Warning

aclose() performs a graceful close, waiting for the transport to close.

If aclose() is cancelled, the transport is closed abruptly.

async send_packet(packet: _T_SentPacket) → None

Sends packet to the remote endpoint.

Warning

In the case of a cancellation, it is impossible to know if all the packet data has been sent. This would leave the connection in an inconsistent state.

Parameters:

packet (_T_SentPacket) – the Python object to send.

Raises:

RuntimeError – send_eof() has been called earlier.

async send_packet_with_ancillary(packet: _T_SentPacket, ancillary_data: Any) → None

Sends packet to the remote endpoint with ancillary data.

Added in version 1.2.

Parameters:

• packet (_T_SentPacket) – the Python object to send.

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

Raises:

• RuntimeError – send_eof() has been called earlier.

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

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

async send_eof() → None

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

This method does nothing if the endpoint is closed.

Can be safely called multiple times.

async recv_packet() → _T_ReceivedPacket

Waits for a new packet to arrive from the remote endpoint.

Raises:

• ConnectionAbortedError – the read end of the stream is closed.

• StreamProtocolParseError – invalid data received.

Returns:

the received packet.

Return type:

_T_ReceivedPacket

async recv_packet_with_ancillary(ancillary_bufsize: int, ancillary_data_received: Callable[[Any], object]) → _T_ReceivedPacket

Waits for a new packet with ancillary data to arrive from the remote endpoint.

Added in version 1.2.

Parameters:

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

• ancillary_data_received (Callable[[Any], object]) – Action to perform on ancillary data reception.

Raises:

• ConnectionAbortedError – the read end of the stream is closed.

• EOFError – could not deserialize packet because of partial chunk reception.

• StreamProtocolParseError – invalid data received.

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

Returns:

the received packet.

Return type:

_T_ReceivedPacket

backend() → AsyncBackend

Returns:

The backend implementation linked to this transport.

Return type:

AsyncBackend

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_async.endpoints.stream.AsyncStreamReceiverEndpoint

Bases: AsyncBaseTransport, Generic[_T_ReceivedPacket]

A read-only communication endpoint based on continuous stream data transport.

__init__(transport: AsyncStreamReadTransport, protocol: StreamProtocol[Any, _T_ReceivedPacket] | BufferedStreamProtocol[Any, _T_ReceivedPacket, Any], max_recv_size: int) → None

Parameters:

• transport (AsyncStreamReadTransport) – The data transport to use.

• protocol (StreamProtocol[Any, _T_ReceivedPacket] | BufferedStreamProtocol[Any, _T_ReceivedPacket, Any]) – The protocol object to use.

• max_recv_size (int) – Read buffer size.

is_closing() → bool

Checks if the endpoint is closed or in the process of being closed.

Returns:

True if the endpoint is closed.

Return type:

bool

async aclose() → None

Closes the endpoint.

Warning

aclose() performs a graceful close, waiting for the transport to close.

If aclose() is cancelled, the transport is closed abruptly.

async recv_packet() → _T_ReceivedPacket

Waits for a new packet to arrive from the remote endpoint.

Raises:

• ConnectionAbortedError – the read end of the stream is closed.

• StreamProtocolParseError – invalid data received.

Returns:

the received packet.

Return type:

_T_ReceivedPacket

async recv_packet_with_ancillary(ancillary_bufsize: int, ancillary_data_received: Callable[[Any], object]) → _T_ReceivedPacket

Waits for a new packet with ancillary data to arrive from the remote endpoint.

Added in version 1.2.

Parameters:

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

• ancillary_data_received (Callable[[Any], object]) – Action to perform on ancillary data reception.

Raises:

• ConnectionAbortedError – the read end of the stream is closed.

• EOFError – could not deserialize packet because of partial chunk reception.

• StreamProtocolParseError – invalid data received.

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

Returns:

the received packet.

Return type:

_T_ReceivedPacket

backend() → AsyncBackend

Returns:

The backend implementation linked to this transport.

Return type:

AsyncBackend

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_async.endpoints.stream.AsyncStreamSenderEndpoint

Bases: AsyncBaseTransport, Generic[_T_SentPacket]

A write-only communication endpoint based on continuous stream data transport.

__init__(transport: AsyncStreamWriteTransport, protocol: StreamProtocol[_T_SentPacket, Any] | BufferedStreamProtocol[_T_SentPacket, Any, Any]) → None

Parameters:

• transport (AsyncStreamWriteTransport) – The data transport to use.

• protocol (StreamProtocol[_T_SentPacket, Any] | BufferedStreamProtocol[_T_SentPacket, Any, Any]) – The protocol object to use.

is_closing() → bool

Checks if the endpoint is closed or in the process of being closed.

Returns:

True if the endpoint is closed.

Return type:

bool

async aclose() → None

Closes the endpoint.

Warning

aclose() performs a graceful close, waiting for the transport to close.

If aclose() is cancelled, the transport is closed abruptly.

async send_packet(packet: _T_SentPacket) → None

Sends packet to the remote endpoint.

Warning

In the case of a cancellation, it is impossible to know if all the packet data has been sent. This would leave the connection in an inconsistent state.

Parameters:

packet (_T_SentPacket) – the Python object to send.

async send_packet_with_ancillary(packet: _T_SentPacket, ancillary_data: Any) → None

Sends packet to the remote endpoint with ancillary data.

Added in version 1.2.

Parameters:

• packet (_T_SentPacket) – the Python object to send.

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

Raises:

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

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

backend() → AsyncBackend

Returns:

The backend implementation linked to this transport.

Return type:

AsyncBackend

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.

Datagram Endpoints

Low-level asynchronous endpoints module for datagram-based communication.

class easynetwork.lowlevel.api_async.endpoints.datagram.AsyncDatagramEndpoint

Bases: AsyncBaseTransport, Generic[_T_SentPacket, _T_ReceivedPacket]

A full-duplex communication endpoint based on unreliable packets of data.

__init__(transport: AsyncDatagramTransport, protocol: DatagramProtocol[_T_SentPacket, _T_ReceivedPacket]) → None

Parameters:

• transport (AsyncDatagramTransport) – The data transport to use.

• protocol (DatagramProtocol[_T_SentPacket, _T_ReceivedPacket]) – The protocol object to use.

is_closing() → bool

Checks if the endpoint is closed or in the process of being closed.

Returns:

True if the endpoint is closed.

Return type:

bool

async aclose() → None

Closes the endpoint.

async send_packet(packet: _T_SentPacket) → None

Sends packet to the remote endpoint.

Warning

In the case of a cancellation, it is impossible to know if all the packet data has been sent.

Parameters:

packet (_T_SentPacket) – the Python object to send.

Raises:

OSError – Data too big to be sent at once.

async send_packet_with_ancillary(packet: _T_SentPacket, ancillary_data: Any) → None

Sends packet to the remote endpoint with ancillary data.

Added in version 1.2.

Parameters:

• packet (_T_SentPacket) – the Python object to send.

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

Raises:

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

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

async recv_packet() → _T_ReceivedPacket

Waits for a new packet from the remote endpoint.

Raises:

DatagramProtocolParseError – invalid data received.

Returns:

the received packet.

Return type:

_T_ReceivedPacket

async recv_packet_with_ancillary(ancillary_bufsize: int, ancillary_data_received: Callable[[Any], object]) → _T_ReceivedPacket

Waits for a new packet with ancillary data to arrive from the remote endpoint.

Added in version 1.2.

Parameters:

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

• ancillary_data_received (Callable[[Any], object]) – Action to perform on ancillary data reception.

Raises:

• DatagramProtocolParseError – invalid data received.

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

Returns:

the received packet.

Return type:

_T_ReceivedPacket

backend() → AsyncBackend

Returns:

The backend implementation linked to this transport.

Return type:

AsyncBackend

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_async.endpoints.datagram.AsyncDatagramReceiverEndpoint

Bases: AsyncBaseTransport, Generic[_T_ReceivedPacket]

A read-only communication endpoint based on unreliable packets of data.

__init__(transport: AsyncDatagramReadTransport, protocol: DatagramProtocol[Any, _T_ReceivedPacket]) → None

Parameters:

• transport (AsyncDatagramReadTransport) – The data transport to use.

• protocol (DatagramProtocol[Any, _T_ReceivedPacket]) – The protocol object to use.

is_closing() → bool

Checks if the endpoint is closed or in the process of being closed.

Returns:

True if the endpoint is closed.

Return type:

bool

async aclose() → None

Closes the endpoint.

async recv_packet() → _T_ReceivedPacket

Waits for a new packet from the remote endpoint.

Raises:

DatagramProtocolParseError – invalid data received.

Returns:

the received packet.

Return type:

_T_ReceivedPacket

async recv_packet_with_ancillary(ancillary_bufsize: int, ancillary_data_received: Callable[[Any], object]) → _T_ReceivedPacket

Waits for a new packet with ancillary data to arrive from the remote endpoint.

Added in version 1.2.

Parameters:

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

• ancillary_data_received (Callable[[Any], object]) – Action to perform on ancillary data reception.

Raises:

• DatagramProtocolParseError – invalid data received.

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

Returns:

the received packet.

Return type:

_T_ReceivedPacket

backend() → AsyncBackend

Returns:

The backend implementation linked to this transport.

Return type:

AsyncBackend

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_async.endpoints.datagram.AsyncDatagramSenderEndpoint

Bases: AsyncBaseTransport, Generic[_T_SentPacket]

A write-only communication endpoint based on unreliable packets of data.

__init__(transport: AsyncDatagramWriteTransport, protocol: DatagramProtocol[_T_SentPacket, Any]) → None

Parameters:

• transport (AsyncDatagramWriteTransport) – The data transport to use.

• protocol (DatagramProtocol[_T_SentPacket, Any]) – The protocol object to use.

is_closing() → bool

Checks if the endpoint is closed or in the process of being closed.

Returns:

True if the endpoint is closed.

Return type:

bool

async aclose() → None

Closes the endpoint.

async send_packet(packet: _T_SentPacket) → None

Sends packet to the remote endpoint.

Warning

In the case of a cancellation, it is impossible to know if all the packet data has been sent.

Parameters:

packet (_T_SentPacket) – the Python object to send.

Raises:

OSError – Data too big to be sent at once.

async send_packet_with_ancillary(packet: _T_SentPacket, ancillary_data: Any) → None

Sends packet to the remote endpoint with ancillary data.

Added in version 1.2.

Parameters:

• packet (_T_SentPacket) – the Python object to send.

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

Raises:

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

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

backend() → AsyncBackend

Returns:

The backend implementation linked to this transport.

Return type:

AsyncBackend

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.