Generic Endpoints

Low-level endpoints module.

---

Stream Endpoints

Low-level endpoints module for connection-oriented communication.

class easynetwork.lowlevel.api_sync.endpoints.stream.StreamEndpoint

Bases: BaseTransport, Generic[_T_SentPacket, _T_ReceivedPacket]

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

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

Parameters:

• transport (StreamTransport) – 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_closed() → bool

Checks if close() has been called.

Returns:

True if the endpoint is closed.

Return type:

bool

close() → None

Closes the endpoint.

send_packet(packet: _T_SentPacket, *, timeout: float | None = None) → None

Sends packet to the remote endpoint.

If timeout is not None, the entire send operation will take at most timeout seconds.

Warning

A timeout on a send operation is unusual unless you have a SSL/TLS context.

In the case of a timeout, 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.

• timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

• TimeoutError – the send operation does not end up after timeout seconds.

• RuntimeError – send_eof() has been called earlier.

send_packet_with_ancillary(packet: _T_SentPacket, ancillary_data: Any, *, timeout: float | None = None) → None

Sends packet to the remote endpoint with ancillary data.

If timeout is not None, the entire send operation will take at most timeout seconds.

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.

• timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

• TimeoutError – the send operation does not end up after timeout seconds.

• 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.

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.

recv_packet(*, timeout: float | None = None) → _T_ReceivedPacket

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

If timeout is not None, the entire receive operation will take at most timeout seconds.

Parameters:

timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

• TimeoutError – the receive operation does not end up after timeout seconds.

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

• StreamProtocolParseError – invalid data received.

Returns:

the received packet.

Return type:

_T_ReceivedPacket

recv_packet_with_ancillary(ancillary_bufsize: int, ancillary_data_received: Callable[[Any], object], *, timeout: float | None = None) → _T_ReceivedPacket

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

If timeout is not None, the entire receive operation will take at most timeout seconds.

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.

• timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

• TimeoutError – the receive operation does not end up after timeout seconds.

• 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

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.endpoints.stream.StreamReceiverEndpoint

Bases: BaseTransport, Generic[_T_ReceivedPacket]

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

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

Parameters:

• transport (StreamReadTransport) – 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_closed() → bool

Checks if close() has been called.

Returns:

True if the endpoint is closed.

Return type:

bool

close() → None

Closes the endpoint.

recv_packet(*, timeout: float | None = None) → _T_ReceivedPacket

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

If timeout is not None, the entire receive operation will take at most timeout seconds.

Parameters:

timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

• TimeoutError – the receive operation does not end up after timeout seconds.

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

• StreamProtocolParseError – invalid data received.

Returns:

the received packet.

Return type:

_T_ReceivedPacket

recv_packet_with_ancillary(ancillary_bufsize: int, ancillary_data_received: Callable[[Any], object], *, timeout: float | None = None) → _T_ReceivedPacket

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

If timeout is not None, the entire receive operation will take at most timeout seconds.

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.

• timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

• TimeoutError – the receive operation does not end up after timeout seconds.

• 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

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.endpoints.stream.StreamSenderEndpoint

Bases: BaseTransport, Generic[_T_SentPacket]

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

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

Parameters:

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

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

is_closed() → bool

Checks if close() has been called.

Returns:

True if the endpoint is closed.

Return type:

bool

close() → None

Closes the endpoint.

send_packet(packet: _T_SentPacket, *, timeout: float | None = None) → None

Sends packet to the remote endpoint.

If timeout is not None, the entire send operation will take at most timeout seconds.

Warning

A timeout on a send operation is unusual unless you have a SSL/TLS context.

In the case of a timeout, 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.

• timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

TimeoutError – the send operation does not end up after timeout seconds.

send_packet_with_ancillary(packet: _T_SentPacket, ancillary_data: Any, *, timeout: float | None = None) → None

Sends packet to the remote endpoint with ancillary data.

If timeout is not None, the entire send operation will take at most timeout seconds.

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.

• timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

• TimeoutError – the send operation does not end up after timeout seconds.

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

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

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 endpoints module for datagram-based communication.

