类型和 Property 类

App Engine 数据存储区支持数据实体上的一系列固定的属性值类型。Property 类可定义与基本值类型相互转换的新类型，并且，这些值类型可与 Expando 动态属性和 ListProperty 聚合属性模型直接配合使用。

下表介绍了一些 Property 类，其值直接对应于基本数据类型。这些值类型中的任何一个都可在 Expando 动态属性或 ListProperty 聚合类型中使用。

数据存储区值类型

数据存储区实体属性值可以是以下类型之一：有关可与 Model 定义配合使用的相应 Property 类的列表，请参阅上文。

除了 Python 标准类型和 users.User，此部分介绍的所有类都由 google.appengine.ext.db 模块提供。

str 或 unicode

短字符串值，长度少于 500 个字节。

str 值假定为用 ascii 编解码器进行编码的文本，且在存储前转换为 unicode 值。数据存储区会将该值作为 unicode 值返回。对于使用其他编解码器的短字符串，请使用 unicode 值。

短字符串由数据存储区编入索引，并可在过滤器和排序顺序中使用。对于长度超过 500 个字节的文本字符串（未编入索引），请使用 Text 实例。对于长度超过 500 个字节的非编码字节字符串（也未编入索引），请使用 Blob 实例。

Model 属性：StringProperty

bool

布尔值，为 True 或 False。

Model 属性：BooleanProperty

int 或 long

整数值。

在存储之前，Python int 值会被转换为 Python long 值。存储为 int 的值将返回为 long。

Model 属性：IntegerProperty

float

浮点值。

Model 属性：FloatProperty

datetime.datetime

日期和时间。请参阅日期时间模块文档。

如果 datetime 值具有 tzinfo 属性，则将转换为 UTC 时区进行存储。值作为 UTC 从数据存储区返回，且具有 None 的 tzinfo。如果某应用程序需要日期和时间值位于特定时区，则在更新该值时必须正确设置 tzinfo，并在访问该值时将值转换到该时区。

有些库使用 TZ 环境变量以控制应用到日期时间值的时区。App Engine 将此环境变量设置为 "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.tzinfo）。您也可参阅第三方模块 pytz，但您要注意，该 pytz 分发有许多文件。

DateTimeProperty Model Property 类包括一些功能（例如，自动使用存储 Model 实例的日期和时间的功能）。这些是该 Model 的功能，但在原始数据存储区值（例如在一个 Expando 动态属性中）上不可用。

Model 属性：DateTimeProperty、DateProperty、TimeProperty

list

值列表，其中每个值都是受支持的数据类型之一。请参阅实体和模型：列表。

当 list 被用作 Expando 动态属性的值时，不能是空列表。这是由列表值的存储方式引起的：当列表属性无项目时，该列表属性在数据存储区中无任何表示。您可以使用一个静态属性和 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 属性：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 类型的子类。

Property 类和 Value 类都不执行对电子邮件地址的验证，它们只存储值。

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 是该即时消息服务的规范网址。一些可能的值：

协议	说明
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
未知	未知或未指定

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)

完全限定网址。这是内置 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 提供的所有 Model Property 类都是 Property 基类的子类，并支持基本构造函数的所有参数。有关这些参数的信息，请参阅基类文档。

google.appengine.ext.db 包将提供以下 Model Property 类：

class BlobProperty(...)

二进制数据属性。

Blob 数据为字节字符串。对于可能包含编码的文本数据，请使用 TextProperty。

值类型：Blob

class BooleanProperty(...)

布尔属性。

值类型：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，则无论 Model 实例在何时存储于数据存储中，该属性值都会设置为当前时间，并覆盖该属性的上一值。这将有助于跟踪一个 Model 实例“上次修改”的日期和时间。

如果 auto_now_add 为 True，除非已为该属性分配值，否则将在第一次在数据存储区中存储 Model 实例时将属性值设置为当前时间。这将有助于存储一个 Model 实例“创建”的日期和时间。

日期时间值作为 UTC 时区存储，并使用 UTC 时区返回。有关如何管理时区的论述，请参阅 datetime.datetime。

值类型：datetime.datetime

class EmailProperty(...)

电子邮件地址。

Property 类和 Value 类都不执行对电子邮件地址的验证，它们只存储值。

值类型：Email

class FloatProperty(...)

浮点数字属性。

值类型：float

class GeoPtProperty(...)

由浮点纬度和经度坐标表示的地理点。

值类型：GeoPt

class IMProperty(...)

即时消息手写板。

值类型：IM

class IntegerProperty(...)

整数属性。

在存储之前，Python int 值会被转换为 Python long 值。作为 int 存储的值将作为 long 返回。

值类型：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。然而，可以是空列表。

提示：由于 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, ...)

对其他 Model 实例的引用。例如，引用可能指明在具有属性的 Model 和由该属性引用的 Model 之间所存在的多对一的关系。

reference_class 是正被引用的 Model 实例的 Model 类。如果已指定，那么，将只能为此属性分配该类的 Model 实例。如果为 None，则任何 Model 实例都能成为该属性的值。

collection_name 为该属性的名称，提供给值为引用该实体的所有实体的 Query 的引用 Model 类。如果未设置 collection_name，那么将使用 modelname_set（包含使用小写字母并添加了“_set”的 Model 名称）。

注意：如果同一模型中存在多个引用了相同 Model 类的属性，则必须设置 collection_name。否则，当生成默认名称时将引发 DuplicatePropertyError。

ReferenceProperty 将会自动引用和解除引用作为属性值的 Model 实例：Model 实例可直接分配到 ReferenceProperty，且将使用该 Model 实例的键。可将 ReferenceProperty 值用作 Model 实例，且将抓取数据存储区实体以及当该数据存储区实体首次以这种方式使用时创建 Model 实例。未触及的引用属性不对不需要的数据进行查询。

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 值时，引用属性值可能引用不存在的数据实体。如果从数据存储区中删除一个引用的实体，将不会更新对该实体的引用。应用程序可明确地对 ReferenceProperty 的值（在这里为 Key）进行 db.get() 操作以测试引用的实体是否存在。

删除实体不会删除 ReferenceProperty 所引用的实体。

请参阅该引用属性简介。

值类型：db.Key（请参阅上文）

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

对属于同一类的其他 Model 实例的引用。请参阅 ReferenceProperty。

值类型：db.Key（请参阅上文）

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

与 Python str 或 unicode (basestring) 值的 ListProperty 相似。请参阅 ListProperty。

值类型：str 或 unicode 值的 Python list

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 不接受默认值。默认值在第一次导入 Model 类时设置，对于导入缓存，其不一定是当前登录的用户。

值类型：users.User（请参阅上文）