Observação: o Python 2.7 chegou ao fim do suporte em 31 de janeiro de 2024. Os aplicativos Python 2.7 atuais continuarão a ser executados e a receber tráfego. No entanto, o App Engine pode bloquear a reimplantação de aplicativos que usam ambientes de execução após o término da data de suporte. Recomendamos que você migre para a versão compatível mais recente do Python.

Funções do módulo descritor

O módulo descriptor.py contém definições e funções de mensagem para converter definições de RPC do protocolo do Google em um formato de mensagem transmissível.

Descrever uma instância de Enum, classe Enum, classe Field ou classe Message gera um objeto descritor apropriado. Um objeto descritor é um objeto que descreve outras definições de RPC do protocolo do Google, como enums, mensagens e serviços. Você pode usar essa mensagem para transmitir informações para clientes que querem saber a descrição de um valor de enum, enum, campo ou mensagem sem precisar fazer download do código-fonte. Esse formato também é compatível com outras linguagens além de Python.

Os descritores são modelados para serem binários compatíveis com https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/descriptor.proto

Observação! Os nomes de tipos e campos definidos em descriptor.py não correspondem necessariamente aos definidos em descriptor.proto. O RPC do protocolo do Google foi projetado dessa maneira para facilitar a leitura dos arquivos de código-fonte que usam esses descritores. Por exemplo, FieldDescriptors precisam do prefixo com TYPE em descriptor.proto, mas não em descriptor.py.

O exemplo de código a seguir demonstra o uso do módulo descritor para descrever uma classe chamada Pixel usando a 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)

O pacote protorpc.descriptor oferece as seguintes funções:

describe(value)

Descreve qualquer valor como um descritor. Você pode usar essa função assistente para descrever qualquer objeto com um objeto descritor apropriado.

Argumentos

value: O valor a ser descrito como um descritor.

Retorna um descritor se o objeto puder ser descrito como um descritor, ou None.

describe_enum(enum_definition)

Constrói um descritor a partir de uma classe Enum.

Argumentos

enum_value: A classe Enum a ser descrita.

Retorna uma instância de EnumDescriptor inicializada que descreve a instância de Enum.

Campos da classe EnumDescriptor:

name: Nome da Enum especificada sem nenhuma qualificação.
values: Valores definidos pela classe Enum.

describe_enum_value(enum_value)

Constrói um descritor a partir de uma instância de Enum. Argumentos

enum_value: O valor de Enum a ser descrito.

Retorna uma instância de EnumValueDescriptor inicializada que descreve a instância de Enum.

Campos da classe EnumValueDescriptor:

name: Nome do valor de enumeração.
number: Número do valor de enumeração.

describe_field(field_definition)

Constrói um descritor a partir de uma instância de Field.

Argumentos

field_definition: A instância de Field a ser descrita.

Retorna uma instância de FieldDescriptor inicializada que descreve a instância de Field com uma lista de Enums e campos.

Enums da classe FieldDescriptor:

Variant: O formato wire indica os subtipos do campo especificado.
Label: Valores de campos opcionais, obrigatórios e repetidos.

Campos da classe FieldDescriptor:

name: Nome do campo especificado.
number: Número do campo especificado.
variant: Variante do campo especificado.
type_name: Nome do tipo dos campos de mensagem e enum.
default_value: Representação de string do valor padrão.

describe_file(module)

Constrói a partir de um arquivo de um módulo Python especificado.

Argumentos

module: O Python a ser descrito.

Retorna uma instância de FileDescriptor que descreve o módulo.

Campos da classe FileDescriptor

package: Nome totalmente qualificado do pacote ao qual pertencem as definições.
message_types: Definições de mensagens contidas no arquivo.
enum_types: Definições de enum contidas no arquivo.
service_types: Definições de serviço contidas no arquivo.

describe_file_set(modules)

Constrói um conjunto de arquivos dos módulos Python especificados.

Argumentos

modules: Iterável do módulo Python a ser descrito.

Retorna uma instância de FileSet inicializada que descreve o módulo.

Campos da classe FileSet:

files: Arquivos no conjunto de arquivos.

describe_message(message_definition)

Constrói um descritor a partir de uma classe Message.

Argumentos

message_definition: A classe Message a ser descrita.

Retorna uma instância de MessageDescriptor inicializada que descreve a classe Message.

Campos da classe MessageDescriptor:

name: Nome totalmente qualificado do pacote ao qual pertencem as definições.
fields: Campos definidos para a mensagem.
message_types: Classes Nested Message definidas na mensagem.
enum_types: Classes Nested Enum definidas na mensagem.

describe_method(method)

Constrói um descritor a partir de um método de serviço remoto.

Argumentos

: O método de serviço remoto a ser descrito.

Retorna uma instância de MethodDescriptor inicializada que descreve o método de serviço remoto.

Campos de MethodDescriptor:

name: Nome do método de serviço.
request_type: Nome totalmente qualificado ou nome relativo do tipo de mensagem de solicitação.
response_type: Nome totalmente qualificado ou nome relativo ou do tipo de mensagem de resposta.

describe_service(service_class)

Constrói um descritor a partir de uma classe Service.

Argumentos

service_class: A classe Service a ser descrita.

Retorna uma instância de ServiceDescriptor inicializada que descreve o serviço.

Campos de ServiceDescriptor:

name: Nome não qualificado de Service.
methods: Métodos remotos do Serviço.

import_descriptor_loader(definition_name, importer=__import__ )

Encontra objetos por meio da importação de módulos conforme necessário. Um carregador de definição é uma função que resolve um nome de definição para um descritor. O localizador de importação resolve definições para seus nomes por meio da importação de módulos quando necessário.

Argumentos

definition_name: Nome da definição a ser encontrada.
importer=__import__ ): Função de importação usada para importar novos módulos.

Retorna um descritor apropriado de qualquer tipo que possa ser descrito localizado pelo nome.

É gerado um erro DefinitionNotFoundError quando um nome não se refere a uma definição ou um módulo.