Le module descriptor.py contient les définitions des messages et les fonctions permettant de convertir les définitions Google Protocol RPC vers un format de message pouvant être transmis.
La description d'une instance Enum, d'une classe Enum, d'une classe Field ou d'une classe Message génère un objet descripteur approprié. Un objet descripteur est un objet qui décrit d'autres définitions Google Protocol RPC, telles que des énumérations, des messages et des services. Vous pouvez utiliser ce message pour transmettre des informations aux clients qui souhaitent connaître la description d'une valeur d'énumération, d'une énumération, d'un champ ou d'un message sans avoir à télécharger le code source. Ce format est également compatible avec d'autres languages que Python.
Les descripteurs sont conçus pour être compatibles en mode binaire avec https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/descriptor.proto
Remarque : Les noms des types et champs définis dans descriptor.py ne correspondent pas nécessairement à ceux définis dans descriptor.proto. Google Protocol RPC est conçu de cette manière pour faciliter la lecture des fichiers de code source utilisant ces descripteurs. Par exemple, FieldDescriptors doit être précédé de TYPE dans descriptor.proto, mais pas dans descriptor.py.
L'exemple de code suivant montre comment utiliser le module descripteur pour décrire une classe appelée Pixel à l'aide de la classe MessageDescriptor.
from protorpc import descriptor
from protorpc import messages
class Pixel(messages.Message):
x = messages.IntegerField(1, required=True)
y = messages.IntegerField(2, required=True)
color = messages.BytesField(3)
# Describe Pixel class using message descriptor.
fields = [
descriptor.FieldDescriptor(name='x',
number=1,
label=descriptor.FieldDescriptor.Label.REQUIRED,
variant=descriptor.FieldDescriptor.Variant.INT64),
descriptor.FieldDescriptor(name='y',
number=2,
label=descriptor.FieldDescriptor.Label.REQUIRED,
variant=descriptor.FieldDescriptor.Variant.INT64),
descriptor.FieldDescriptor(name='color',
number = 3,
label=descriptor.FieldDescriptor.Label.OPTIONAL,
variant=descriptor.FieldDescriptor.Variant.BYTES)]
message = descriptor.MessageDescriptor(name='Pixel',
fields=fields)
# Describing is the equivalent of building the above message.
message == descriptor.describe_message(Pixel)
Le package protorpc.descriptor comprend les fonctions suivantes :
- describe(value)
-
Décrit une valeur comme un descripteur. Vous pouvez utiliser cette fonction d'assistance pour décrire un objet avec un objet descripteur approprié.
Arguments- value
- Valeur à décrire comme un descripteur.
Renvoie un descripteur si l'objet est descriptible comme un descripteur, sinon None.
- describe_enum(enum_definition)
-
Crée un descripteur à partir d'une classe Enum.
Arguments- enum_value
- Classe Enum à décrire.
Renvoie une instance EnumDescriptor initialisée décrivant l'instance Enum.
Champs de la classe EnumDescriptor :
name- Nom de la classe Enum spécifiée sans aucune qualification.
values- Valeurs définies par la classe Enum.
- describe_enum_value(enum_value)
-
Crée un descripteur à partir d'une instance Enum. Arguments
- enum_value
- Valeur Enum à décrire.
Renvoie une instance EnumValueDescriptor initialisée décrivant l'instance Enum.
Champs de la classe EnumValueDescriptor :
name- Nom de la valeur d'énumération.
number- Numéro de la valeur d'énumération.
- describe_field(field_definition)
-
Crée un descripteur à partir d'une instance Field.
Arguments- field_definition
- Instance Field à décrire.
Renvoie une instance FieldDescriptor initialisée décrivant l'instance Field avec une liste d'énumérations et de champs.
Énumérations de la classe FieldDescriptor :
Variant- Sous-types du format de transmission pour le champ spécifié.
Label- Valeurs des champs facultatifs, obligatoires et répétés.
Champs de la classe FieldDescriptor :
name- Nom du champ spécifié.
number- Numéro du champ spécifié.
variant- Variante du champ spécifié.
type_name- Nom du type pour les champs de message et d'énumération.
default_value- Représentation sous forme de chaîne de la valeur par défaut.
- describe_file(module)
-
Crée un fichier à partir d'un module Python spécifié.
Arguments- module
- Module Python à décrire.
Renvoie une instance FileDescriptor initialisée décrivant le module.
Champs de la classe FileDescriptor :
package- Nom complet du package auquel appartiennent les définitions.
message_types- Définitions de messages contenues dans le fichier.
enum_types- Définitions d'énumérations contenues dans le fichier.
service_types- Définitions de services contenues dans le fichier.
- describe_file_set(modules)
-
Crée un ensemble de fichiers à partir des modules Python spécifiés.
Arguments- modules
- Valeur itérable du module Python à décrire.
Renvoie une instance FileSet initialisée décrivant le module.
Champs de la classe FileSet :
files- Fichiers de l'ensemble de fichiers.
- describe_message(message_definition)
-
Crée un descripteur à partir d'une classe Message.
Arguments- message_definition
- Classe Message à décrire.
Renvoie une instance MessageDescriptor initialisée décrivant la classe Message.
Champs de la classe MessageDescriptor :
name- Nom complet du package auquel appartiennent les définitions.
fields- Champs définis pour le message.
message_types- Classes Message imbriquées définies dans le message.
enum_types- Classes Enum imbriquées définies dans le message.
- describe_method(method)
-
Crée un descripteur à partir d'une méthode distante du service.
Arguments- Méthode distante du service à décrire.
Renvoie une instance MethodDescriptor initialisée décrivant la méthode distante du service.
Champs de la classe MethodDescriptor :
name- Nom de la méthode du service.
request_type- Nom complet ou relatif du type du message de la requête.
response_type- Nom complet ou relatif du type du message de la réponse.
- describe_service(service_class)
-
Crée un descripteur à partir d'une classe Service.
Arguments- service_class
- Classe Service à décrire.
Renvoie une instance ServiceDescriptor initialisée décrivant le service.
Champs de la classe ServiceDescriptor :
name- Nom incomplet du service.
methods- Méthodes distantes du service.
- import_descriptor_loader(definition_name, importer=__import__ )
-
Recherche des objets en important des modules, si nécessaire. Un outil de chargement de définitions est une fonction qui résout un nom de définition par rapport à un descripteur. L'outil de recherche d'importations résout des définitions par rapport à leurs noms en important des modules, si nécessaire.
Arguments- definition_name
- Nom de la définition à rechercher.
- importer=__import__ )
- Fonction d'importation utilisée pour l'importation de nouveaux modules.
Renvoie un descripteur approprié depuis un type descriptible situé à côté du nom.
Déclenche une erreur DefinitionNotFoundError lorsqu'un nom ne fait référence ni à une définition, ni à un module.