描述元模組函式

descriptor.py 模組包含訊息定義與函式，用於將 Google Protocol RPC 定義轉換為可傳輸的訊息格式。

描述 Enum 執行個體、Enum 類別、Field 類別或 Message 類別後，即可產生適當的描述元物件。描述元物件是一個用來描述其他 Google RPC 定義 (例如 Enum、訊息以及服務) 的物件。您可以使用這項訊息，將資訊傳送給想要知道 Enum 值、Enum、欄位或訊息之描述的用戶端，而不需要下載原始碼。這種格式也與其他非 Python 的程式語言相容。

描述符的模擬方式與 https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/descriptor.proto 的二進位相容

注意！descriptor.py 中定義的類型和欄位名稱不一定與 descriptor.proto 中定義的名稱相符。Google Protocol RPC 以這種方式設計，讓使用這些描述元的原始碼更便於閱讀。舉例來說，在 descriptor.proto 中，欄位描述元需要在前方加上 TYPE，但在 descriptor.py 中則不需要。

下列程式碼範例示範如何使用描述元模組，使用 MessageDescriptor 類別描述名為 Pixel 的類別。

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)

protorpc.descriptor 套件提供下列函式：

describe(value)

將任何值描述為描述元。您可以使用這個輔助程式函式來描述任何具有適當描述元物件的物件。

引數
value
要描述為描述符的值。

如果該物件可描述為描述元，就傳回其描述元，否則傳回 None。

describe_enum(enum_definition)

從 Enum 類別中建立描述元。

引數
enum_value
要描述的列舉類別。

傳回已初始化的 EnumDescriptor 執行個體，描述 Enum 執行個體。

EnumDescriptor 類別的欄位包括：

name
指定的列舉名稱，不含任何限定條件。
values
由 Enum 類別定義的值。
describe_enum_value(enum_value)

根據 Enumerator 例項建構描述元。引數

enum_value
要說明的列舉值。

傳回已初始化的 EnumValueDescriptor 執行個體，描述 Enum 執行個體。

EnumValueDescriptor 類別的欄位包括：

name
列舉值的名稱。
number
列舉值的數字。
describe_field(field_definition)

從 Field 執行個體中建立描述元。

引數
field_definition
要描述的欄位例項。

傳回已初始化的 FieldDescriptor 執行個體，描述 Field 執行個體，並附上 Enum 和欄位的清單。

FieldDescriptor 類別的 Enum 包括：

Variant
指定欄位的線路格式提示子類型。
Label
選用、必填和重複欄位的值。

FieldDescriptor 類別的欄位包括：

name
指定欄位的名稱。
number
指定欄位的編號。
variant
指定欄位的變化版本。
type_name
輸入訊息和列舉欄位的名稱。
default_value
預設值的字串表示法。
describe_file(module)

從所指定的 Python 模組中建立檔案。

引數
module
要說明的 Python。

傳回已初始化的 FileDescriptor 執行個體，描述模組。

FileDescriptor 類別的欄位包括：

package
定義所屬套件的完整名稱。
message_types
檔案中包含的訊息定義。
enum_types
檔案中包含的列舉定義。
service_types
檔案中包含的服務定義。
describe_file_set(modules)

從所指定的 Python 模組中建立檔案集。

引數
模組
要說明的 Python 模組可枚舉項目。

傳回已初始化的 FileSet 執行個體，描述模組。

FileSet 類別的欄位包括：

files
檔案集中的檔案。
describe_message(message_definition)

從 Message 類別中建立描述元。

引數
message_definition
要描述的 Message 類別。

傳回已初始化的 MessageDescriptor 執行個體，描述 Message 執行個體。

MessageDescriptor 類別的欄位包括：

name
定義所屬套件的完整名稱。
fields
為訊息定義的欄位。
message_types
在訊息上定義的巢狀訊息類別。
enum_types
在訊息中定義的巢狀列舉類別。
describe_method(method)

從遠端服務方法中建立描述元。

引數
method
要說明的遠端服務方法。

傳回已初始化的 MethodDescriptor 執行個體，描述遠端服務方法。

MethodDescriptor 的欄位包括：

name
服務方法的名稱。
request_type
要求訊息類型的完整名稱或相對名稱。
response_type
回應訊息類型的完整合格名稱或相對名稱。
describe_service(service_class)

從 Service 類別中建立描述元。

引數
service_class
要描述的服務類別。

傳回已初始化的 ServiceDescriptor 執行個體，描述服務。

ServiceDescriptor 的欄位包括：

name
未限定的服務名稱。
methods
服務的遠端方法。
import_descriptor_loader(definition_name, importer=__import__ )

視需要匯入模組，藉以尋找物件。定義載入器屬於函式，可將定義名稱解析至描述元。匯入尋找器可視需要匯入模組，以將定義解析至其名稱。

引數
definition_name
要查找的定義名稱。
importer=__import__ )
用於匯入新模組的匯入函式。

從任何按名稱找到的可描述類型，傳回適當的描述元。

當名稱不是以定義或模組為主時，則引發 DefinitionNotFoundError。