類型和 Property 類別

「應用服務引擎」資料存放區支援資料實體屬性的一組固定的值類型。Property 類別可以定義新類型，可以在底層值類型之間轉換，而且新的值類型可以直接與 Expando 動態屬性和 ListProperty 彙整屬性模型搭配使用。

下列表格描述 Property 類型的值與其底層資料類型。任何這些值類型都可以用在 Expando 動態屬性或 ListProperty 彙整類型。

資料存放區值類型

資料存放區實體屬性值可以是下列類型之一。請參閱上述的相關 Property 類別清單，與 Model 定義搭配使用。

除了 Python 標準類型和 users.User之外，本區段所描述的所有類別都是由 google.appengine.ext.db 模組所提供。

str 或 unicode

短字串值，長度小於 500 個位元組。

str 值假設是以 ascii 編碼器編碼的文字，而且在儲存之前會轉換為 unicode 值。資料存放區會以 unicode 值傳回該值。 使用其他編碼器的短字串，會使用 unicode 值。

短字串可以由資料存放區進行索引，可以用於篩選器以及排序順序。大於 500 個位元組的文字字串 (不會進行索引)，會使用 Text 實例。 大於 500 個位元組的未編碼字串 (也不會進行索引)，會使用 Blob 實例。

Model 屬性： StringProperty

bool

Boolean 值，True 或 False。

Model 屬性： BooleanProperty

int 或 long

整數值

Python int 值在儲存之前會轉換為 Python long 值。儲存為 int 的值將會以 long 傳回。

Model 屬性： IntegerProperty

float

浮點數值。

Model 屬性： FloatProperty

datetime.datetime

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

若 datetime 值有 tzinfo 屬性 (attribute)，它在儲存時會轉換為通用時間慣例 (UTC)。從資料存放區傳回的 UTC 值，其 tzinfo 為 None。 應用程式若需要將日期和時間值設為特定時區，則在更新值的時候，要將 tzinfo 設定正確，並於存取該值時，將值轉換為特定的時區。

部分程式庫使用 TZ 環境變數來控制套用至日期時間值的時區。「應用服務引擎」將此環境變數設定為 "UTC"。 請注意，在應用程式中變更此值，不會變更某些日期時間函式的行為，因為在 Python 程式碼以外的範圍，看不到環境變數的變更。

若您只需將值轉為或轉出某特定時區，則可以實作自訂的 datetime.tzinfo，以轉換來自資料存放區的值：

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

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

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

   if dst_start <= dt.replace(tzinfo=None) < dst_end:
     return datetime_module.timedelta(hours=1)
   else:
     return datetime_module.timedelta(hours=0)

 def tzname(self, dt):
   if self.dst(dt) == datetime_module.timedelta(hours=0):
     return "PST"
   else:
     return "PDT"

pacific_time = utc_time.astimezone(Pacific_tzinfo())

請參閱 datetime 模組文件 (包括 datetime.tzinfo)。 另請參閱第三方模組 pytz，不過請注意，pytz 發行有很多檔案。

DateTimeProperty 模型類別的功能包括例如自動使用模型實例儲存的日期和時間。這些是模型的功能，在原始資料存放區值 (例如在 Expando 動態屬性中) 無法使用。

Model 屬性： DateTimeProperty、DateProperty、TimeProperty

list

值的清單，清單中的每個值都是支援的資料類型之一。請參閱實體和模型：清單。

當 Expando 動態屬性使用 list 類型時，不能是空白清單。這是由於清單值儲存的方式：清單屬性沒有任何項目時，在資料存放區中就不存在。您可以使用靜態屬性以及 ListProperty 類別來代表屬性的空白清單值。

Model 屬性： ListProperty

db.Key

其他資料存放區實體的金鑰。

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)

Model 屬性： ReferenceProperty、SelfReferenceProperty

users.User

具有 Google 帳戶的使用者。

如果使用者變更其電子郵件地址，則資料存放區中的 User 值不會更新。這可能會在以後的版本中加以修正。目前，您可以將 User 值的 user_id() 視為使用者的固定唯一識別碼。

