類型和 Property 類別

附註：強烈建議建構新應用程式的開發人員使用 NDB 用戶端程式庫，相較於此用戶端程式庫，NDB 用戶端程式庫有幾項優點，例如能透過 Memcache API 自動快取實體。如果您目前使用的是舊版 DB 用戶端程式庫，請參閱 DB 至 NDB 遷移指南

App Engine Datastore 支援一組固定的資料實體屬性值類型。 Property 類別可定義要轉換至基本值類型，或是從基本值類型轉換而來的新類型，且這種值類型可直接搭配 Expando 動態屬性和 ListProperty 匯總屬性模型來使用。

下表列出值會直接對應到基礎資料類型的 Property 類別。這些值類型均可使用在 Expando 動態屬性或是 ListProperty 匯總類型上。

Property 類別	值類型	排序順序
IntegerProperty	int long (64 位元)	數字
FloatProperty	float	數字
BooleanProperty	bool	False < True
StringProperty	str unicode	Unicode (str 當成 ASCII 文字處理)
TextProperty	db.Text	無
ByteStringProperty	ByteString	位元組順序
BlobProperty	db.Blob	無
DateProperty TimeProperty DateTimeProperty	datetime.date datetime.time datetime.datetime	依時間順序
GeoPtProperty	db.GeoPt	依照緯度、 經度的順序
PostalAddressProperty	db.PostalAddress	Unicode
PhoneNumberProperty	db.PhoneNumber	Unicode
EmailProperty	db.Email	Unicode
UserProperty	users.User	電子郵件地址 (以 Unicode 順序)。請注意，根據 UserProperty 類別說明下方的附註，請盡量避免使用 UserProperty。
IMProperty	db.IM	Unicode
LinkProperty	db.Link	Unicode
CategoryProperty	db.Category	Unicode
RatingProperty	db.Rating	數字
ReferenceProperty SelfReferenceProperty	db.Key	按路徑元素 (種類、ID、 種類、ID...)
blobstore.BlobReferenceProperty	blobstore.BlobInfo	位元組順序
ListProperty StringListProperty	支援類型的 list	如為遞增，從最小的元素遞增； 如為遞減，從最大的元素遞減

資料儲存庫值類型

下列類型為 Datastore 實體可能的屬性值。請參閱前文中與 Model 定義搭配使用的 Property 類別對應清單。

除了 Python 標準類型和 users.User 之外，在此章節提到的其他所有類別皆由 google.appengine.ext.db 模組提供。

str 或 unicode

一個短字串 (不得超過 1500 位元組)。

系統會將 str 值認定為使用 ascii 轉碼器編碼而成的文字，且會在儲存值之前轉換成 unicode 值。資料儲存庫會將該值當成 unicode 值傳回。至於使用其他轉碼器的短字串，則使用 unicode 值。

資料儲存庫會將短字串建立索引，可用於篩選器和排序順序。如果是超過 1500 個位元組的文字字串 (且未建立索引)，請使用 Text 例項。如果是超過 1500 個位元組且未經編碼的位元組字串 (也未建立索引)，則使用 Blob 例項。如果是應建立索引，且不超過 1500 個位元組的未經編碼非文字位元組字串 (非字元)，則使用 ByteString 例項。

「模型屬性」：StringProperty

bool

布林值 (True 或 False)。

「模型屬性」：BooleanProperty

int 或 long

整數值，最多 64 位元。

儲存之前，Python int 值會轉換成 Python long 值。以 int 所儲存的資料值會當做 long 傳回。

如果指派的 long 超過 64 位元，則系統只會儲存最低有效的 64 位元。

「模型屬性」：IntegerProperty

float

浮點數。

「模型屬性」：FloatProperty

datetime.datetime

日期和時間。請參閱 datetime 模組說明文件。

如果 datetime 值具有 tzinfo 屬性，則會轉換成世界標準時間時區來儲存。資料儲存庫傳回的值為世界標準時間，包含 None 的 tzinfo。如果是需要特定時區的日期時間值的應用程式，則必須在更新值時正確設定 tzinfo，並於存取值時，將值轉換到該時區。

部分程式庫會使用 TZ 環境變數來控制套用到日期時間值上的時區。App Engine 會將此環境變數設為 "UTC"。請注意，在應用程式中變更此變數，並不會更改某些日期時間函式的行為，因為對環境變數的變更無法在 Python 程式碼之外顯示出來。

