communication.communicators.communicator module

This module contains the abstract classes for Communicators and Clients.

class communication.communicators.communicator.Communicator

Bases: Generic[Connection], ABC

An abstract interface for sending and receiving packets of bytes to registered connections.

A Communicator has “connections” which describe how to reach a specific endpoint. These connections are added through Communicator.add_connection. Each connection has a unique name, which is used to address the connection when sending packets to it, or to identify the connection when receiving packets from it.

To be able to receive packets from connections through the Communicator, one must register a receive_handler using Communicator.register_receive_handler. This receive_handler is called for each packet that is received.

__init__()

Initializer for the Communicator.

add_connection(name, connection)

Register a new connection to the communicator.

By registering a connection to the communicator, the communicator can send and receive messages through the connection. Each connection needs to be identified by a unique name.

Parameters:

• name (str) – The name of the connection to register.

• connection (TypeVar(Connection)) – The connection to register.

Raises:

• IllegalStateAction – If the state is not INITIALIZED

• KeyError – If a connection with the given name already exists.

Return type:

None

async initialize()

Initialize and start the Communicator.

Functionality depends on implementation, but often some (asynchronous) setup steps are required to setup the connections.

Raises:

IllegalStateAction – If the state is not UNINITIALIZED.

Return type:

None

property receive_handler: Callable[[str, bytes], Awaitable[None]]

The handler to be called upon receiving a new packet.

Raises:

AttributeError – If no receive_handler is set.

Returns:

A handler function which accepts packets.

async send(recipient, packet)

Send a message packet to the recipient.

Parameters:

• recipient (str) – The intended recipient of the message.

• packet (bytes) – The message to send to the recipient.

Raises:

• IllegalStateAction – If the state is not STARTED.

• KeyError – If no connection is registered with the given name.

Return type:

None

set_receive_handler(receive_handler)

Register the receive_handler to be called upon receiving a message.

Parameters:

receive_handler (Callable[[str, bytes], Awaitable[None]])

Return type:

None

async shutdown()

Shutdown the communicator.

Raises:

IllegalStateAction – If the state is not STARTED

Return type:

None

class communication.communicators.communicator.CommunicatorState(*values)

Bases: IntEnum

The states in the lifecycle of a Communicator.

Upon construction, the Communicator is in the UNINITIALIZED state. To start the Communicator, Communicator.initialize must be called, transitioning the Communicator to the STARTED state. To stop the Communicator, Communicator.shutdown must be called, transitioning the Communicator to the STOPPED state.

STARTED = 2

STOPPED = 3

UNINITIALIZED = 1

exception communication.communicators.communicator.IllegalStateAction(action, curr_state)

Bases: Exception

Exception class for when an action is performed that is illegal in the current state.