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。