如果只是要將值轉換成為特定時區，或是轉換特定時區的值，請採用自訂 datetime.tzinfo 來轉換資料儲存庫中的值。

import datetime
import time

class Pacific_tzinfo(datetime.tzinfo):
    """Implementation of the Pacific timezone."""
    def utcoffset(self, dt):
        return datetime.timedelta(hours=-8) + self.dst(dt)

    def _FirstSunday(self, dt):
        """First Sunday on or after dt."""
        return dt + datetime.timedelta(days=(6-dt.weekday()))

    def dst(self, dt):
        # 2 am on the second Sunday in March
        dst_start = self._FirstSunday(datetime.datetime(dt.year, 3, 8, 2))
        # 1 am on the first Sunday in November
        dst_end = self._FirstSunday(datetime.datetime(dt.year, 11, 1, 1))

        if dst_start <= dt.replace(tzinfo=None) < dst_end:
            return datetime.timedelta(hours=1)
        else:
            return datetime.timedelta(hours=0)
    def tzname(self, dt):
        if self.dst(dt) == datetime.timedelta(hours=0):
            return "PST"
        else:
            return "PDT"

pacific_time = datetime.datetime.fromtimestamp(time.mktime(utc_time.timetuple()), Pacific_tzinfo())

請參閱 datetime 模組說明文件 (包含 datetime.tzinfo)。另請參閱第三方模組 pytz，但請注意 pytz 發布內有許多檔案。

DateTimeProperty 模型屬性類別含有許多功能，例如可自動使用儲存模型執行個體的日期與時間。這些屬於模型功能，不可用於原始資料儲存庫值 (例如在 Expando 動態屬性中)。

「模型屬性」：DateTimeProperty、DateProperty、TimeProperty

list

一份值清單，每個值都是其中一種支援的資料類型。

將 list 當做 Expando 動態屬性的值使用時，不可為空白清單。這是因為值清單的儲存方式的緣故：當清單屬性沒有任何項目時，資料儲存庫中也會沒有內容可以呈現。您可以使用靜態屬性和 ListProperty 類別來代表屬性的空清單值。

「模型屬性」：ListProperty

db.Key

另一個資料儲存庫實體的鍵。

附註：金鑰字串上限為 1500 個位元組。

m = Employee(name="Susan", key_name="susan5")
m.put()
e = Employee(name="Bob", manager=m.key())
e.put()

m_key = db.Key.from_path("Employee", "susan5")
e = Employee(name="Jennifer", manager=m_key)

「模型屬性」：ReferenceProperty、SelfReferenceProperty

blobstore.BlobKey

Blobstore 值的鍵，在上傳此值時由 Blobstore 產生。

「模型屬性」：blobstore.BlobReferenceProperty

users.User

Google 帳戶使用者。

如果使用者變更了電子郵件地址，資料儲存庫中的 user.User 值不會更新。因此，強烈建議您避免將 users.User 當做 UserProperty 值儲存，因為其中含有電子郵件地址和專屬 ID。如果使用者變更了電子郵件地址，但您還是使用先前儲存的 user.User 來與新的 user.User 值進行比較時，兩者將不相符。請改為使用 user.User 值的 user_id() 做為該使用者的穩定專屬 ID。

「模型屬性」：UserProperty

class Blob(arg=None)

二進位資料，以位元組字串為格式。此為內建 str 類型的子類別。

Blob 屬性沒有建立索引，而且無法用於篩選器或排序順序。

Blob 用於圖片等二進位資料，會採用 str 值，但是此值會作為位元組字串來儲存，且不會編碼為文字，對於大型文字資料請使用 Text 例項。

「模型屬性」：BlobProperty

class MyModel(db.Model):
    blob = db.BlobProperty()

m = MyModel()
m.blob = db.Blob(open("image.png", "rb").read())

在 XML 中，無論 Blob 是否包含二進位資料，都是以 Base-64 編碼。

class ByteString(arg)

短 blob 值 (即「位元組字串」)，不得超過 1500 個位元組。ByteString 是 str 的子類別，採用未編碼的 str 值做為建構函式的引數。