Model 屬性： UserProperty

class Blob(arg=None)

二進位資料，為字元組字串。這是內建 str 類型的子類別。

Blob 屬性不會進行索引，且無法用於篩選器和排序順序。

Blob 是供二進位資料使用，例如影像。它接受 str 值，但此值會儲存為位元組字串，而且不會編碼為文字。若為大型文字資料，請使用 Text 實例。

Model 屬性： BlobProperty

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

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

在 XML 中，不論 blob 是否包含二進位資料，都會是 base-64 編碼。

class ByteString(arg)

短 blob 值 (「位元組字串」)，長度少於 500 個位元祖。ByteString 為 str 的子類別，並接受 str 值做為其建構函式的引數。

ByteStrings 可由資料存放區索引，且可用於篩選器以及排序順序。大於 500 個位元組的位元組字串 (不會進行索引) 會使用 Blob 實例。 針對編碼的文字資料，請使用 str (短、已建立索引) 或 Text (長，未建立索引)。

Model property: ByteStringProperty

class Text(arg=None, encoding=None)

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

arg unicode 或 str 值。若 arg 為 str，則它會以 encoding 指定的編碼進行剖析，若未指定編碼，則使用 ascii。請參閱標準的編碼清單以瞭解 encoding 的可能值。

與實體屬性值為簡單的 str 或 unicode 不同，Text 屬性的長度可以超過 500 個位元組。不過，Text 屬性不會進行索引，且無法用於篩選器和排序順序。

Model 屬性： 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 類型的子類別。

Model 屬性： CategoryProperty

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

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

在 XML 中，這是一種 Atom category 項目。請參閱 Atom 規格。

class Email(email)

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

不論是屬性類別或值類別，都不會對電子郵件地址進行驗證，它們會直接儲存那些值。

Model 屬性： EmailProperty

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

m = MyModel()
m.email_address = db.Email("larry@example.com")

在 XML 中，這是 gd:email 項目。請參閱 GData API 參考資料。

class GeoPt(lat, lon=None)

地理位置點會以浮點數的緯度和經度座標來表示。

Model 屬性： GeoPtProperty

在 XML 中，這是 georss:point 項目。請參閱 georss.org。

class IM(protocol, address=None)

一種立即訊息處理。

protocol 是立即訊息服務的正式 URL。部分可能的值如下：

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

address 是處理的位址。

Model 屬性： IMProperty

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

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

在 XML 中，這是 gd:im 項目。請參閱 GData API 參考資料。

class Link(link)

完整的 URL。這是內建 unicode 類型的子類別。

Model 屬性： LinkProperty

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

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

在 XML 中，這是一種 Atom link 項目。請參閱 Atom 規格。

class PhoneNumber(phone)

人類可讀的電話號碼。這是內建 unicode 類型的子類別。

Model 屬性： PhoneNumberProperty

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

m = MyModel()
m.phone = db.PhoneNumber("1 (206) 555-1212")

在 XML 中，這是 gd.phoneNumber 項目。請參閱 GData API 參考資料。

class PostalAddress(address)

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

Model 屬性： PostalAddressProperty

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

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

在 XML 中，這是 gd:postalAddress 項目。請參閱 GData API 參考資料。

class Rating(rating)

使用者提供的內容評等，介於 0 和 100 之間的整數。 這是內建 long 類型的子類別。類別會驗證值是否為介於 0 和 100 之間的整數值，並於值不正確時，引發 BadValueError。

Model 屬性： RatingProperty

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

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

在 XML 中，這是 gd:rating 項目。請參閱 GData API 參考資料。

Property 類別

google.appengine.ext.db 提供的所有模型屬性類別，都是 Property 基礎類別的子類別，且支援所有基礎建構函式的引數。請參閱基礎類別文件以取得關於那些引數的詳細資訊。

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

class BlobProperty(...)

二進位資料屬性。

Blob 資料是位元組字串。可能經過編碼的文字資料，請使用 TextProperty。

值類型： Blob

class BooleanProperty(...)

