A classe Message

A classe Message é usada para definir mensagens para transmissão eficiente em espaços de rede ou processo. As mensagens são definidas por classes de campo.

Message é fornecido pelo módulo protorpc.messages.

Introdução

As mensagens são classes mais restritas que o normal porque só contêm atributos de campo e outras definições de Mensagem e Enum. Essas restrições estão em vigor porque a estrutura da classe Message é transmitida por meio da rede ou do espaço do processo e usada diretamente pelos clientes ou até mesmo por outros servidores. Assim, métodos e atributos que não são de campo não podem ser transmitidos com informações estruturais, causando discrepâncias entre diferentes linguagens e implementações.

Inicialização e validação

Um objeto Message é considerado inicializado se tiver todos os campos obrigatórios e se mensagens aninhadas também tiverem sido inicializadas.

Um ValidationError será gerado para a chamada "check_initialized" em caso de não inicialização. Um valor booleano que indica a validade da chamada é retornado por "is_initialized".

Os objetos Message são validados automaticamente pelo protocolo de RPC do Google quando são criados e preenchidos. Com o método validate() da instância de Field, é possível que o aplicativo verifique se determinado valor é compatível com o campo a que foi atribuído. Quando usado em uma mensagem, o método verifica se todos os valores de uma mensagem e das respectivas submensagens são válidos. A atribuição de um valor inválido a um campo causa um ValidationError.

O exemplo a seguir cria e inicializa objetos Message em um aplicativo fictício de comércio de ações.

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()

Construtor

O construtor da classe Message é definido assim:

class Message(**kwargs)

Inicializa o estado interno de mensagens.

A mensagem é iniciada pelo aplicativo por meio do construtor, com a transmissão dos argumentos da palavra-chave correspondentes às classes de campo. Exemplo:

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

Após definir o campo da classe, invoque valores de campo de forma concisa. As duas invocações a seguir são equivalentes:

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

É equivalente a:

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

Métodos de classe

A classe Message fornece os seguintes métodos de classe:

all_fields()

Consegue todos os objetos de definição de campo. Retorna um iterador sobre todos os valores em ordem arbitrária.

field_by_name(name)

Recebe os campos por nome. Retorna um objeto Field associado ao nome.

Um KeyError é gerado se nenhum campo com esse nome for encontrado.

field_by_number(number)

Recebe o campo por número. Retorna o objeto de campo associado a esse número.

Um KeyError é gerado se nenhum campo com esse número for encontrado.

Métodos da instância

As instâncias de mensagem têm os seguintes métodos:

check_initialized()

Verifica se todos os campos obrigatórios foram inicializados.

Um ValidationError é gerado se o objeto Message não for inicializado.

get_assigned_value(name)

Recebe o valor atribuído de um atributo. Se o valor não estiver definido, retorna None.

Argumentos:

name

Nome do atributo a ser recebido.

Retorna o valor atribuído do atributo ou None, se o atributo não tiver um valor atribuído.

is_initialized(name)

Recebe o status de inicialização do objeto Message. Retorna True, se a mensagem for válida, ou False.

reset(name)

Redefine o valor atribuído a um campo, restabelecendo o valor padrão ou, se não houver valor padrão, None.

Argumentos:

name

Nome do campo a ser redefinido.