ByteStrings 由資料儲存庫建立索引，可用於篩選器和排序順序。如果是超過 1500 個位元組的位元組字串 (且未建立索引)，會使用 Blob 例項。如果是編碼文字資料，會使用 str (簡短且已建立索引) 或 Text (較長且未建立索引)。

「模型屬性」：ByteStringProperty

class Text(arg=None, encoding=None)

長字串。這是內建 unicode 類型的子類別。

arg 為 unicode 或 str 值。如果 arg 是 str，會使用 encoding 指定的編碼進行剖析；如果未指定編碼，則為 ascii。如需可能的編碼值，請參閱標準編碼清單。

不同於簡單的 str 或 unicode 的實體屬性值，Text 屬性可超過 1500 位元組的長度。然而，Text 屬性並未編入索引，且無法用於篩選器或排序順序。

「模型屬性」：TextProperty

class MyModel(db.Model):
    text = db.TextProperty()

m = MyModel()
m.text = db.Text(u"kittens")

m.text = db.Text("kittens", encoding="latin-1")

class Category(tag)

一種類別或是「標記」，這是內建 unicode 類型的子類別。

「模型屬性」：CategoryProperty

class MyModel(db.Model):
    category = db.CategoryProperty()

m = MyModel()
m.category = db.Category("kittens")

在 XML 中，這是 Atom Category 元素。

class Email(email)

電子郵件地址，這是內建 unicode 類型的子類別。

屬性類別或值類別都不會執行電子郵件地址驗證，只會儲存值。

「模型屬性」：EmailProperty

class MyModel(db.Model):
    email_address = db.EmailProperty()

m = MyModel()
m.email_address = db.Email("[e-mail]")

在 XML 中，這是 gd:email 元素。

class GeoPt(lat, lon=None)

由浮點經緯度座標呈現的地理點。

「模型屬性」：GeoPtProperty

在 XML 中，這是 georss:point 元素。

class IM(protocol, address=None)

即時通訊控制代碼。

「protocol」是即時通訊服務的標準網址，以下為可能的值：

通訊協定	說明
sip	SIP/SIMPLE
xmpp	XMPP/Jabber
http://aim.com/	AIM
http://icq.com/	ICQ
http://messenger.msn.com/	MSN Messenger
http://messenger.yahoo.com/	Yahoo Messenger
http://sametime.com/	Lotus Sametime
http://gadu-gadu.pl/	Gadu-Gadu
不明	未知或未指定

「address」是控制代碼的地址。

「模型屬性」：IMProperty

class MyModel(db.Model):
    im = db.IMProperty()

m = MyModel()
m.im = db.IM("http://example.com/", "Larry97")

在 XML 中，這是 gd:im 元素。

class Link(link)

一個完整網址，這是內建 unicode 類型的子類別。

「模型屬性」：LinkProperty

class MyModel(db.Model):
    link = db.LinkProperty()

m = MyModel()
m.link = db.Link("http://www.google.com/")

在 XML 中，這是 Atom Link 元素。

class PhoneNumber(phone)

一組使用者可判讀的電話號碼。這是內建 unicode 類型的子類別。

「模型屬性」：PhoneNumberProperty

class MyModel(db.Model):
    phone = db.PhoneNumberProperty()

m = MyModel()
m.phone = db.PhoneNumber("1 [phone]")

在 XML 中，這是 gd.phoneNumber 元素。

class PostalAddress(address)

一個郵寄地址，這是內建 unicode 類型的子類別。

「模型屬性」：PostalAddressProperty

class MyModel(db.Model):
    address = db.PostalAddressProperty()

m = MyModel()
m.address = db.PostalAddress("1600 Ampitheater Pkwy., Mountain View, CA")

在 XML 中，這是 gd:postalAddress 元素。

class Rating(rating)

一個由使用者提供的內容片段評分，為 0 到 100 之間的整數。這是內建 long 類型的子類別。此類別會驗證該值是否為 0 到 100 之間的整數，並在值為無效時引發 BadValueError。

「模型屬性」：RatingProperty

class MyModel(db.Model):
    rating = db.RatingProperty()

m = MyModel()
m.rating = db.Rating(97)

在 XML 中，這是 gd:rating 元素。

Property 類別

所有 google.appengine.ext.db 提供的模型屬性類別皆為 Property 基本類別中的子類別，可支援基本建構函式的所有引數。如需引數的詳細資訊，請參閱基本類別說明文件。