Boolean 屬性。

值類型： bool

class ByteStringProperty(verbose_name=None, ...)

短 blob 屬性 (「位元組字串」)。接受小於或等於 500 個位元組的 ByteString 值。

ByteStringProperty 屬性值會進行索引，並可用於篩選器和排序順序。

就像 StringProperty 一樣，除了這裡的值並未以任何方式進行編碼之外。會儲存原始的位元組。

值類型： 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，則屬性值會設為目前的時間 (模型實例第一次儲存在資料存放區時)，除非屬性已指派其他值。儲存模型實例「建立時間」的日期和時間時，這非常有用。

儲存和傳回日期時間值時，都會使用通用時間慣例 (UTC)。請參閱 datetime.datetime 以取得如何管理時區的討論。

值類型： datetime.datetime

class EmailProperty(...)

電子郵件地址。

不論是屬性類別或值類別，都不會對電子郵件地址進行驗證，它們會直接儲存那些值。

值類型： Email

class FloatProperty(...)

浮點數屬性。

值類型： float

class GeoPtProperty(...)

地理位置點會以浮點數的緯度和經度座標來表示。

值類型： GeoPt

class IMProperty(...)

一種立即訊息處理。

值類型： IM

class IntegerProperty(...)

整數屬性。

Python int 值在儲存之前會轉換為 Python long 值。儲存為 int 的值將會以 long 傳回。

值類型： int 或 long

class LinkProperty(...)

完整的 URL。

值類型： 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。不過，可以是空白清單。

提示：因為 ListProperty 彙整類型不會使用 Property 類別，Property 類別之自動值和驗證之類的功能，不會自動套用至清單的成員。若要使用 Property 類別來驗證成員值，您可以具現化該類別，並對該值呼叫其 validate() 方法。

default 是清單屬性的預設值。若為 None，則預設為空白清單。清單屬性可以定義自訂 validator，讓它不允許空白清單。

請參閱實體和模型以取得 ListProperty 和清單值的詳細資訊。

值類型：零或其他值的 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，而且會使用其金鑰。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

使用 Key 值時，參考屬性值可以參考不存在的資料實體。若從資料存放區刪除被參考的實體，則不會更新該實體的參考。應用程式可以明確地 db.get() ReferenceProperty (這是 Key) 的值，來測試被參考的實體是否存在。

刪除實體不會刪除 ReferenceProperty 參考的實體。

另請參閱本簡介的參考屬性。

值類型： db.Key (請參閱上方)

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

相同類別之另一個模型實例的參考。請參閱 ReferenceProperty。

值類型： db.Key (請參閱上方)

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

與 Python str 或 unicode (basestring) 值的 ListProperty 相似。 請參閱 ListProperty。

值類型：Python list 的 str 或 unicode 值

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

短字串屬性。接受小於或等於 500 個位元組的 Python str 或 unicode (basestring) 值。

StringProperty 屬性值會進行索引，並可用於篩選器和排序順序。

若 multiline 為 False，則值不能包括換行字元。djangoforms 程式庫用它來區分資料模型中文字欄位和文字區域欄位的不同，而其他的可能將它做為類似的目的。

值類型： str 或 unicode

class TextProperty()

長字串。

與 StringProperty 不同，TextProperty 值的長度可以大於 500 個位元組。不過，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, ...)

具有 Google 帳戶的使用者。

若 auto_current_user 為 True，則屬性值會設為目前登入的使用者 (只要模型實例儲存在資料存放區即可)，並覆寫屬性之前的值。追蹤哪位使用者修改了模型實例，這非常有用。

若 auto_current_user_add 為 True，則屬性值會設為目前登入的使用者 (模型實例第一次儲存在資料存放區時)，除非屬性已指派其他值。其中一個實用的方法是追蹤哪位使用者建立了模型實例，這些使用者可能不同於稍後進行修改的使用者。

UserProperty 不接受預設值。預設值會在第一次匯入模組類別時設定，且匯入快取可能不是目前登入的使用者。

值類型： users.User (請參閱上方)