Классы типов свойств

Хранилище App Engine поддерживает определенный набор типов свойств для хранения данных. Классы Property могут определять новые типы свойств, которые будут сконвертированы в базовые типы и использованы напрямую в динамических свойствах расширенных моделей Expando и в качестве значений типов ListProperty.

Следующая таблица описывает классы, являющиеся потомками Property, значения которых непосредственно соответствуют базовым типам данных. Любой из этих типов может быть использован в качестве динамических свойств моделей Expando или списков типа ListProperty.

Класс свойства	Тип значения	Тип сортировки
StringProperty	str unicode	По юникодному представлению (str интерпретируется как ASCII)
BooleanProperty	bool	False < True
IntegerProperty	int long	В порядке возрастания
FloatProperty	float	В порядке возрастания
DateTimeProperty DateProperty TimeProperty	datetime.datetime	В хронологическом порядке
ListProperty StringListProperty	список поддерживаемых типов	Если по возрастанию, то от наименьшего элемента; если по убыванию - то от наибольшего
ReferenceProperty SelfReferenceProperty	db.Key	По элементам пути (тип, идентификатор или имя...)
UserProperty	users.User	По адресу электронной почты (юникодное значение)
BlobProperty	db.Blob	(не подлежит сортировке)
TextProperty	db.Text	(не подлежит сортировке)
CategoryProperty	db.Category	По юникодному значению
LinkProperty	db.Link	По юникодному значению
EmailProperty	db.Email	По юникодному значению
GeoPtProperty	db.GeoPt	Сначала по широте, потом по долготе
IMProperty	db.IM	По юникодному значению
PhoneNumberProperty	db.PhoneNumber	По юникодному значению
PostalAddressProperty	db.PostalAddress	По юникодному значению
RatingProperty	db.Rating	В порядке возрастания

Типы значений, помещаемых в хранилище

Свойству объекта, помещаемого в хранилище, могут быть присвоены значения следующих типов. Смотрите выше список соответствующих классов Property, которые могут быть использованы при определеннии модели.

Все классы описанные в этом разделе, кроме стандартных типов языка 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

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

Перед сохранением этого значения в хранилище производится конвертация типа int в тип long. Обратно, значение, сохраненное в типе int, будет возвращено из хранилища уже имеющим тип long.

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

float

Число с плавающей запятой.

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

datetime.datetime

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

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

Некоторые библиотеки могут использовать переменную окружения TZ для приведения значений дат и времени к правильной временной зоне. Обратите внимание, платформа App Engine устанавливает значение этой переменной в "UTC". Изменение этой переменной внутри вашего приложения не даст никакого результата на поведение функций, так как изменения переменных окружения не будут вынесены за пределы кода Python.

Если вам необходима простая конвертация значений даты с учетом временной зоны, вы можете реализовать собственный обработчик datetime.tzinfo и преобразовывать значения, получаемые из хранилища:

class Pacific_tzinfo(datetime_module.tzinfo):
 """Реализация обработчика для временной зоны Pacific."""
 def utcoffset(self, dt):
   return datetime_module.timedelta(hours=-8) + self.dst(dt)

 def _FirstSunday(self, dt):
   """Вычисление дня после указанной даты, когда наступит первое воскресенье."""
   return dt + datetime_module.timedelta(days=(6-dt.weekday()))

 def dst(self, dt):
   # смещение 2 часа второго воскресенья марта
   dst_start = self._FirstSunday(datetime_module.datetime(dt.year, 3, 8, 2))
   # смещение 1 час первого воскресенья ноября
   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, единственным недостатком которого является то, что его дистрибутив содержит очень много файлов.

Класс свойства модели типа 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 = Key.from_path("Employee", "susan5")
e = Employee(name="Jennifer", manager=m_key)

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

users.User

Пользователь, сопоставленный со своим аккаунтом Google.

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

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, совпадает с элементом category формата Atom. Обратитесь к спецификации формата 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. Смотрите описание GData API.

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
unknown	Неизвестный или неуказанный

Параметр address должен быть адресом контакта в нужном формате.

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

