O módulo descriptor.py contém definições de mensagens e funções para converter definições de RPC do protocolo Google num formato de mensagem transmissível.
A descrição de uma instância Enum, uma classe Enum, uma classe Field ou uma classe Message gera um objeto descritor adequado. Um objeto descritor é um objeto que descreve outras definições de RPC do protocolo Google, como enumerações, mensagens e serviços. Pode usar esta mensagem para transmitir informações a clientes que queiram saber a descrição de um valor de enumeração, uma enumeração, um campo ou uma mensagem sem terem de transferir o código fonte. Este formato também é compatível com outras linguagens que não sejam Python.
Os descritores são modelados para serem binariamente compatíveis com https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/descriptor.proto
Nota! Os nomes dos tipos e dos campos definidos em descriptor.py não correspondem necessariamente aos definidos em descriptor.proto. O RPC do Protocol Buffer da Google foi concebido desta forma para facilitar a leitura dos ficheiros de código fonte que usam estes descritores. Por exemplo, os FieldDescriptors têm de ter o prefixo TYPE em descriptor.proto, mas não em descriptor.py.
O seguinte exemplo de código demonstra a utilização do módulo de descritor para descrever uma classe denominada Pixel através da 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. Pode usar esta função auxiliar para descrever qualquer objeto com um objeto descritor adequado.
Argumentos- valor
- Valor a descrever como um descritor.
Devolve um descritor se o objeto for descritível como um descritor. Caso contrário, devolve None.
- describe_enum(enum_definition)
-
Cria um descritor a partir de uma classe Enum.
Argumentos- enum_value
- A classe Enum a descrever.
Devolve uma instância EnumDescriptor inicializada que descreve a instância Enum.
Campos da classe EnumDescriptor:
name- Nome da enumeração especificada sem qualificações.
values- Valores definidos pela classe Enum.
- describe_enum_value(enum_value)
-
Cria um descritor a partir de uma instância de enumeração. Argumentos
- enum_value
- O valor Enum a descrever.
Devolve uma instância EnumValueDescriptor inicializada que descreve a instância Enum.
Campos da classe EnumValueDescriptor:
name- Nome do valor de enumeração.
number- Número do valor de enumeração.
- describe_field(field_definition)
-
Cria um descritor a partir de uma instância de campo.
Argumentos- field_definition
- A instância do campo a descrever.
Devolve uma instância FieldDescriptor inicializada que descreve a instância Field com uma lista de enumerações e campos.
Enumerações da classe FieldDescriptor:
Variant- Subtipos de sugestões de formato de transmissão para o campo especificado.
Label- Valores para 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- Introduza o nome da mensagem e os campos enum.
default_value- Representação de string do valor predefinido.
- describe_file(module)
-
Cria um ficheiro a partir de um módulo Python especificado.
Argumentos- module
- O Python a descrever.
Devolve uma instância FileDescriptor inicializada que descreve o módulo.
Campos da classe FileDescriptor
package- Nome totalmente qualificado do pacote ao qual as definições pertencem.
message_types- Definições de mensagens contidas no ficheiro.
enum_types- Definições de enumeração contidas no ficheiro.
service_types- Definições de serviços contidas no ficheiro.
- describe_file_set(modules)
-
Cria um conjunto de ficheiros a partir dos módulos Python especificados.
Argumentos- modules
- Iterable do módulo Python a descrever.
Devolve uma instância FileSet inicializada que descreve o módulo.
Campos da classe FileSet:
files- Ficheiros no conjunto de ficheiros.
- describe_message(message_definition)
-
Cria um descritor a partir de uma classe Message.
Argumentos- message_definition
- A classe Message a descrever.
Devolve uma instância MessageDescriptor inicializada que descreve a classe Message.
Campos da classe MessageDescriptor:
name- Nome totalmente qualificado do pacote ao qual as definições pertencem.
fields- Campos definidos para a mensagem.
message_types- Classes de mensagens aninhadas definidas na mensagem.
enum_types- Classes Enum aninhadas definidas na mensagem.
- describe_method(method)
-
Cria um descritor a partir de um método de serviço remoto.
Argumentos- método
- O método de serviço remoto a descrever.
Devolve uma instância MethodDescriptor inicializada que descreve o método do serviço remoto.
Campos MethodDescriptor:
name- Nome do método de serviço.
request_type- Nome totalmente qualificado ou nome relativo do tipo de mensagem de pedido.
response_type- Nome totalmente qualificado ou relativo do tipo de mensagem de resposta.
- describe_service(service_class)
-
Cria um descritor a partir de uma classe Service.
Argumentos- service_class
- A classe de serviço a descrever.
Devolve uma instância ServiceDescriptor inicializada que descreve o serviço.
Campos ServiceDescriptor:
name- Nome não qualificado do serviço.
methods- Métodos remotos do Serviço.
- import_descriptor_loader(definition_name, importer=__import__ )
-
Encontra objetos importando módulos conforme necessário. Um carregador de definições é uma função que resolve um nome de definição para um descritor. O localizador de importações resolve as definições para os respetivos nomes importando módulos quando necessário.
Argumentos- definition_name
- Nome da definição a encontrar.
- importer=__import__ )
- Função de importação usada para importar novos módulos.
Devolve um descritor adequado de qualquer tipo descritível localizado por nome.
Gera um DefinitionNotFoundError quando um nome não se refere a uma definição nem a um módulo.