附註：強烈建議建構新應用程式的開發人員使用 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 (屬性) 名稱。因為模型類別除了 property 外還有 attribute (無法用於 property)，所以 property 可透過 name 使用保留的 attribute 名稱，以作為在資料儲存庫中的 property 名稱，並為 property attribute 使用不同的名稱。詳情請參閱不允許的屬性名稱一節。
- default
-
屬性預設值。如果沒有設定屬性的值，或將屬性值設為
None，則會將這個值視為預設值。注意：Model 類別定義會與其他應用程式的程式碼一併快取。這包括快取屬性預設值。請勿在模型定義中為要求 (例如
users.get_current_user()) 專屬的資料設定 default。相反地，請針對 Model 類別定義__init__()方法來初始化屬性值。 - required
-
如果為
True，屬性值不可為None。模型執行個體必須將其建構函式中的所有必要屬性初始化，如此才不會建立遺失屬性值的執行個體。嘗試建立執行個體而沒有初始化必要屬性，或嘗試將None指派給必要屬性，將會發出 BadValueError。如果沒有在建構函式中針對具有預設值的必要屬性指定其值，則會使用預設值。不過，您無法將屬性值指派為
None，且指派其他值後，無法自動還原為預設值。您隨時都可以存取 property 的defaultattribute 來取得這個值並明確指派其值。 - validator
- 指派屬性值時為驗證該值而應呼叫的函式。這個函式會將屬性值作為唯一的引數；如果該值無效，就會發出例外狀況。在完成其他驗證 (例如檢查必要屬性具有屬性值) 後才會呼叫指定的驗證工具。當非必要的屬性未有指派值時，就會以引數為
None呼叫驗證工具。 - choices
- 可接受的屬性值清單。如有設定，則無法為屬性指派不在清單中的值。跟 required 以及其他驗證相同，模型執行個體必須透過 choices 初始化所有屬性，如此才不會使用無效值建立執行個體。如果 choices 為
None，則接受所有值，否則會接受通過驗證的值。 - indexed
-
指定這個屬性是否應包含在由開發人員定義的內建索引。如果為
False，則排序或篩選這個屬性的查詢就絕不會傳回寫入到資料儲存庫的實體，這點跟 Blob 和 Text 屬性類似。附註：每個已建立索引的屬性都會增加少量負擔與 CPU 成本，並造成
put()與delete()呼叫延遲。如果您從來不需要篩選或排序屬性，請考慮使用indexed=False來避免增加負擔。但請千萬小心！如果您之後還是決定要建立屬性索引，改回indexed=True僅會影響之後的寫入。原先使用indexed=False寫入的實體不會重新建立索引。
類別屬性
Property 類別的子類別會定義下列類別屬性 (attribute)：
data_type- 屬性 (property) 接受為 Python 原生值的 Python 資料類型或類別。
執行個體方法
Property 類別的執行個體方法如下：
- default_value()
-
傳回屬性的預設值。基本實作會採用傳送到建構函式的 default 引數值。屬性類別可覆寫這項設定以提供特殊的預設值行為，例如 DateTimeProperty 的 auto-now 功能。
- validate(value)
-
屬性的完整驗證常式。如果 value 為有效值，則會以原封不動方式傳回這個值，或將其修改為必要類型傳回。如果不是，會發出適用的例外狀況。
基本實作會檢查 value 並非
None(如為必要，即基本 Property 建構函式的 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 原生表示法。基本實作僅會傳回該值。屬性類別可覆寫這個設定，為模型執行個體使用不同於資料儲存庫所用的資料類型。