Соответствующее свойство модели: LinkProperty

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

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

В разметке XML совпадает с элементом link формата Atom. Обратитесь к спецификации формата 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. Смотрите описание GData API.

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. Смотрите описание GData API.

class Rating(rating)

Пользовательский рейтинг определенного контента, является целым числом в интервале от 0 до 100. Является потомком встроенного класса long. Этот класс выполняет проверку на допустимость значения между 0 и 100 и выдает исключение BadValueError, в случае, если указано неверное значение.

Соответствующее свойство модели: RatingProperty

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

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

В разметке совпадает с элементом gd:rating. Смотрите описание GData API.

Классы свойств моделей

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

В пакете google.appengine.ext.db реализованы следующие классы свойств моделей:

class BlobProperty(...)

Свойство, содержащее двоичные данные.

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

Соответствующий тип значения: Blob

class BooleanProperty(...)

Свойство имеющее логический тип.

Соответствующий тип значения: bool

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

Свойство типа целое число.

Перед сохранением этого значения в хранилище производится конвертация типа int в тип long. Обратно, значение, сохраненное в типе int, будет возвращено из хранилища уже имеющим тип long.

Соответствующие типы значения: int или long

class LinkProperty(...)

Строка, содержащая значение абсолютного URL.

Соответствующий тип значения: Link

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

Список значений типа, указанного в параметре item_type.

В запросе, содержащем условие сравнения свойства списка со значениями, выполняется проверка каждого члена списка: условие свойство_списка = значение проверяет, что заданное значение совпадает с одним из значений списка, а свойство_списка < значение проверяет, что любой из членов списка меньше заданного значения, и тому подобное.

Запрос не может произвести напрямую сравнение двух списков. Поэтому не существует способа выполнить сравнение двух списков между собой без последовательной проверки каждого их элемента.

Параметр item_type задает тип элементов списка, который может быть стандартным типом языка Python или его классом. Все элементы одного списка должны иметь один и тот же заданный тип. Параметр item_type должен быть одним из допустимых типов хранилища и сам не может быть списком типа list. Смотрите раздел Типы значений, помещаемых в хранилище.

Значение статического свойства типа ListProperty никогда не может быть None. Тем не менее, ему можно присваивать значение пустого списка.

Подсказка: Так как типы хранимые в списках ListProperty не используют классы Property, их возможности типа автоматического задания значений или валидации не применимы к членам списка. Если вы хотите произвести проверку на допустимость значений с использованием классов Property, то необходимо создать их экземпляры и передать значение методу validate().

Параметр default является значением по умолчанию для свойства списка. Если задано None, по умолчанию оно будет содержать пустой список. Свойство списка может задать собственный валидатор для запрещения использования пустого списка.

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

Соответствующий тип значения: стандартный список 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 не задан, то будет использовано имя вида модель_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 из значений стандартных типов языка Python str или unicode. Смотрите описание ListProperty.

Соответствующий тип значения: список типа list значений str или unicode

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

Свойство для хранения коротких строк. Может принимать значения стандартных типов str или unicode (basestring) длиной до 500 символов.

Свойства типа StringProperty могут быть проиндексированы и использованы в фильтрах запросов или условиях сортировки.

Если параметр multiline установлен в False, значение не может содержать символы перевода строки. Библиотека djangoforms использует это указание для проведения отличий между обычными текстовыми полями формы и содержащими многострочные конструкции (textarea).

Соответствующие типы значений: 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()

Пользователь, сопоставленный со своим аккаунтом Google.

Свойство типа UserProperty не может быть пустым.

Примечание: Не задавайте свойству типа UserProperty значение по умолчанию, присваемое как результат функции get_current_user(). Платформа App Engine проводит кэширование импортуемых модулей, поэтому может произойти ситуация, когда значение по умолчанию от одного пользователя будет использовано для другого. В общем случае, в свойстве типа UserProperty не должно быть указано значение по умолчанию. Для дополнительной информации обратитесь к разделу кэширование.

Соответствующий тип значения: users.User (смотрите выше)