google.appengine.ext.db 套件提供下列模型屬性類別：

class BlobProperty(...)

一個未解譯的二進位資料集。

Blob 資料為位元組字串。如果是可能會用到編碼的文字資料，請使用 TextProperty。

「值類型」：Blob

class BooleanProperty(...)

布林值 (True 或 False)。

「值類型」：bool

class ByteStringProperty(verbose_name=None, ...)

短 blob 值 (即「位元組字串」)，不得超過 1500 個位元組。

ByteStringProperty 值已建立索引，且可用於篩選器和排序順序。

與 StringProperty 類似，但是該值不會以任何方式編碼，只會儲存位元組。

如果需要 ByteStringProperty，此值不可以是空白字串。

「值類型」：ByteString

class CategoryProperty(...)

一種類別或是「標記」，描述性的字詞或詞組。

「值類型」：Category

class DateProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)

不含時段的日期，詳情請參閱 DateTimeProperty。

「值類型」：datetime.date；在內部會轉換成 datetime.datetime

class DateTimeProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)

日期和時間。

如果 auto_now 為 True，每當將模型例項儲存在資料儲存庫中時，都會將該屬性值設為目前的時間，並覆寫該屬性之前的值。很適合用於追蹤模型例項「上次修改時間」的日期時間。

如果 auto_now_add 為 True，除非已為該屬性指派值，否則第一次將模型例項儲存在資料儲存庫中時，會將屬性值設為目前時間。很適合用於儲存模型例項的「已建立」日期時間。

日期時間值會使用世界標準時間時區值來儲存，並以相同格式傳回。如何管理時區的深入說明，請參閱 datetime.datetime 一節。

「值類型」：datetime.datetime

class EmailProperty(...)

電子郵件地址。

屬性類別或值類別都不會執行電子郵件地址驗證，只會儲存值。

「值類型」：Email

class FloatProperty(...)

浮點數。

「值類型」：float

class GeoPtProperty(...)

由浮點經緯度座標呈現的地理點。

「值類型」：GeoPt

class IMProperty(...)

即時通訊控制代碼。

「值類型」：IM

class IntegerProperty(...)

整數值，最多 64 位元。

儲存之前，Python int 值會轉換成 Python long 值。以 int 所儲存的資料值會當做 long 傳回。

如果指派的 long 超過 64 位元，則系統只會儲存最低有效的 64 位元。

「值類型」：int 或 long

class LinkProperty(...)

完全符合的網址。

「值類型」：Link

class ListProperty(item_type, verbose_name=None, default=None, ...)

一份由 item_type 指定的類型值清單。

在查詢中，如果將屬性清單與值相互比對，就會執行對清單成員的測試：list_property = value 會測試該值是否出現在清單上的任何地方；list_property < value 會測試清單上的成員是否少於給定值，依此類推。

查詢無法比較兩份清單值。如果要測試兩份清單的相等性，也須單獨測試每個元素的成員資格。

item_type 是清單內的項目類型，例如 Python 類型或類別。清單值中的所有項目必須為指定的類型。item_type 必須為資料儲存庫值類型之一，且不能為 list。

ListProperty 的值不可以是 None，但可以是空白清單。將預設引數指定為 None 後 (或是未指定 default 引數時)，該屬性的預設值即為空白清單。

提示：因為 ListProperty 匯總類型不使用 Property 類別，自動產生值與驗證等 Property 類別的功能，並不會自動套用到清單值的成員上。如果想用 Property 類別驗證成員值，可以將類別實例化，並針對該值呼叫類別的 validate() 方法。

default 是清單屬性的預設值。如果是 None，預設值為空白清單。清單屬性可以定義自訂的驗證工具，以禁止空白清單。

如要進一步瞭解清單屬性與值的詳細資訊，請參閱建立資料模型頁面。

「值類型」：指定類型值的 Python list

class PhoneNumberProperty(...)

一組使用者可判讀的電話號碼。

「值類型」：PhoneNumber

class PostalAddressProperty(...)

一個郵寄地址。

「值類型」：PostalAddress

class RatingProperty()

一個由使用者提供的內容片段評分，為 0 到 100 之間的整數。

「值類型」：Rating

