The Message Class

The Message class is used to define messages for efficient transmission across network or process space. Messages are defined using field classes.

Message is provided by the protorpc.messages module.

Introduction

Messages are more restricted than normal classes in that they may only contain field attributes and other Message and Enum definitions. These restrictions are in place because the structure of the Message class itself is intended to be transmitted across network or process space and used directly by clients or even other servers. As such, methods and non-field attributes cannot be transmitted with structural information, which causes discrepancies between different languages and implementations.

Initialization and Validation

A Message object is considered to be initialized if it has all required fields and any nested messages are also initialized.

Calling 'check_initialized' will raise a ValidationError if it is not initialized; 'is_initialized' returns a boolean value indicating if it is valid.

Google Protocol RPC validates Message objects automatically when they are created and populated. Your application can validate whether a given value is compatible with a field that it is assigned to using the Field instance's validate() method. When used on a message, this method checks that all values of a message and its sub-messages are valid. Assigning an invalid value to a field raises a ValidationError.

The following example creates and initializes Message objects in a fictitious stock trading application.

from protorpc import messages

# Trade type.
class TradeType(messages.Enum):
    BUY = 1
    SELL = 2
    SHORT = 3
    CALL = 4

class Lot(messages.Message):
    price = messages.IntegerField(1, required=True)
    quantity = messages.IntegerField(2, required=True)

class Order(messages.Message):
    symbol = messages.StringField(1, required=True)
    total_quantity = messages.IntegerField(2, required=True)
    trade_type = messages.EnumField(TradeType, 3, required=True)
    lots = messages.MessageField(Lot, 4, repeated=True)
    limit = messages.IntegerField(5)

order = Order(symbol='GOOG',
              total_quantity=10,
              trade_type=TradeType.BUY)

lot1 = Lot(price=304,
           quantity=7)

lot2 = Lot(price=305,
           quantity=3)

order.lots = [lot1, lot2]

# Now object is initialized!
order.check_initialized()

Constructor

The constructor of the Message class is defined as follows:

class Message(**kwargs)

Initialize the internal messages state.

An application initializes a message via the constructor by passing in keyword arguments corresponding to field classes. For example:

class Date(Message)
    day = IntegerField(1)
    month = IntegerField(2)
    year = IntegerField(3)

After defining the class field, you can concisely invoke field values. The following two invocations are equivalent:

date = Date(day=6, month=6, year=1911)

Is equivalent to:

date = Date()
date.day = 6
date.month = 6
date.year = 1911

Class Methods

The Message class provides the following class methods:

all_fields()

Gets all field definition objects. Returns an iterator over all values in arbitrary order.

field_by_name(name)

Gets fields by name. Returns a Field object associated with the name.

Raises a KeyError if no field by that name is found.

field_by_number(number)

Gets a field by number. Returns the field object associated with that number.

Raises a KeyError if no field by that number is found.

Instance Methods

Message instances have the following methods:

check_initialized()

Checks that all required fields are initialized.

Raises a ValidationError if the Message object is not initialized.

get_assigned_value(name)

Gets the assigned value of an attribute. If the value is unset, returns None.

Arguments:

name

Name of the attribute to get.

Returns the assigned value of an attribute, or None if the attribute has no assigned value.

is_initialized(name)

Gets the initialization status for the Message object. Returns True if the message is valid, else False.

reset(name)

Resets the assigned value for a field, which re-establishes the default value or, if there is no default value, None.

Arguments:

name

Name of the field to reset.