Типы и классы Property

Хранилище данных App Engine поддерживает ограниченный набор типов значений свойств объектов данных. Классы 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.

Свойство модели: StringProperty

bool

Логическое значение – True или False.

Свойство модели: BooleanProperty

int или long

Целое значение.

Значения Python int преобразуются в значения Python long перед сохранением. Значение, сохраненное как int, будет возвращено как long.

Свойство модели: IntegerProperty

float

Значение с плавающей точкой.

Свойство модели: FloatProperty

datetime.datetime

Дата и время. См. документацию по модулю datetime.

Если у значения datetime есть атрибут tzinfo, для сохранения оно будет преобразовано в часовой пояс всемирного времени (UTC). Значения возвращаются из хранилища данных как UTC с tzinfo None. В приложении, которому требуется, чтобы дата и время были заданы в определенном часовом поясе, необходимо корректно задать tzinfo во время обновления значения и преобразовать значения для необходимого часового пояса во время извлечения.

Некоторые приложения используют переменную среды TZ, чтобы контролировать часовой пояс, который применяется к значениям даты и времени. App Engine присваивает данной переменной среды значение "UTC". Обратите внимание, что изменение данной переменной в приложении не повлечет за собой изменение поведения ряда функций datetime, так как изменения переменных среды не видны вне кода 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).

Свойства модели: DateTimeProperty, DateProperty, TimeProperty

list

Список значений поддерживаемого типа. См. статью Объекты и модели. Списки.

Когда list используется как значение динамического свойства Expando, список не может быть пустым. Это связано со способом хранения значений списка: когда свойство списка не содержит элементов, в хранилище данных нет его представления. Можно использовать статическое свойство и класс ListProperty, который представляет значение пустого списка для свойства.

Свойство модели: 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)

Свойства модели: ReferenceProperty, SelfReferenceProperty

users.User

Пользователь с аккаунтом Google.

Значение свойства User не обновляется в хранилище данных в случае, если пользователь меняет свой адрес электронной почты. Возможно, это будет исправлено в следующем выпуске. До тех пор используйте в качестве стабильного уникального идентификатора пользователя user_id() значения User.

Свойство модели: 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").read())

В XML блобы кодируются на базе 64 бит, вне зависимости от того, содержат ли они двоичные данные.

class ByteString(arg)

Короткое значение типа блоб ("байтовая строка") длиной менее 500 байт. ByteString является подклассом класса str и принимает значение str в качестве аргумента конструктора.

Строки ByteString индексируются хранилищем данных и могут использоваться в фильтрах и порядках сортировки. Для байтовых строк длиной более 500 байт (которые не индексируются) используйте экземпляр класса Blob. Для закодированных текстовых данных используйте класс str (короткая, индексируемая строка) или Text (длинная, не индексируемая строка).

Свойство модели: ByteStringProperty

class Text(arg=None, encoding=None)

Длинная строка. Это подкласс встроенного типа unicode.

arg – значение unicode или str. Если arg имеет значение str, то он анализируется с помощью кодировки, указанной в encoding, или ascii, если она не указана. Допустимые значения encoding приведены в списке стандартных кодировок.

В отличие от свойства объекта, значением которого является простая строка str или unicode, свойство Text может быть длиной более 500 байт. Свойства 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. См. спецификацию Atom.

class Email(email)

Адрес электронной почты. Это подкласс встроенного типа unicode.

Ни класс свойств, ни класс значений не проверяют адреса электронной почты, они просто хранят значение.

Свойство модели: EmailProperty

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

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

В XML это элемент gd:email. См. Справку по API GData.

class GeoPt(lat, lon=None)

Географическая точка, представленная координатами широты и долготы с плавающей точкой.

Свойство модели: 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
неизвестен	Неизвестен или неуказан

address – адрес обработки.

Свойство модели: IMProperty

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

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

В XML это элемент gd:im. См. справку по API GData.

class Link(link)

Полностью соответствующий требованиям URL-адрес. Это подкласс встроенного типа unicode.

Свойство модели: 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.

Свойство модели: PhoneNumberProperty

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

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

В XML это элемент gd.phoneNumber. См. справку по API GData.

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. См. справку по API GData.

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. См. справку по API GData.

Классы Property

Все классы свойств модели, включенные в google.appengine.ext.db, являются подклассами базового класса Property и поддерживают все аргументы базового конструктора. Дополнительную информацию об аргументах можно найти в документации по базовому классу.

Пакет google.appengine.ext.db содержит следующие классы свойств модели:

class BlobProperty(...)

Свойство в виде двоичных данных.

Данные Blob – байтовая строка. Для текстовых данных, которые могут быть закодированы, используйте TextProperty.

Тип значений: Blob

class BooleanProperty(...)

Логическое свойство.

Тип значений: bool

class ByteStringProperty(verbose_name=None, ...)

Короткое свойство типа блоб ("байтовая строка"). Принимает значение ByteString длиной 500 байт или меньше.

Значения свойств 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 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, то значение по умолчанию – пустой список. Свойство списка может определять пользовательский валидатор, чтобы запретить пустой список.

Дополнительную информацию по ListProperty и значениям списка можно найти в статье Объекты и модели.

Тип значений: list Python из нуля или более значений, каждое из которых имеет указанный тип

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, ...)

Аналогично значениям ListProperty str или unicode (basestring) Python. См. ListProperty.

Тип значений: list Python из значений str или unicode

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

Свойство в виде короткой строки. Принимает значение str или unicode (basestring) Python длиной 500 байт или меньше.

Значения свойств 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, ...)

Свойство в виде времени без даты. Принимает значение datetime.time из стандартной библиотеки Python. Дополнительную информацию можно найти в 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 (см. выше)