• Официальный сайт SDK
  • Сайт с примерами кода

Класс Model

Класс Model является базовым классом для всех определений моделей данных.

Класс Model реализован в модуле google.appengine.ext.db.

Введение

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

CmNsYXNzIFN0b3J5KGRiLk1vZGVsKToKdGl0bGUgPSBkYi5TdHJpbmdQcm9wZXJ0eSgpCmJvZHkgPSBkYi5UZXh0UHJvcGVydHkoKQpjcmVhdGVkID0gZGIuRGF0ZVRpbWVQcm9wZXJ0eShhdXRvX25vd19hZGQ9VHJ1ZSkK=

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

CnMgPSBTdG9yeSgpCnMudGl0bGUgPSAiVGhlIFRocmVlIExpdHRsZSBQaWdzIgpzID0gU3RvcnkodGl0bGU9IlRoZSBUaHJlZSBMaXR0bGUgUGlncyIpCg===

Имя класса модели используется в качестве имени соответствующего типа объекта данных. Аналогично, имена атрибутов модели используются как имена соответствующих свойств объекта. Атрибуты экземпляра модели, имена которых начинаются с символа подчеркивания (_) игнорируются, таким образом ваше приложение может использовать их для хранения временных данных, которые не должны помещаться в хранилище.

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

Объект данных может иметь опциональное указание своего родительского объекта. Дочерние отношения формируют группы объектов, которые используются в дальнейшем для контроля целостности транзакций и месторасположения этих данных. Приложение может задать отношения между дочерним и родительским объектом передав последний как значение аргумента parent в конструктор дочернего объекта. Для дополнительной информации о родителях и предках объектов обратитесь к разделу Ключи и группы объектов.

Каждый объект имеет свой ключ - уникальный идентификатор, однозначно указывающий на объект. Объект может опционально иметь свое имя - уникальную строку внутри заданного типа объектов. Комбинация типа и имени объекта может быть использована в методах Key.from_path() и Model.get_by_key_name() для загрузки соответствующего объекта. Для дополнительной информации о ключах, обратитесь к разделу Ключи и группы объектов.

Метод Model.get_or_insert() может быть использован для загрузки объекта, который еще может не существовать, в этом случае он автоматически его создаст:

CmtleW5hbWUgPSAic29tZV9rZXkiCnMgPSBTdG9yeS5nZXRfb3JfaW5zZXJ0KGtleW5hbWUsIHRpdGxlPSJUaGUgVGhyZWUgTGl0dGxlIFBpZ3MiKQo==

Примечание: Экземпляр модели после своего создания не имеет соответствующего ему объекта в хранилище до тех пор, пока он явно не будет сохранен методом put(), либо тоже самое будет осуществлено через вызов метода Model.get_or_insert().

Класс Model реализован в пакете google.appengine.ext.db.

Конструктор

Конструктор класса модели определен следующим образом:

class Model(parent=None, key_name=None, **kw)

Он является базовым классом для определения моделей данных.

Параметры:

parent
Экземпляр модели - родителя нового объекта.
key_name

Имя нового объекта. Имя становится частью его первичного ключа. Если задано None, то для ключа используется заданный системой числовой идентификатор.

Значение параметра key_name не должно начинаться с цифры и не может быть вида __*__. Если приложение использует для задания имен ключей объектов введенные пользователем данные (например, адрес электронной почты), то оно должно привести их к допустимому виду, к примеру, добавив к ним префикс, заранее удовлетворяющий системным требованиям.

Значение параметра key_name сохраняется в качестве юникод строки (с конвертацией из типа str).

**kw
Первичные значения свойств экземпляра модели, заданные именованными параметрами. Каждый параметр соответствует атрибуту нового объекта класса модели.

Методы класса

Класс Model имеет следующие методы класса:

Model.get(keys)

Получает экземпляр модели (или экземпляры), заданные ключами - объектами типа Key. Ключи должны соответствовать объектам этого типа модели. Если заданы ключи для объектов другого типа, то выдается исключение KindError.

Этот метод похож на функцию db.get(), но проводит дополнительную проверку типа.

Параметры:

keys
Объект типа Key или список объектов типа Key. Может быть также строковым представлением объекта Key или списком таких строк.
Model.get_by_id(ids, parent=None)

Получает экземпляр модели (или экземпляры), заданные цифровым идентификатором (или идентификаторами).

Параметры:

ids
Числовой идентификатор или их список.
parent
Родитель запрашиваемых объектов в виде экземпляра класса Model или Key, или значение None (по умолчанию), если запрашиваемые объекты не имеют родителя. Если при вызове метода задается получение нескольких объектов, то все они должны принадлежать одному родителю.

Если в параметре ids задан единственный идентификатор, то метод возвращает соответствующий ему экземпляр модели или значение None, если объект не существует. Если параметр ids указан в качестве списка, метод также вернет список из экземпляров модели и, возможно, он будет путой.

Model.get_by_key_name(key_names, parent=None)

Получает экземпляр модели (или экземпляры), заданные именем ключа (или несколькими именами).

Параметры:

key_names
Имя ключа или их список.
parent
Родитель запрашиваемых объектов в виде экземпляра класса Model или Key, или значение None (по умолчанию), если запрашиваемые объекты не имеют родителя. Если при вызове метода задается получение нескольких объектов, то все они должны принадлежать одному родителю.

Если в параметре ids задано единственное имя объекта, то метод возвращает соответствующий ему экземпляр модели или значение None, если объект не существует. Если параметр key_names указан в качестве списка, метод также вернет список из экземпляров модели и, возможно, он будет путой.

