Message 類別

Message 類別用於定義訊息，以便提高整個網路或程序空間中的傳輸效率。訊息可使用欄位類別加以定義。

Message 由 protorpc.messages 模組提供。

簡介

訊息比一般類別受到更多限制，因為它只能包含欄位屬性和其他訊息和列舉定義。實行這些限制是因為 Message 類別本身的結構旨在跨越網路或程序空間傳輸，並由客戶端甚至其他伺服器直接使用。因此，系統無法將結構性資訊隨附於方法和非欄位性質的屬性進行傳輸，因為這樣會造成不同程式語言和實作之間的不一致。

初始化和驗證

如果 Message 物件具有所有必要欄位，且所有巢狀訊息也都已初始化，則該 Message 物件即可視為已初始化。

若未初始化，呼叫「check_initialized」會引發 ValidationError；「is_initialized」會傳回一個布林值來表示是否有效。

Google Protocol RPC 會在建立及填入 Message 物件時自動對這些物件進行驗證。應用程式可使用欄位例項的 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)

將內部訊息的狀態初始化。

應用程式透過建構函式 (透過傳入相符於 field 類別的關鍵字引數) 來初始化訊息。例如：

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

定義類別欄位之後，您可以簡潔地呼叫欄位值。以下兩種叫用方式的效果相同：

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)
取得欄位編號。傳回與該號碼相關聯的欄位物件。
如果找不到該編號的欄位，就會引發 KeyError。

實例方法

Message 執行個體具有以下幾種方法：

check_initialized()
檢查是否已初始化所有必填欄位。
如果 Message 物件未經過初始化，就會引發 ValidationError。
get_assigned_value(name)
取得屬性的指派值。如果尚未設定值，則傳回 None。
引數：
name
要取得的屬性名稱。

傳回指派給某個屬性的值，或如果尚未指派值給該屬性，則傳回 None。

is_initialized(name)
取得 Message 物件的初始化狀態。如果訊息有效，就會傳回 True，否則傳回 False。
reset(name)
會重設欄位的已指派值，重新建立預設值，如果沒有預設值，則會設為 None。
引數：
name
要重設的欄位名稱。