abstract¶

Interface specification for publishing and receiving data in MCL.

This module defines an interface for publishing and receiving data in MCL. This is done by providing abstract objects for broadcasting and listening for data. The interface defined by these objects helps insure new interface implementations will integrate with MCL.

The following abstract objects are defined:

Connection

RawBroadcaster

RawListener

For examples of how to use abstract to integrate a new network interface into MCL see network.udp.

Classes

class Connection[source]¶

Base class for MCL network interface connection objects.

The Connection object provides a base class for defining MCL network interface connection objects. Classes that inherit from Connection must implement the attributes mandatory, broadcaster and listener where:

mandatory is a list of strings defining the names of mandatory message attributes that must be present when instances of the new Message objects are created. During instantiation the input list *args is mapped to the attributes defined by mandatory. If mandatory is not present, a TypeError will be raised.

broadcaster is a reference to the RawBroadcaster object associated with the Connection object.

listener is a reference to the RawListener object associated with the Connection object.

Classes that inherit from Connection can optionally implement the attribute optional where:

optional is a dictionary of optional connection parameters and their defaults. Keywords represent attribute names and the corresponding value represents the default value. During instantiation of the new Connection object, **kwargs is mapped to the attributes defined by optional.

These attributes form the definition of the network interface connection and allow Connection to manufacture a connection class adhering to the specified definition. None of the attribute names can be set to mandatory, broadcaster, listener or optional.

Connection objects behave like collections.namedtuple objects. That is, Connection objects have fields accessible by attribute lookup as well as being indexable and iterable. However, since Connection objects are tuple-like, the data they contain is immutable after instantiation.

Example usage:

from mcl.network.abstract import Connection
from mcl.network.abstract import RawListener
from mcl.network.abstract import RawBroadcaster

# Define new connection object WITH NO optional parameters (abstract
# RawBroadcaster/Listener used for illustration).
class ExampleConnection(Connection):
    mandatory = ('A',)
    broadcaster = RawBroadcaster
    listener = RawListener

# Instantiate connection object.
example = ExampleConnection('A')
print example

# Define new connection object WITH optional parameters.
class ExampleConnection(Connection):
    mandatory = ('A',)
    optional  = {'B': 1, 'C': 2, 'D': 3}
    broadcaster = RawBroadcaster
    listener = RawListener

# Instantiate connection object.
example = ExampleConnection('A', D=5)
print example

Raises:	`TypeError` – If the mandatory or optional attributes are ill-specified. `ValueError` – If any of the mandatory or optional attribute names are ill-specified.

class RawBroadcaster(connection, topic=None)[source]¶

Abstract base class for sending data over a network interface.

The RawBroadcaster is an abstract base class designed to provide a template for objects in the MCL ecosystem which broadcast data over a network interface. Broadcasters inheriting from this template are likely to integrate safely with the MCL system.

Parameters:	connection (`Connection`) – Connection object. topic (str) – Default topic associated with the network interface.

connection¶

Connection

Connection object.

topic¶

str

Default topic associated with the network interface.

is_open¶

bool

Returns True if the network interface is open. Otherwise returns False.

counter¶

int

Number of broadcasts issued.

Raises:	`TypeError` – If any of the inputs are ill-specified.

close()[source]¶

Virtual: Close connection to network interface.

Returns:	Returns `True` if the network interface was closed. If the network interface was already closed, the request is ignored and the method returns `False`.
Return type:	`bool`

publish(data, topic=None)[source]¶

Virtual: Send data over network interface.

Parameters:	data (obj) – Serialisable object to publish over the network interface. topic (str) – Topic associated with published data. This option will temporarily override the topic specified during instantiation.

class RawListener(connection, topics=None)[source]¶

Abstract base class for receiving data over a network interface.

The RawListener is an abstract base class designed to provide a template for objects in the MCL ecosystem which listen for data over a network interface. Listeners inheriting from this template are likely to integrate safely with the MCL system.

Network data is made available to subscribers by issuing callbacks, when data arrives, in the following format:

{'topic': str,
 'payload': obj()}

where:

<topic> is a string containing the topic associated with the received data.

<payload> is the received (serialisable) data.

Note

RawListener implements the event-based programming paradigm by inheriting from Event. Data can be issued to callback functions by calling the RawListener.__trigger__ method. This method has been removed from the public API to prevent users from calling the method. In concrete implementations of the :class:`.RawListener, developers can call the ‘__trigger__’ method in I/O loops when network data is available.

Parameters:	connection (`Connection`) – Connection object. topics (str or list) – Topics associated with the network interface represented as either a string or list of strings.

connection¶

Connection

Connection object.

topics¶

str or list

Topics associated with the network interface.