A classe da mensagem

A classe Message é usada para definir mensagens para uma transmissão eficiente na rede ou no espaço de processamento. As mensagens são definidas através de classes de campos.

O Message é fornecido pelo módulo protorpc.messages.

Introdução

As mensagens são mais restritas do que as classes normais, pois só podem conter atributos de campos e outras definições de mensagens e enumerações. Estas restrições estão em vigor porque a estrutura da classe Message propriamente dita destina-se a ser transmitida através da rede ou do espaço de processamento e usada diretamente pelos clientes ou até mesmo por outros servidores. Como tal, os métodos e os atributos não pertencentes a campos não podem ser transmitidos com informações estruturais, o que causa discrepâncias entre diferentes idiomas e implementações.

Inicialização e validação

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

A chamada de "check_initialized" gera um ValidationError se não estiver inicializado; "is_initialized" devolve um valor booleano que indica se é válido.

O RPC do protocolo Google valida automaticamente os objetos Message quando são criados e preenchidos. A sua aplicação pode validar se um determinado valor é compatível com um campo ao qual está atribuído através do método validate() da instância Field. Quando usado numa mensagem, este método verifica se todos os valores de uma mensagem e das respetivas submembros são válidos. A atribuição de um valor inválido a um campo gera um ValidationError.

O exemplo seguinte cria e inicializa objetos Message numa aplicação fictícia de negociação 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 da seguinte forma:

class Message(**kwargs)

Inicialize o estado das mensagens internas.

Uma aplicação inicializa uma mensagem através do construtor, transmitindo argumentos de palavras-chave correspondentes a classes de campos. Por exemplo:

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

Depois de definir o campo de classe, pode invocar concisamente os valores dos campos. As duas invocações seguintes 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()
Obtém todos os objetos de definição de campos. Devolve um iterador sobre todos os valores por ordem arbitrária.
field_by_name(name)
Obtém campos por nome. Devolve um objeto Field associado ao nome.
Gera um KeyError se não for encontrado nenhum campo com esse nome.
field_by_number(number)
Obtém um campo por número. Devolve o objeto de campo associado a esse número.
Gera um KeyError se não for encontrado nenhum campo com esse número.

Métodos de instância

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

check_initialized()
Verifica se todos os campos obrigatórios estão inicializados.
Gera um ValidationError se o objeto Message não estiver inicializado.
get_assigned_value(name)
Obtém o valor atribuído de um atributo. Se o valor não estiver definido, devolve Nenhum.
Argumentos:
name
Nome do atributo a obter.

Devolve o valor atribuído de um atributo ou Nenhum se o atributo não tiver nenhum valor atribuído.

is_initialized(name)
Obtém o estado de inicialização do objeto Message. Devolve True se a mensagem for válida, caso contrário, devolve False.
reset(name)
Repõe o valor atribuído de um campo, o que restabelece o valor predefinido ou, se não existir um valor predefinido, Nenhum.
Argumentos:
name
Nome do campo a repor.