Model.get_or_insert(key_name, **kwds)

Получает или создает новый объект заданного типа с определенным именем ключа, используя транзакцию. Транзакция позволяет быть уверенным, что если два пользователя одновременно попытаются произвести операцию get-or-insert с одним и тем же объектом, то будет создан только один экземпляр и оба пользователя получат на него корректную ссылку.

Параметры:

key_name
Имя ключа объекта.
**kwds
Именованные параметры для передачи в конструктор класса модели в том случае, если объект с указанным именем ключа не существует. Параметр parent должен быть задан обязательно, если указанный объект имеет родителя.

Метод возвращает экземпляр класса модели, который соответствует указанному объекту, который либо был изменен, либо был создан в процессе работы метода. Также как и другие подобные операции, этот метод может выдать исключение TransactionFailedError, если транзакцию не удалось зафиксировать.

Model.all()

Возвращает объект типа Query, который соответствует выборке всех объектов данных этой модели. Методы интерфейса Query могут задавать фильтры и порядок сортировки до того, как будет выполнен запрос. Для дополнительной информации смотрите описание Класса Query.

Model.gql(query_string, *args, **kwds)

Формирует GQL запрос с экземплярами этой модели.

Параметры:

query_string
Часть GQL запроса, которая следует после выражения SELECT * FROM модель (которое уже подразумевается при использовании этого метода класса).
*args
Позиционные параметры, такие же как используемые в конструкторе класса GqlQuery.
**kw
Именованные параметры, такие же как используемые в конструкторе класса GqlQuery.
CnMgPSBTdG9yeS5ncWwoIldIRVJFIHRpdGxlID0gOjEiLCAiTGl0dGxlIFJlZCBSaWRpbmcgSG9vZCIpCnMgPSBTdG9yeS5ncWwoIldIRVJFIHRpdGxlID0gOnRpdGxlIiwgdGl0bGU9IkxpdHRsZSBSZWQgUmlkaW5nIEhvb2QiKQo==

Возвращает значение объекта GqlQuery, которое затем может использоваться для получения результатов запроса.

Model.kind()
Возвращает тип объекта, обычно являющегося именем класса модели.
Model.properties()
Возвращает словарь всех свойств, определенных в классе модели.

Методы экземпляра

Экземпляры класса Model имеют следующие методы:

key()

Возвращает объект типа Key, сопоставленный с этим экземпляром модели.

Экземпляр модели может не иметь ключа, до тех пор, пока он не будет помещен в хранилище с помощью метода put(). Вызов метода key() до проведения сохранения объекта приведет в выдаче исключения NotSavedError.

put()

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

Метод возвращает ключ типа Key сохраненного объекта.

delete()

Удаляет экземпляр модели из хранилища. Если экземпляр ранее никогда не сохранялся методом put(), операция удаления не будет производить никаких действий.

is_saved()

Возвращает значение True, если экземпляр модели был сохранен в хранилище по крайней мере один раз.

Этот метод производит только проверку того, что экземпляр был сохранен хотя бы один раз после того, как был создан. Он не производит проверку того, что свойствам экземпляра присваивались новые значения с тех пор, когда последний раз объект был сохранен.

dynamic_properties()

Возвращает список имен всех динамических свойств, определенных для этого экземпляра модели. Доступно только для экземпляров классов Expando. Для стандартных моделей возвращает пустой список.

parent()

Возвращает экземпляр модели родительского объекта этого экземпляра или значение None, если этот экземпляр не имеет родителя.

parent_key()

Возвращает ключ родительского объекта этого экземпляра типа Key или значение None, если этот экземпляр не имеет родителя.

to_xml()

Возвращает представление экземпляра модели на языке разметки XML.

Значения свойств приводятся к соответствующим спецификациям Atom и GData.

Зарезервированные имена свойств

Хранилище и его интерфейс налагают некоторые ограничения на значения имен свойств объектов и атрибутов экземпляров модели.

Хранилище резервирует все имена свойств, которые начинаются и заканчиваются двумя символами подчеркивания (__*__). Объект хранилища не может иметь свойства с подобными именами.

Интерфейс по работе с данными будет игнорировать все атрибуты класса Model или Expando, которые начинаются с одного символа подчеркивания (_). Ваше приложение может использовать такие атрибуты для сохранения в них данных, которые не будут помещаться в хранилище.

В завершении, интерфейс языка Python для работы с моделями использует атрибуты объекта для определения свойств модели и по умолчанию присваивает соответствующим свойствам объектов в хранилище имена этих атрибутов. Так как класс Model имеет некоторые свойства и методы, используемые для внутренней реализации, то эти имена не могут быть использованы в свойствах модели приложения. К примеру, модель не может иметь свойство с атрибутом key.

Однако, возможно задавать отличные от зарезервированных имен тех, которые используются в хранилище, путем определения их с помощью параметра name в конструкторе свойства. Это позволяет объекту в хранилище иметь свойство с именем, аналогичным зарезервированному для класса Model и использовать для его сопоставления со свойством с другим именем атрибута в модели.

CmNsYXNzIE15TW9kZWwoZGIuTW9kZWwpOgpvYmpfa2V5ID0gZGIuU3RyaW5nUHJvcGVydHkobmFtZT0ia2V5IikK=

Следующие имена атрибутов зарезервированы и не могут быть использованы в описании класса Model:

  • all
  • app
  • copy
  • delete
  • entity_type
  • fields
  • from_entity
  • get
  • gql
  • instance_properties
  • is_saved
  • key
  • key_name
  • kind
  • parent
  • parent_key
  • properties
  • put
  • setdefault
  • to_xml
  • update