Nota: Python 2.7 alcanzó el fin de la asistencia el 31 de enero de 2024. Tus aplicaciones existentes de Python 2.7 seguirán ejecutándose y recibiendo tráfico. Sin embargo, App Engine podría bloquear la reimplementación de aplicaciones que usan entornos de ejecución después de la fecha de finalización de la asistencia. Te recomendamos que migres a la última versión compatible de Python.

Funciones del módulo descriptor

El módulo descriptor.py contiene definiciones de mensajes y funciones para convertir las definiciones de la RPC del protocolo de Google en un formato de mensaje transmisible.

Cuando se describe una instancia de Enumeración, una clase de Enumeración, una clase de Campo o una clase de Mensaje se genera un objeto descriptor apropiado. Un objeto descriptor es un objeto que describe otras definiciones de la RPC del protocolo de Google como, por ejemplo, enumeraciones, mensajes y servicios. Puedes usar este mensaje para transmitir información a los clientes que deseen conocer la descripción de un valor de enumeración, campo o mensaje sin necesidad de descargar el código fuente. Este formato también es compatible con otros lenguajes que no sean Python.

Los descriptores se modelan para ser objetos binarios compatibles con https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/descriptor.proto.

Nota: Los nombres de tipos y campos que se definen en descriptor.py no necesariamente coinciden con los definidos en descriptor.proto. La RPC del protocolo de Google está diseñada de esta manera para hacer que los archivos de código fuente que usan estos descriptores sean más fáciles de leer. Por ejemplo, FieldDescriptors debe tener el prefijo TYPE en descriptor.proto, pero no en descriptor.py.

En la siguiente muestra de código, se explica el uso del módulo descriptor para describir una clase llamada Pixel con 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 un descriptor. Puedes utilizar esta función auxiliar para describir cualquier objeto con un objeto descriptor apropiado.

Argumentos

value: El valor a describir como un descriptor.

Muestra un descriptor si el objeto se puede describir como un descriptor, de lo contrario, Ninguno.

describe_enum(enum_definition)

Compila un descriptor a partir de una clase de Enumeración.

Argumentos

enum_value: La clase de Enumeración a describir.

Muestra una instancia inicializada de EnumDescriptor que describe la instancia de Enumeración.

Campos de la clase EnumDescriptor:

name: El nombre de la Enumeración especificada sin ninguna calificación.
values: Los valores que define la clase de Enumeración.

describe_enum_value(enum_value)

Compila un descriptor a partir de una instancia de Enumeración. Argumentos

enum_value: El valor de Enumeración a describir.

Muestra una instancia inicializada de EnumValueDescriptor que describe la instancia de Enumeración.

Campos de la clase EnumValueDescriptor:

name: El nombre del valor de enumeración.
number: El número del valor de enumeración.

describe_field(field_definition)

Compila un descriptor a partir de una instancia de Campo.

Argumentos

field_definition: La instancia de Campo que se describirá.

Muestra una instancia inicializada de FieldDescriptor que describe la instancia de Campo con una lista de las Enumeraciones y los campos

Enumeraciones de la clase FieldDescriptor:

Variant: Los subtipos con sugerencias de formato de cable para el campo especificado.
Label: Los valores para los campos opcionales, obligatorios y repetidos.

Campos de la clase FieldDescriptor:

name: El nombre del campo especificado.
number: El número del campo especificado.
variant: La variante del campo especificado.
type_name: El nombre del tipo para los campos de mensaje y enumeración.
default_value: Representación de string del valor predeterminado.

describe_file(module)

Compila un archivo a partir de un módulo de Python especificado.

Argumentos

module: El Python a describir.

Muestra una instancia inicializada de FileDescriptor que describe el módulo.

Campos de la clase FileDescriptor

package: El nombre completo del paquete al que pertenecen las definiciones.
message_types: Las definiciones de mensajes que se incluyen en el archivo.
enum_types: Las definiciones de enumeraciones que se incluyen en el archivo.
service_types: Las definiciones de servicios que se incluyen en el archivo.

describe_file_set(modules)

Compila un conjunto de archivos a partir de los módulos de Python especificados.

Argumentos

modules: La capacidad de repetición del módulo de Python para describir.

Muestra una instancia inicializada de FileSet que describe el módulo.

Campos de la clase FileSet:

files: Los archivos en el conjunto de archivos.

describe_message(message_definition)

Compila un descriptor a partir de una clase de Mensaje.

Argumentos

message_definition: La clase de Mensaje a describir.

Muestra una instancia inicializada de MessageDescriptor que describe la clase de Mensaje.

Campos de la clase MessageDescriptor:

name: El nombre completo del paquete al que pertenecen las definiciones.
fields: Los campos definidos para el mensaje.
message_types: Las clases Mensaje anidadas que se definen en el mensaje.
enum_types: Las clases de Enumeración anidadas que se definen en el mensaje.

describe_method(method)

Compila un descriptor a partir de un método de servicio remoto.

Argumentos

método: El método de servicio remoto a describir.

Muestra una instancia inicializada de MethodDescriptor que describe el método de servicio remoto.

Campos de MethodDescriptor:

name: El nombre del método de servicio.
request_type: El nombre completo o el nombre relativo del tipo de mensaje de solicitud.
response_type: El nombre completo o el nombre relativo del tipo de mensaje de respuesta.

describe_service(service_class)

Compila un descriptor a partir de una clase de Servicio.

Argumentos

service_class: La clase de Servicio a describir.

Muestra una instancia inicializada de ServiceDescriptor que describe el servicio.

Campos de ServiceDescriptor:

name: El nombre no calificado del Servicio.
methods: Los métodos remotos del Servicio.

import_descriptor_loader(definition_name, definition_name=__import__ )

Encuentra objetos mediante la importación de módulos según sea necesario. Un cargador de definiciones es una función que decide un nombre de definición de un descriptor. El localizador de importación decide las definiciones de los nombres mediante la importación de módulos cuando sea necesario.

Argumentos

definition_name: El nombre de la definición a buscar.
importer=__import__ ): La función de importación que se utiliza para importar módulos nuevos.

Muestra un descriptor apropiado a partir cualquier tipo descriptible ubicado por nombre.

Genera un error DefinitionNotFoundError cuando un nombre no hace referencia a una definición o un módulo.