Classe Message

La classe Message est utilisée pour définir des messages en vue d'une transmission efficace sur un réseau ou un espace de traitement. Les messages sont définis à l'aide de classes de champs.

La classe Message est fournie par le module protorpc.messages.

Présentation

Les messages sont plus restreints que les classes normales dans la mesure où ils ne peuvent contenir que des attributs de champs et autres définitions Message et Enum. Ces restrictions sont en place, car la structure de la classe Message elle-même est destinée à être transmise sur un réseau ou un espace de traitement et à être utilisée directement par les clients, voire par d'autres serveurs. Ainsi, les méthodes et attributs non définis dans des champs ne peuvent pas être transmis avec des informations de structure, ce qui crée des écarts entre les différents langages et implémentations.

Initialisation et validation

Un objet Message est considéré comme étant initialisé s'il a tous les champs requis et que les messages imbriqués sont également initialisés.

L'appel de "check_initialized" génère une erreur ValidationError si le message n'est pas initialisé. "is_initialized" renvoie une valeur booléenne indiquant si le message est valide.

Le protocole Google RPC valide automatiquement les objets Message lors de leur création et de leur remplissage. Votre application peut valider la compatibilité d'une valeur donnée avec un champ auquel elle est attribuée à l'aide de la méthode validate() de l'instance de champ. Lorsqu'elle est utilisée sur un message, cette méthode vérifie que toutes les valeurs d'un message et ses sous-messages sont correctes. L'attribution d'une valeur non valide à un champ génère une erreur ValidationError.

L'exemple suivant crée et initialise des objets Message dans une application fictive conçue pour les opérations de bourse.

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

Constructeur

Le constructeur de la classe Message est défini comme suit :

class Message(**kwargs)

Initialisez l'état des messages internes.

Une application initialise un message via le constructeur en transmettant des arguments de mot clé correspondant aux classes de champs. Exemple :

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

Une fois le champ de classe défini, vous pouvez appeler de manière concise les valeurs de champs. Les deux appels suivants sont équivalents :

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

Est équivalent à :

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

Méthodes des classes

La classe Message fournit les méthodes de classe suivantes :

all_fields()

Récupère tous les objets de définition de champ. Renvoie un itérateur sur toutes les valeurs dans un ordre arbitraire.

field_by_name(name)

Récupère les champs par nom. Renvoie un objet Field associé au nom.

Génère une erreur KeyError si aucun champ portant ce nom n'est trouvé.

field_by_number(number)

Récupère un champ par numéro. Renvoie l'objet Field associé à ce numéro.

Génère une erreur KeyError si aucun champ portant ce numéro n'est trouvé.

Méthodes des instances

Les instances Message utilisent les méthodes suivantes :

check_initialized()

Vérifie que tous les champs obligatoires sont initialisés.

Génère une erreur ValidationError si l'objet Message n'est pas initialisé.

get_assigned_value(name)

Récupère la valeur attribuée à un attribut. Si la valeur n'est pas définie, renvoie None.

Arguments :

name

Nom de l'attribut à récupérer.

Renvoie la valeur attribuée à un attribut ou None si l'attribut n'a pas de valeur attribuée.

is_initialized(name)

Récupère l'état d'initialisation de l'objet Message. Renvoie True si le message est correct, sinon False.

reset(name)

Réinitialise la valeur attribuée à un champ, ce qui rétablit la valeur par défaut ou, en cas d'absence de valeur par défaut, la définit sur "None".

Arguments :

name

Nom du champ à redéfinir.