記述子モジュール関数

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 では先頭に 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
記述する 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 クラスの 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 モジュールからファイルセットを構築します。

引数
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)

リモート サービス メソッドから記述子を構築します。

引数
method
記述するリモート サービス メソッド。

リモート サービス メソッドを記述する初期化済みの MethodDescriptor インスタンスを返します。

MethodDescriptor のフィールド:

name
サービス メソッドの名前。
request_type
リクエスト メッセージ型の完全修飾名または相対名。
response_type
レスポンス メッセージ型の完全修飾名または相対名。
describe_service(service_class)

Service クラスから記述子を構築します。

引数
service_class
記述する Service クラス。

サービスを記述する初期化済みの ServiceDescriptor インスタンスを返します。

ServiceDescriptor のフィールド:

name
Service の非修飾名。
methods
Service のリモート メソッド
import_descriptor_loader(definition_name, importer=__import__ )

必要に応じてモジュールのインポートによりオブジェクトを検索します。定義ローダーは、定義名を記述子に変える関数です。インポート ファインダーは、必要に応じてモジュールのインポートにより定義を名前に変えます。

引数
definition_name
検索する定義の名前。
importer=__import__ )
新しいモジュールのインポートに使用するインポート関数。

名前で特定した任意の記述可能な型から適切な記述子を返します。

名前が定義またはモジュールのいずれも参照していない場合、DefinitionNotFoundError を送出します。