messages

Object specification for creating messages in MCL.

The messages module provides a means for implementing MCL message objects. This is done through the Message object. Since Message objects derive from python dictionaries, they operate near identically.

Message objects are a specification of what structure of data is being transmitted on a particular abstract.Connection. As a result Message objects are defined by:

• mandatory message attributes that must be present when instances of the new Message objects are created
• a Connection object instance specifying where the message can be broadcast and received

Creating MCL Message objects is simple and is demonstrated in the following example:

from mcl import Message
from mcl.network.udp import Connection as UdpConnection

# Define a message.
class ExampleMessage(Message):
    mandatory = ('text', )
    connection = UdpConnection('ff15::a')

# Create instance of message.
msg = ExampleMessage(text='hello world')
print msg

# Messages objects contain the a 'timestamp' key which records the UTC time
# of when the message object was instantiated. To update the timestamp and
# message attributes, use the update() method.
msg.update(text="I'm a lumberjack")
print msg

# To update a message attribute without updating the timestamp, set it
# directly.
msg['text'] = 'Spam! Spam!'
print msg

# Serialise message into a msgpack binary string. Hex-ify the string for
# demonstration and printability.
print msg.encode().encode('hex')

# The message can also be encoded as a JSON object.
print msg.to_json()

The following functions can be used to retrieve and manipulate Message objects:

• get_message_objects() return Message object(s) from name(s)
• list_messages() list message objects derived from Message
• remove_message_object() de-register a Message object from the list of known messages

Functions

---

get_message_objects(names)

Return Message object(s) from name(s).

Parameters:

name (string or list) – The name (as a string) of a single message object to retrieve. To retrieve multiple message objects, input a list containing the object names.

Returns:

If a single message object is requested (string input), the requested py:class:.Message is returned. If multiple message objects are requested (list input), a list of message objects is returned.

Return type:

Message or list

Raises:

• TypeError – If names is not a string or list/tuple of strings.
• NameError – If names does not exist or multiple message objects are found.

---

list_messages(include=None, exclude=None)

List objects derived from Message.

Parameters:

• include (list) – list of message object names to include.
• exclude (list) – list of message object names to exclude.

Returns:

a list of message objects derived from Message is returned.

Return type:

list

---

remove_message_object(name)

De-register a Message object from the list of known messages.

Parameters:name (string) – Name of the Message object to de-register. Returns:True if the Message object was de-registered. False if the Message object does not exist. Return type:bool

---

Classes

---

class Message(*args, **kwargs)

Base class for MCL message objects.

The Message object provides a base class for defining MCL message objects. Objects inheriting from Message must implement the attribute mandatory where:

• mandatory is a list of strings defining the names of mandatory connection parameters that must be present when instances of the new Connection object are created. If mandatory is not present, a TypeError will be raised.

These attributes define a message format and allow Message to manufacture a message class adhering to the specified definition.

Raises:TypeError – If any of the input argument are invalid.

encode()

Return the contents of the message as serialised binary msgpack data.

Returns:serialised binary msgpack representation of the message contents. Return type:str

to_json()

Return the contents of the message as a JSON string.

Returns:JSON formatted representation of the message contents. Return type:str

update(*args, **kwargs)

Update message contents with new values.

Update message contents from an optional positional argument and/or a set of keyword arguments.

If a positional argument is given and it is a serialised binary msgpack representation of the message contents, it is unpacked and used to update the contents of the message.

serialised = ExampleMessage(text='hello world')
print ExampleMessage(serialised)

If a positional argument is given and it is a mapping object, the message is updated with the same key-value pairs as the mapping object.

print ExampleMessage({'text': 'hello world'})

If the positional argument is an iterable object. Each item in the iterable must itself be an iterable with exactly two objects. The first object of each item becomes a key in the new dictionary, and the second object the corresponding value. If a key occurs more than once, the last value for that key becomes the corresponding value in the message.

print ExampleMessage(zip(('text',), ('hello world',)))

If keyword arguments are given, the keyword arguments and their values are used to update the contents of the message

print ExampleMessage(text='hello world')

If the key ‘timestamp’ is present in the input, the timestamp of the message is set to the input value. If no ‘timestamp’ value is specified, the CPU time-stamp, in milliseconds from UTC epoch, at the end of the update is recorded.

Parameters:

• *args (list) – positional arguments
• *kwargs (dict) – keyword arguments.

Raises:

TypeError – If the message contents could not be updated.

---