Hinweis: Python 2.7 hat am 31. Januar 2024 das Ende des Supports erreicht. Ihre vorhandenen Python 2.7-Anwendungen werden weiterhin ausgeführt und erhalten Traffic. App Engine kann die erneute Bereitstellung von Anwendungen, die Laufzeiten verwenden, jedoch nach dem Enddatum des Supports blockieren. Wir empfehlen die Migration zur neuesten unterstützten Version von Python.

Funktionen des Moduls "Descriptor"

Das Modul descriptor.py enthält Nachrichtendefinitionen und Funktionen zum Konvertieren von Google Protocol-RPC-Definitionen in ein übertragbares Nachrichtenformat.

Durch die Beschreibung einer Enum-Instanz, Enum-Klasse, Field-Klasse oder Message-Klasse wird ein entsprechendes Deskriptorobjekt erzeugt. Ein Deskriptorobjekt ist ein Objekt, das andere Google Protocol-RPC-Definitionen wie Enums, Nachrichten und Dienste beschreibt. Sie können mit dieser Nachricht Informationen an Clients übermitteln, die die Beschreibung eines Enumerationswerts, einer Enumeration, eines Felds oder einer Nachricht kennen möchten, ohne den Quellcode herunterladen zu müssen. Dieses Format ist auch mit anderen Programmiersprachen als Python kompatibel.

Die Deskriptoren werden so dargestellt, dass sie mit https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/descriptor.proto binär kompatibel sind.

Hinweis! Die Namen der Typen und Felder, die in descriptor.py definiert sind, entsprechen nicht notwendigerweise den Definitionen in descriptor.proto. Google Protocol RPC ist so konzipiert, damit Quellcodedateien, die diese Deskriptoren verwenden, leichter lesbar sind. Ein FieldDescriptor muss beispielsweise in descriptor.proto das Präfix TYPE erhalten, jedoch nicht in descriptor.py.

Das folgende Codebeispiel zeigt die Verwendung des Deskriptormoduls zur Beschreibung einer Klasse namens Pixel mit der Klasse 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)

Das protorpc.descriptor-Paket bietet folgende Funktionen:

describe(value)

Beschreibt jeden beliebigen Wert als Deskriptorobjekt. Sie können mit dieser Hilfsfunktion jedes Objekt mit einem entsprechenden Deskriptorobjekt beschreiben.

Argumente

Wert: Wert für die Beschreibung als Deskriptorobjekt

Gibt ein Deskriptorobjekt zurück, wenn das Objekt als Deskriptor beschreibbar ist. Andernfalls wird "None" zurückgegeben.

describe_enum(enum_definition)

Erstellt einen Deskriptor aus einer Enumerationsklasse.

Argumente

enum_value: Die zu beschreibende Enumerationsklasse

Gibt eine initialisierte EnumDescriptor-Instanz zurück, die die Enumerationsinstanz beschreibt.

Felder der EnumDescriptor-Klasse:

name: Name der angegebenen Enumeration ohne Qualifikationen.
values: Von der Enumerationsklasse definierte Werte

describe_enum_value(enum_value)

Erstellt einen Deskriptor aus einer Enumerationsklasse. Argumente

enum_value: Der zu beschreibende Enumerationswert

Gibt eine initialisierte EnumValueDescriptor-Instanz zurück, die die Enumerationsinstanz beschreibt.

Felder der EnumValueDescriptor-Klasse:

name: Name des Enumerationswerts.
number: Nummer des Enumerationswerts

describe_field(field_definition)

Erstellt eine Beschreibung aus einer Field-Instanz.

Argumente

field_definition: Die zu beschreibende Field-Instanz

Gibt eine initialisierte FieldDescriptor-Instanz zurück, die die Field-Instanz mit einer Liste aus Enumerationen und Feldern beschreibt.

Enumerationen der FieldDescriptor-Klasse:

Variant: Hinweis-Untertypen im Sendeformat für das angegebene Feld.
Label: Werte für optionale, erforderliche und wiederholte Felder

Felder der FieldDescriptor-Klasse:

name: Name des angegebenen Felds.
number: Nummer des angegebenen Felds.
variant: Variante des angegebenen Felds.
type_name: Typname für die Nachrichten- und Enumerationsfelder.
default_value: String-Darstellung des Standardwerts

describe_file(module)

Erstellt eine Datei aus einem angegebenen Python-Modul.

Argumente

module: Das zu beschreibende Python-Modul

Gibt eine initialisierte FileDescriptor-Instanz zurück, die das Modul beschreibt.

Felder der FileDescriptor-Klasse:

package: Voll qualifizierter Name des Pakets, zu dem die Definitionen gehören.
message_types: In der Datei enthaltene Nachrichtendefinitionen.
enum_types: In der Datei enthaltene Enumerationsdefinitionen.
service_types: In der Datei enthaltene Dienstdefinitionen

describe_file_set(modules)

Erstellt eine Dateigruppe aus den angegebenen Python-Modulen.

Argumente

modules: Iterierbares Element des zu beschreibenden Python-Moduls

Gibt eine initialisierte FileSet-Instanz zurück, die das Modul beschreibt.

Felder der FileSet-Klasse:

files: Dateien in der Dateigruppe

describe_message(message_definition)

Erstellt eine Beschreibung aus einer Message-Klasse.

Argumente

message_definition: Die zu beschreibende Message-Klasse

Gibt eine initialisierte MessageDescriptor-Instanz zurück, die die Message-Klasse beschreibt.

Felder der MessageDescriptor-Klasse:

name: Voll qualifizierter Name des Pakets, zu dem die Definitionen gehören.
fields: Für die Nachricht definierte Felder.
message_types: Verschachtelte Message-Klassen, die bei der Nachricht definiert wurden.
enum_types: Verschachtelte Enum-Klassen, die bei der Nachricht definiert wurden

describe_method(method)

Erstellt eine Beschreibung aus einer Remotedienst-Methode.

Argumente

method: Die zu beschreibende Remotedienst-Methode

Gibt eine initialisierte MethodDescriptor-Instanz zurück, die die Remotedienst-Methode beschreibt.

MethodDescriptor-Felder:

name: Name der Dienstmethode.
request_type: Voll qualifizierter Name oder relativer Name des Anforderungsnachrichtentyps.
response_type: Voll qualifizierter oder relativer Name des Antwortnachrichtentyps

describe_service(service_class)

Erstellt eine Beschreibung aus einer Dienstklasse.

Argumente

service_class: Die zu beschreibende Dienstklasse

Gibt eine initialisierte ServiceDescriptor-Instanz zurück, die den Dienst beschreibt.

ServiceDescriptor-Felder:

name: Nicht qualifizierter Name des Dienstes.
methods: Remote-Methoden des Diensts

import_descriptor_loader(definition_name, importer=__import__ )

Findet Objekte, indem nach Bedarf Module importiert werden. Ein Definitions-Loader ist eine Funktion, die einen Definitionsnamen in einen Deskriptor auflöst. Die Importsuche löst Definitionen in ihre Namen auf, indem bei Bedarf Module importiert werden.

Argumente

definition_name: Name der zu suchenden Definition.
importer=__import__ ): Importfunktion für den Import neuer Module

Gibt einen entsprechenden Deskriptor jedes beschreibbaren Typs zurück, der nach Name gefunden wurde.

Löst einen DefinitionNotFoundError aus, wenn sich ein Name weder auf eine Definition noch auf ein Modul bezieht.