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())。相反地，請針對 Model 類別定義 __init__() 方法，以便初始化屬性值。

必填

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

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

驗證器

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

choices

屬性可接受的值清單。如有設定，則無法為屬性指派不在清單中的值。與required和其他驗證一樣，模型執行個體必須使用選項初始化所有屬性，以免使用無效值建立執行個體。如果 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 為有效值，則會以原封不動方式傳回這個值，或將其修改為必要類型傳回。如果不是，會發出適用的例外狀況。

基礎實作會檢查 value 是否為 None (如果需要，則為基礎屬性建構函式的 required 引數)，如果屬性已使用選項進行設定，則值為有效選項之一 (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 原生表示法。基本實作僅會傳回該值。屬性類別可覆寫這個設定，為模型執行個體使用不同於資料儲存庫所用的資料類型。