El módulo descriptor.py contiene definiciones de mensajes y funciones para convertir definiciones de llamadas a procedimiento remoto (RPC) del protocolo de Google en un formato de mensaje transmisible.
Al describir una instancia de Enum, una clase Enum, una clase Field o una clase Message, se genera el objeto descriptor apropiado. Un objeto de descriptor es un objeto que describe otras definiciones de RPC de Protocol de Google, como enumeraciones, mensajes y servicios. Puedes utilizar este mensaje para transmitir información a los clientes que deseen conocer la descripción de un valor de Enum, un enum, un campo o un mensaje sin necesidad de descargar el código fuente. Este formato también es compatible con otros lenguajes distintos de Python.
Los descriptores se han diseñado para que sean compatibles con el formato binario de https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/descriptor.proto.
Nota: Los nombres de los tipos y los campos definidos en descriptor.py no tienen por qué coincidir con los definidos en descriptor.proto. El protocolo RPC de Google se ha diseñado de esta forma para que los archivos de código fuente que usan estos descriptores sean más fáciles de leer. Por ejemplo, los FieldDescriptors deben ir precedidos de TYPE en descriptor.proto, pero no en descriptor.py.
En el siguiente ejemplo de código se muestra cómo usar el módulo de descriptor para describir una clase llamada Pixel mediante la clase 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)
El paquete protorpc.descriptor proporciona las siguientes funciones:
- describe(value)
-
Describe cualquier valor como descriptor. Puedes utilizar esta función de ayuda para describir cualquier objeto con un objeto descriptor apropiado.
Argumentos- value
- Valor que se va a describir como un descriptor.
Devuelve un descriptor si el objeto es descriptible como descriptor; de lo contrario, devuelve None.
- describe_enum(enum_definition)
-
Crea un descriptor de una clase Enum.
Argumentos- enum_value
- La clase Enum que se va a describir.
Devuelve una instancia de EnumDescriptor inicializada que describe la instancia de Enum.
Campos de la clase EnumDescriptor:
name- Nombre del enum especificado sin ninguna cualificación.
values- Valores definidos por la clase Enum.
- describe_enum_value(enum_value)
-
Crea un descriptor de una instancia de Enum. Argumentos
- enum_value
- Valor de enumeración que se va a describir.
Devuelve una instancia de EnumValueDescriptor inicializada que describe la instancia de Enum.
Campos de la clase EnumValueDescriptor:
name- Nombre del valor de enumeración.
number- Número del valor de enumeración.
- describe_field(field_definition)
-
Crea un descriptor a partir de una instancia de Field.
Argumentos- field_definition
- Instancia de Field que se va a describir.
Devuelve una instancia de FieldDescriptor que describe la instancia de Field con una lista de enums y campos.
Enums de la clase FieldDescriptor:
Variant- Subtipos de sugerencias de formato de cable para el campo especificado.
Label- Valores de los campos opcionales, obligatorios y repetidos.
Campos de la clase FieldDescriptor:
name- Nombre del campo especificado.
number- Número del campo especificado.
variant- Variante del campo especificado.
type_name- Escribe el nombre de los campos de mensaje y enum.
default_value- Representación de cadena del valor predeterminado.
- describe_file(módulo)
-
Crea un archivo a partir de un módulo Python especificado.
Argumentos- module
- El Python que se va a describir.
Devuelve una instancia de FileDescriptor inicializada que describe el módulo.
Campos de la clase FileDescriptor
package- Nombre completo del paquete al que pertenecen las definiciones.
message_types- Definiciones de mensajes contenidas en el archivo.
enum_types- Definiciones de enumeraciones contenidas en el archivo.
service_types- Definiciones de servicio incluidas en el archivo.
- describe_file_set(modules)
-
Crea un conjunto de archivos a partir de los módulos Python especificados.
Argumentos- modules
- Iterable del módulo de Python que se va a describir.
Devuelve una instancia de FileSet inicializada que describe el módulo.
Campos de la clase FileSet:
files- Archivos del conjunto de archivos.
- describe_message(message_definition)
-
Crea un descriptor a partir de una clase Message.
Argumentos- message_definition
- Clase Message que se va a describir.
Devuelve una instancia de MessageDescriptor inicializada que describe la clase Message.
Campos de la clase MessageDescriptor:
name- Nombre completo del paquete al que pertenecen las definiciones.
fields- Campos definidos para el mensaje.
message_types- Clases de mensajes anidadas definidas en el mensaje.
enum_types- Clases Enum anidadas definidas en el mensaje.
- describe_method(método)
-
Crea un descriptor a partir de un método de servicio remoto.
Argumentos- método
- El método de servicio remoto que se va a describir.
Devuelve una instancia de MethodDescriptor inicializada que describe el método de servicio remoto.
Campos de MethodDescriptor:
name- Nombre del método del servicio.
request_type- Nombre completo o relativo del tipo de mensaje de solicitud.
response_type- Nombre completo o relativo del tipo de mensaje de respuesta.
- describe_service(service_class)
-
Crea un descriptor a partir de una clase Service.
Argumentos- service_class
- La clase de servicio que se va a describir.
Devuelve una instancia de ServiceDescriptor inicializada que describe el servicio.
Campos de ServiceDescriptor:
name- Nombre no cualificado del servicio.
methods- Métodos remotos del Servicio.
- import_descriptor_loader(definition_name, importer=__import__ )
-
Encuentra objetos importando módulos según sea necesario. Un cargador de definiciones es una función que resuelve un nombre de definición en un descriptor. El buscador de importaciones resuelve las definiciones en sus nombres importando módulos cuando es necesario.
Argumentos- definition_name
- Nombre de la definición que se va a buscar.
- importer=__import__ )
- Función de importación que se usa para importar módulos nuevos.
Devuelve un descriptor apropiado a partir de cualquier tipo descriptible localizándolo por su nombre.
Genera un error DefinitionNotFoundError cuando un nombre no hace referencia a una definición ni a un módulo.