注: Python 2.7 は、2024 年 1 月 31 日にサポートが終了しました。既存の Python 2.7 アプリケーションは引き続き実行され、トラフィックを受信します。ただし、サポート終了日を過ぎると、ランタイムを使用するアプリケーションの再デプロイが App Engine によってブロックされることがあります。サポートされている最新バージョンの Python に移行することをおすすめします。

Message クラス

Message クラスは、ネットワークまたは処理空間全体で効率的に伝達されるようにメッセージを定義するために使用されます。メッセージはフィールドクラスを使用して定義されます。

Message は protorpc.messages モジュールによって提供されます。

はじめに

Message は、フィールド属性と、他の Message や Enum の定義のみを含むことができるという点で、通常のクラスよりも制限されています。このような制限が設けられているのは、Message クラスの構造そのものを、ネットワークまたは処理空間で転送し、クライアントで、または別のサーバーでも直接使用することを意図としているためです。そのため、言語と実装の相違により矛盾が発生することから、メソッドとフィールド以外の属性を構造情報とともに転送することはできません。

初期化と検証

Message オブジェクトにすべての必須フィールドがあり、ネストされたメッセージもすべて初期化されている場合、その Message オブジェクトは初期化済みとみなされます。

初期化されていない状態で check_initialized を呼び出すと、ValidationError が発生します。is_initialized は、オブジェクトが有効であるかどうかを示すブール値を返します。

Google プロトコル RPC は、Message オブジェクトが作成され、移入されると自動的に検証します。アプリケーションでは、指定した値が代入先のフィールドと互換性があるかどうかを Field インスタンスの validate() メソッドを使用して検証できます。このメソッドをメッセージに対して使用すると、メッセージのすべての値とそのサブメッセージが有効かどうかがチェックされます。フィールドに無効な値を代入すると ValidationError を送出します。

次の例では、架空の株取引アプリケーションで Message オブジェクトを作成、初期化しています。

from protorpc import messages

# Trade type.
class TradeType(messages.Enum):
    BUY = 1
    SELL = 2
    SHORT = 3
    CALL = 4

class Lot(messages.Message):
    price = messages.IntegerField(1, required=True)
    quantity = messages.IntegerField(2, required=True)

class Order(messages.Message):
    symbol = messages.StringField(1, required=True)
    total_quantity = messages.IntegerField(2, required=True)
    trade_type = messages.EnumField(TradeType, 3, required=True)
    lots = messages.MessageField(Lot, 4, repeated=True)
    limit = messages.IntegerField(5)

order = Order(symbol='GOOG',
              total_quantity=10,
              trade_type=TradeType.BUY)

lot1 = Lot(price=304,
           quantity=7)

lot2 = Lot(price=305,
           quantity=3)

order.lots = [lot1, lot2]

# Now object is initialized!
order.check_initialized()

コンストラクタ

Message クラスのコンストラクタは次のように定義されます:

class Message(**kwargs)

メッセージの内部状態を初期化します。

アプリケーションは、フィールドクラスに対応するキーワード引数を渡すことで、コンストラクタを介してメッセージを初期化します。次に例を示します。

class Date(Message)
    day = IntegerField(1)
    month = IntegerField(2)
    year = IntegerField(3)

クラスフィールドを定義したら、フィールド値を正確に呼び出すことができます。次の 2 つの呼び出しは同等です:

date = Date(day=6, month=6, year=1911)

これは次と同等です:

date = Date()
date.day = 6
date.month = 6
date.year = 1911

クラスメソッド

Message クラスには、次のクラスメソッドがあります:

all_fields(): すべてのフィールド定義オブジェクトを取得します。すべての値に対するイテレータを順不同で返します。
field_by_name(name): フィールドを名前で取得します。名前に関連付けられた Field オブジェクトを返します。; 指定された名前のフィールドが見つからない場合は KeyError を送出します。
field_by_number(number): フィールドを数値で取得します。数値に関連付けられた Field オブジェクトを返します。; 指定された数値のフィールドが見つからない場合は KeyError を送出します。

インスタンスメソッド

メッセージインスタンスには、次のメソッドがあります。

check_initialized()

すべての必須フィールドが初期化されているかどうかをチェックします。

Message オブジェクトが初期化されていない場合は、ValidationError を送出します。

get_assigned_value(name)

属性に設定された値を取得します。値が設定されていない場合は None を返します。

引数:

name: 取得する属性の名前。

属性に設定された値を返します。属性に値が設定されていない場合は None を返します。

is_initialized(name)

Message オブジェクトの初期化ステータスを取得します。メッセージが有効であれば True、有効でなければ False を返します。

reset(name)

フィールドに割り当てられた値をリセットします。つまり、デフォルト値が再設定されます。デフォルト値がない場合は None が設定されます。

引数:

name: リセットするフィールドの名前。