class easynetwork.lowlevel.api_sync.endpoints.datagram.DatagramEndpoint

Bases: BaseTransport, Generic[_T_SentPacket, _T_ReceivedPacket]

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

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

Parameters:

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

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

is_closed() → bool

Checks if close() has been called.

Returns:

True if the endpoint is closed.

Return type:

bool

close() → None

Closes the endpoint.

send_packet(packet: _T_SentPacket, *, timeout: float | None = None) → None

Sends packet to the remote endpoint.

If timeout is not None, the entire send operation will take at most timeout seconds.

Warning

A timeout on a send operation is unusual.

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

Parameters:

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

• timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

• TimeoutError – the send operation does not end up after timeout seconds.

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

send_packet_with_ancillary(packet: _T_SentPacket, ancillary_data: Any, *, timeout: float | None = None) → None

Sends packet to the remote endpoint with ancillary data.

If timeout is not None, the entire send operation will take at most timeout seconds.

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.

• timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

• TimeoutError – the send operation does not end up after timeout seconds.

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

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

recv_packet(*, timeout: float | None = None) → _T_ReceivedPacket

Waits for a new packet from the remote endpoint.

If timeout is not None, the entire receive operation will take at most timeout seconds.

Parameters:

timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

• TimeoutError – the receive operation does not end up after timeout seconds.

• DatagramProtocolParseError – invalid data received.

Returns:

the received packet.

Return type:

_T_ReceivedPacket

recv_packet_with_ancillary(ancillary_bufsize: int, ancillary_data_received: Callable[[Any], object], *, timeout: float | None = None) → _T_ReceivedPacket

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

If timeout is not None, the entire receive operation will take at most timeout seconds.

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.

• timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

• TimeoutError – the receive operation does not end up after timeout seconds.

• DatagramProtocolParseError – invalid data received.

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

Returns:

the received packet.

Return type:

_T_ReceivedPacket

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.endpoints.datagram.DatagramReceiverEndpoint

Bases: BaseTransport, Generic[_T_ReceivedPacket]

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

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

Parameters:

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

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

is_closed() → bool

Checks if close() has been called.

Returns:

True if the endpoint is closed.

Return type:

bool

close() → None

Closes the endpoint.

recv_packet(*, timeout: float | None = None) → _T_ReceivedPacket

Waits for a new packet from the remote endpoint.

If timeout is not None, the entire receive operation will take at most timeout seconds.

Parameters:

timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

• TimeoutError – the receive operation does not end up after timeout seconds.

• DatagramProtocolParseError – invalid data received.

Returns:

the received packet.

Return type:

_T_ReceivedPacket

recv_packet_with_ancillary(ancillary_bufsize: int, ancillary_data_received: Callable[[Any], object], *, timeout: float | None = None) → _T_ReceivedPacket

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

If timeout is not None, the entire receive operation will take at most timeout seconds.

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.

• timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

• TimeoutError – the receive operation does not end up after timeout seconds.

• DatagramProtocolParseError – invalid data received.

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

Returns:

the received packet.

Return type:

_T_ReceivedPacket

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.endpoints.datagram.DatagramSenderEndpoint

Bases: BaseTransport, Generic[_T_SentPacket]

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

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

Parameters:

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

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

is_closed() → bool

Checks if close() has been called.

Returns:

True if the endpoint is closed.

Return type:

bool

close() → None

Closes the endpoint.

send_packet(packet: _T_SentPacket, *, timeout: float | None = None) → None

Sends packet to the remote endpoint.

If timeout is not None, the entire send operation will take at most timeout seconds.

Warning

A timeout on a send operation is unusual.

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

Parameters:

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

• timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

• TimeoutError – the send operation does not end up after timeout seconds.

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

send_packet_with_ancillary(packet: _T_SentPacket, ancillary_data: Any, *, timeout: float | None = None) → None

Sends packet to the remote endpoint with ancillary data.

If timeout is not None, the entire send operation will take at most timeout seconds.

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.

• timeout (float | None) – the allowed time (in seconds) for blocking operations.

Raises:

• TimeoutError – the send operation does not end up after timeout seconds.

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

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

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.