class ReferenceProperty(reference_class=None, verbose_name=None, collection_name=None, ...)

其他模型例項的參照。例如，參照可能會指出含有該屬性的模型與該屬性參照之模型間的多對一關係。

reference_class 是參照模型例項的模型類別。如果有指定，則只有該類別的模型例項可以指派給此屬性。如果是 None，任何模型例項都可以成為此屬性的值。

collection_name 是要提供給所參照模型類別的屬性名稱。對於參照該實體的所有實體，該屬性值為 Query。如果未設定 collection_name，則會使用 modelname_set (即參照模型的小寫字母名稱，並加上 _set)。

附註：如果參照相同模型類別的同一個模型內有多個屬性，就必須設定 collection_name。否則，當預設名稱產生時，會引發 DuplicatePropertyError 狀況。

ReferenceProperty 會自動參照與解除參照模型例項，以當做屬性值：模型例項可直接指派至參照屬性，且會使用屬性的金鑰。ReferenceProperty 值可以當成模型例項來使用，在第一次以這種方式使用該值時，系統會擷取資料儲存庫實體並建立模型例項。未受影響的參照屬性不會查詢不需要的資料。

class Author(db.Model):
    name = db.StringProperty()

class Story(db.Model):
    author = db.ReferenceProperty(Author)

story = db.get(story_key)
author_name = story.author.name

author = db.get(author_key)
stories_by_author = author.story_set.get()

與 Key 值一樣，參照屬性值可以參照不存在的資料實體。如果刪除資料儲存庫中的參照實體，則該實體的參照不會隨之更新。存取不存在的實體會引發 ReferencePropertyResolveError。

刪除實體並不會刪除參照屬性所參照的實體。

「值類型」：db.Key

class SelfReferenceProperty(verbose_name=None, collection_name=None, ...)

對相同類別的其他模型例項的參照 (請參閱 ReferenceProperty)。

「值類型」：db.Key

class StringListProperty(verbose_name=None, default=None, ...)

與 Python str 或 unicode (basestring) 值的清單屬性類似。

「值類型」：Python 的 str 或 unicode 值 list。

class StringProperty(verbose_name=None, multiline=False, ...)

一個短字串，採用 Python str 或 unicode (basestring) 值 (不得超過 1500 位元組)。

StringProperty 值已建立索引，且可用於篩選器和排序順序。

如果 multiline 為 False，該值不能包含換行字元。djangoforms 程式庫在資料模型中，會用此值強制區分文字欄位與文字區域欄位，其他程式庫可能也會用在類似的用途上。

如果需要字串屬性，此值不可以是空白字串。

「值類型」：str 或 unicode

class TextProperty()

長字串。

不同於 StringProperty，TextProperty 值的長度可超過 1500 個位元組。然而，TextProperty 值並未建立索引，且無法用於篩選器或排序順序。

TextProperty 值會儲存含有文字編碼的文字。如果是二進位資料，則使用 BlobProperty。

如果需要字串屬性，此值不可以是空白字串。

「值類型」：Text

class TimeProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)

沒有日期的時段，採用 Python 標準程式庫 datetime.time 值。詳情請參閱 DateTimeProperty 一節。

「值類型」：datetime.time；在內部會轉換成 datetime.datetime

class UserProperty(verbose_name=None, auto_current_user=False, auto_current_user_add=False, ...)

重要事項：強烈建議您不要儲存 UserProperty，因為其中包含電子郵件地址和使用者的專屬 ID。如果使用者變更了電子郵件地址，但您還是使用先前儲存的 User 來比對新的 User 值，兩者將無法配對。

使用「Google 帳戶」的使用者。

如果 auto_current_user 為 True，每當將模型例項儲存在資料儲存庫中時，都會將該屬性值設為目前登入的使用者，並覆寫該屬性之前的值。很適合用於追蹤修正模型例項的使用者。

如果 auto_current_user_add 為 True，除非已為該屬性指派值，否則第一次將模型例項儲存在資料儲存庫中時，會將屬性值設為目前登入的使用者。很適合用於追蹤修正模型例項的使用者，因為該使用者可能與之後的修改者不相同。

UserProperty 不接受預設值。模型類別第一次匯入時會設定預設值，其中的匯入快取可能並非目前登入的使用者。

「值類型」：users.User