Property 類別

Property 類別是資料模型定義的超級類別。Property 類別定義屬性值的類型、值的驗證方式、以及值儲存在資料存放區的方式。

Property 是由 google.appengine.ext.db 模組所提供。

• 簡介
• Property()
• 類別屬性 (attribute)：
  • Property.data_type
• 實例方法：
  • default_value()
  • validate()
  • empty()
  • get_value_for_datastore()
  • make_value_from_datastore()

簡介

屬性類別描述值類型、預設值、驗證邏輯以及其他 Model 屬性的功能。每個屬性類別都是 Property 類別的子類別。Datastore API (資料存放區 API) 包括每個資料存放區值類型的屬性類別，以及一些提供資料存放區類型其他功能的屬性類別。請參閱類型和 Property 類別。

屬性類別可以接受從引數傳遞到建構函式的設定。基礎類別建構函式支援幾個引數，所有屬性類別通常都支援這些引數，包括資料存放區 API 中所提供的所有屬性類別。這種設定可以包括預設值，不論是否需要明確的值、可接受值的清單、以及自訂的驗證邏輯。要進一步了解如何設定某屬性，請參閱針對該屬性類型的文件。

屬性類別定義資料存放區屬性的模型。它不包含模型實例的屬性值。Property 類別的實例隸屬於 Model 類別，而非 Property 類別的實例。以 Python 的方式來說明，屬性類別實例就是「描述元」，可以自訂 Model 實例屬性 (attribute) 的行為方式。請參閱 Python 文件以取得關於描述元的詳細資訊。

建構函式

Property 基礎類別的建構函式定義如下：

class Property(verbose_name=None, name=None, default=None, required=False, validator=None, choices=None)

模型屬性定義的超級類別。

引數：

verbose_name

方便使用的屬性名稱。這必須是屬性建構函式的第一個引數。djangoforms 程式庫用它做為表格欄位的標籤，而其他的可能將它做為類似的目的。

name

屬性用於查詢的儲存名稱。這是屬性所使用的預設屬性 (attribute) 名稱。因為除了 property 之外，模型類別還具有 attribute (不能用於 property)，所以 property 可以使用 name，來使用保留的 attribute 名稱做為資料存放區中的 property 名稱，並讓 property attribute 使用不同的名稱。請參閱不允許的屬性名稱以取得詳細資訊。

default

屬性的預設值。若屬性值沒有指定值，或者指定值為 None，則該值會視為預設值。

注意：Model 類別定義會與應用程式碼的其他部分一起快取。這包括快取屬性的預設值。請勿將模型定義中的 default 設定為特定要求的資料 (例如 users.get_current_user())。而是要為 Model 類別定義 __init__() 方法，該類別會初始化屬性值。

required

若為 True，則屬性值不能為 None。 模型實例必須在其建構函式中，初始化所有必要的屬性，讓建立的實例不會有錯誤的值。 嘗試建立沒有初始化必要屬性的實例，或嘗試指派必要屬性為 None，會引發 BadValueError。

若建構函式中沒有指定預設值，則必要而且具有預設值的屬性，將會使用預設值。不過，屬性不能指派 None 值，而且指派其他值之後，沒有自動的方式可以還原預設值。您可以存取屬性的 default 屬性 (attribute)，以取得此值，並明確地指派。

validator

指派屬性值時，要驗證該值所呼叫的函式。函式只會以引數接受該值，若該值無效則會引發例外狀況。在其他驗證發生之後，會呼叫指定的驗證程式，例如檢查必要的屬性是否有值。

choices

可接受的屬性值清單。若有設定，則不能指派清單以外的屬性值。如同 required 和其他驗證一樣，模型實例必須以 choices 初始化所有屬性，讓建立的實例不會有無效值。若 choices 為 None，則所有值皆可通過驗證而成為可接受的值。

Class 屬性 (attribute)

Property 類別的子類別定義下列類別屬性 (attribute)：

data_type

Python 資料類型或類別屬性接受為 Python 的原生值。

實例方法

Property 類別實例具有下列方法：

default_value()

傳回屬性的預設值。基礎實作使用 default 引數的值傳遞給建構函式。屬性類別可以覆寫本項，以提供特殊的預設值行為，例如 DateTimeProperty 自動使用目前日期、時間的功能。

validate(value)

完整的屬性驗證常式。若 value 是有效值，則會傳回該值，可能會變更為必要的類型，或保持不變。否則，它會引發適當的例外狀況。

在必要情況下 (基礎 Property 建構函式的 required 引數)，基礎實作會檢查 value 不是 None，若屬性有設定選項 (即 choices 引數)，以及值能夠通過自訂驗證程式 (若有的話，即 validator 引數)，則值是有效選項之一。

使用屬性類型的模型具現化 (使用預設或初始化的值)、以及類型的屬性得到指派的值時，會呼叫驗證常式。常式不應有其他副作用。

empty(value)

若 value 對此屬性類型來說是空白值的話，則傳回 True。基礎實作等同於 not value，對大部分的類型而言已經足夠。其他類型 (例如 Boolean 類型) 可以用更適當的測試來覆寫此方法。

get_value_for_datastore(model_instance)

傳回此屬性應該以指定模型實例儲存在資料存放區中的值。 基礎實作只會傳回屬性在模型實例中的 Python 原生值。屬性類別可以覆寫此項，為資料存放區使用與模型實例不同的資料類型，或者在儲存模型實例之前執行其他資料轉換。

make_value_from_datastore(value)

傳回來自資料存放區指定值的 Python 原生代表。基礎實作只會傳回值。屬性類別可以覆寫此項，為資料存放區使用與模型實例不同的資料類型。