Класс Model

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

Класс Model входит в модуль google.appengine.ext.db.

• Введение
• Model()
• Методы класса:
  • Model.get()
  • Model.get_by_id()
  • Model.get_by_key_name()
  • Model.get_or_insert()
  • Model.all()
  • Model.gql()
  • Model.kind()
  • Model.properties()
• Методы экземпляра:
  • key()
  • put()
  • delete()
  • is_saved()
  • parent()
  • parent_key()
  • to_xml()
• Запрещенные названия свойств

Введение

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

class Story(db.Model):
  title = db.StringProperty()
  body = db.TextProperty()
  created = db.DateTimeProperty(auto_now_add=True)

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

s = Story()
s.title = "The Three Little Pigs"

s = Story(title="The Three Little Pigs")

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

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

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

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

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

keyname = "some_key"
s = Story.get_or_insert(keyname, title="The Three Little Pigs")

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

Класс Model входит в пакет google.appengine.ext.db.

Конструктор

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

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

Суперкласс определений моделей данных.

Аргументы:

parent

Экземпляр класса Model или Key для объекта, который является родителем нового объекта.

key_name

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

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

Значение аргумента key_name хранится в виде строки Unicode, при этом значения str преобразуются в текст ASCII.

**kw

Начальные значения свойств экземпляра в виде именованных аргументов. Каждое название соответствует атрибуту, определенному в классе Model.

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

Класс 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 является списком, метод возвращает список экземпляров модели. Если какой-либо объект не существует, для соответствующего значения Key в списке возвращается значение None.

Model.get_by_key_name(key_names, parent=None)

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

Аргументы:

key_names

Название ключа или список названий ключей.

parent

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

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

Model.get_or_insert(key_name, **kwds)

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

Аргументы:

key_name

Название ключа объекта.

**kwds

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

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

Model.all()

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

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

Выполняет GQL-запрос над экземплярами этой модели.

Аргументы:

query_string

Часть GQL-запроса, следующая за частью SELECT * FROM model (которая подразумевается при использовании этого метода класса).

*args

Привязки позиционных параметров, аналогичные конструктору класса GqlQuery.

**kw

Привязки именованных параметров, аналогичные конструктору класса GqlQuery.

s = Story.gql("WHERE title = :1", "Little Red Riding Hood")

s = Story.gql("WHERE title = :title", title="Little Red Riding Hood")

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

Model.kind()

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

Model.properties()

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

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

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

key()

Возвращает значение Key для этого экземпляра модели из хранилища данных.

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

put()

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

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

delete()

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

is_saved()

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

Этот метод только проверяет, сохранялся ли экземпляр хотя бы один раз с момента создания. Он не проверяет, обновлялись ли свойства экземпляра с момента последнего размещения в хранилище с помощью метода put().

dynamic_properties()

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

parent()

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

parent_key()

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

to_xml()

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

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

Запрещенные названия свойств

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

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

API модели Python игнорирует все атрибуты классов Model или Expando, начинающиеся с подчеркивания (_). Можно использовать такие атрибуты в приложении для связи данных с объектами модели, которые не сохраняются в хранилище данных.

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

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

class MyModel(db.Model):
  obj_key = db.StringProperty(name="key")

Следующие названия атрибутов зарезервированы классом Model в API Python: