描述符模块函数

descriptor.py 模块包含用于将 Google Protocol RPC 定义转换为可传输的消息格式的消息定义和函数。

描述 Enum 实例、Enum 类、Field 类或 Message 类会生成相应的描述符对象。这些描述符对象是描述其他 Google Protocol RPC 定义(如枚举、消息和服务)的对象。您可以使用此消息将信息传输给那些希望了解枚举值、枚举、字段或消息的描述的客户端,并且无需下载源代码。同时,此格式还与其他非 Python 语言兼容。

描述符被构建为与 https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/descriptor.proto 兼容的二进制数字。

注意!descriptor.py 中定义的类型和字段的名称不必与在 descriptor.proto 中定义的名称相匹配。以这种方式设计 Google Protocol RPC 的目的是使得使用这些描述符的源代码文件更易于阅读。例如,FieldDescriptors 需使用 descriptor.proto(而不是 descriptor.py)中的 TYPE 作为前缀。

以下代码示例演示了如何使用描述符模块来描述使用 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
将被描述为描述符的值。

如果可以将对象描述为描述符,则返回描述符,否则返回无。

describe_enum(enum_definition)

从 Enum 类构建描述符。

参数
enum_value
要描述的 Enum 类。

返回描述 Enum 实例的已初始化的 EnumDescriptor 实例。

EnumDescriptor 类字段:

name
指定的 Enum 的名称,无任何限制。
values
Enum 类定义的值。
describe_enum_value(enum_value)

从 Enum 实例构建描述符。 参数

enum_value
要描述的 Enum 值。

返回描述 Enum 实例的已初始化的 EnumValueDescriptor 实例。

EnumValueDescriptor 类字段:

name
枚举值的名称。
number
枚举值的编号。
describe_field(field_definition)

从 Field 实例构建描述符。

参数
field_definition
要描述的 Field 实例。

返回描述 Field 实例(包含一组枚举和字段)的已初始化 FieldDescriptor 实例。

FieldDescriptor 类枚举:

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 模块构建文件集。

参数
modules
要描述的 Python 模块的迭代。

返回描述模块的已初始化的 FileSet 实例。

FileSet 类字段:

files
文件集中的文件。
describe_message(message_definition)

从 Message 类构建描述符。

参数
message_definition
要描述的 Message 类。

返回描述 Message 类的已初始化的 MessageDescriptor 实例。

MessageDescriptor 类字段:

name
定义所属文件包的完全限定名称。
fields
为消息定义的字段。
message_types
在消息中定义的嵌套 Message 类。
enum_types
在消息中定义的嵌套 Enum 类。
describe_method(method)

从远程服务方法构建描述符。

参数
方法
要描述的远程服务方法。

返回描述远程服务方法的已初始化的 MethodDescriptor 实例。

MethodDescriptor 字段:

name
服务方法的名称。
request_type
请求消息类型的完全限定名称或相对名称。
response_type
响应消息类型的完全限定名称或相对名称。
describe_service(service_class)

从 Service 类构建描述符。

参数
service_class
要描述的 Service 类。

返回描述服务的已初始化的 ServiceDescriptor 实例。

ServiceDescriptor 字段:

name
服务的未限定名称。
methods
Service 的远程方法。
import_descriptor_loader(definition_name, importer=__import__ )

根据需要通过导入模块来查找对象。其中,定义加载程序是一个函数,它将定义名称解析为一个描述符。接着,导入查找程序在必要时利用导入模块将定义解析为其名称。

参数
definition_name
要查找的定义的名称。
importer=__import__ )
用于导入新模块的导入函数。

从按名称定位的任何可描述类型返回相应的描述符。

当名称未引用定义或模块时,抛出 DefinitionNotFoundError