Property 類別

附註：我們強烈建議建構新應用程式的開發人員使用 NDB 用戶端程式庫，因為 NDB 用戶端程式庫與本用戶端程式庫相較之下有幾個優點，例如能透過 Memcache API 自動將實體加入快取。如果您目前使用的是舊版的 DB 用戶端程式庫，請參閱從 DB 至 NDB 的遷移指南。

Property 類別是資料模型屬性定義的父類別。Property 類別可定義屬性值的類型、屬性值的驗證方式，以及屬性值儲存在資料儲存庫中的方式。

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

簡介

屬性類別說明 Model 屬性的值類型、預設值、驗證邏輯及其他功能。每個屬性類別都是 Property 類別的子類別。資料儲存庫 API 包含各個資料儲存庫值類型的屬性類別，以及在資料儲存庫類型之上提供額外功能的其他屬性類別。請參閱「類型和 Property 類別」。

屬性類別可接受透過引數傳送給建構函式的設定。基本類別建構函式支援所有屬性類別通常都會支援的多個引數，包括資料儲存庫 API 中提供的所有引數。這些設定可包含預設值 (無論是否需要為明確值)、可接受的值清單，以及自訂驗證邏輯。如需更多關於設定屬性的資訊，請參閱特定屬性類型的說明文件。

屬性類別可定義資料儲存庫屬性的模型。它不包含模型執行個體的屬性值。Property 類別的執行個體屬於 Model 類別，而非該類別的執行個體。就 Python 而言，屬性 (property) 類別執行個體為自訂 Model 執行個體屬性 (attribute) 行為的「描述元」。如要進一步瞭解描述元的相關資訊，請參閱 Python 說明文件。

建構函式

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

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

模型屬性定義的父類別。

引數

verbose_name

屬性的易記名稱。規定必須為屬性建構函式的第一個引數。djangoforms 程式庫會使用這項資訊為表單欄位建立標籤，其他人也可以用於類似用途。

name

屬性的儲存空間名稱，用於查詢。預設為 property (屬性) 使用的 attribute (屬性) 名稱。由於模型類別具有屬性以外的屬性 (無法用於屬性)，因此屬性可以使用 name，將保留的屬性名稱做為資料儲存庫中的屬性名稱，並為屬性屬性使用不同的名稱。詳情請參閱「不允許的屬性名稱」。

預設

屬性預設值。如果屬性值從未獲得值，或獲得 None 值，則該值會視為預設值。

注意：Model 類別定義會與其他應用程式的程式碼一併快取。這包括快取屬性預設值。請勿在模型定義中，使用要求專屬資料 (例如 users.get_current_user()) 設定 default。請改為針對 Model 類別定義 __init__() 方法，初始化屬性值。

required

如果 True，屬性值不得為 None。模型執行個體必須將其建構函式中的所有必要屬性初始化，如此才不會建立遺失屬性值的執行個體。嘗試建立執行個體而沒有初始化必要屬性，或嘗試將 None 指派給必要屬性，將會發出 BadValueError。

如果沒有在建構函式中針對具有預設值的必要屬性指定其值，則會使用預設值。不過，屬性無法指派 None 值，且指派其他值後，無法自動還原為預設值。您隨時可以存取屬性的 default 屬性來取得這個值，並明確指派該值。

驗證器

：指派值時應呼叫的函式，用於驗證屬性的值。這個函式會將屬性值作為唯一的引數；如果該值無效，就會發出例外狀況。在完成其他驗證 (例如檢查必要屬性具有屬性值) 後才會呼叫指定的驗證工具。如果未為非必要屬性提供值，系統會使用 None 引數呼叫驗證工具。

選擇

屬性的可接受值清單。如有設定，則無法為屬性指派不在清單中的值。與必要和其他驗證一樣，模型執行個體必須使用選項初始化所有屬性，這樣執行個體才不會以無效值建立。如果 choices 為 None，則接受所有值，否則會接受通過驗證的值。

已建立索引

指定這個屬性是否應包含在由開發人員定義的內建索引。如果為 False，則排序或篩選這個屬性的查詢就絕不會傳回寫入到資料儲存庫的實體，這點跟 Blob 和 Text 屬性類似。

注意：每個已建立索引的屬性都會增加少量負擔與 CPU 成本，並造成 put() 和 delete() 呼叫延遲。如果您永遠不需要篩選或排序屬性，請考慮使用 indexed=False，避免這類額外負擔。但請千萬小心！如果您之後決定要將屬性編入索引，改回 indexed=True 只會影響該時間點之後的寫入作業。系統不會重新為原本以 indexed=False 寫入的實體建立索引。

類別屬性

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

data_type

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

執行個體方法

Property 類別的執行個體方法如下：

default_value()

傳回屬性的預設值。基本實作會採用傳送到建構函式的 default 引數值。屬性類別可以覆寫這項設定，提供特殊的預設值行為，例如 DateTimeProperty 的自動設定為目前時間功能。

validate(value)

屬性的完整驗證常式。如果 value 為有效值，則會以原封不動方式傳回這個值，或將其修改為必要類型傳回。如果不是，會發出適用的例外狀況。

如果需要 (基本 Property 建構函式的 required 引數)，基本實作會檢查 value 是否為 None；如果屬性已設定選項 (choices 引數)，則值是否為有效選項之一；以及值是否通過任何自訂驗證器 (validator 引數)。

(使用預設或初始化的值) 實例化使用屬性類型的模型時，以及為類型的屬性指派值時，會呼叫這個驗證常式。這個常式不應帶來任何副作用。

empty(value)

如果這個屬性類型的值視為空白值，則傳回 True。基本實作方式等同於 not value，足以應付大多數型別。布林值等其他類型則可使用更適當的測試來覆寫這個方法。

get_value_for_datastore(model_instance)

針對指定模型執行個體中的這個屬性，傳回應儲存在資料儲存庫中的值。基本實作會針對模型執行個體中的屬性，僅傳回 Python 原生值。屬性類別可覆寫這個設定，為資料儲存庫使用不同於模型執行個體所用的資料類型，或在儲存模型執行個體前執行其他資料轉換。

make_value_from_datastore(value)

從資料儲存庫傳回指定值的 Python 原生表示法。基本實作僅會傳回該值。屬性類別可覆寫這個設定，為模型執行個體使用不同於資料儲存庫所用的資料類型。

make_value_from_datastore_index_value(value)

從資料儲存庫索引中傳回指定值的 Python 原生表示法。基本實作僅會傳回該值。屬性類別可覆寫這個設定，為模型執行個體使用不同於資料儲存庫所用的資料類型。