Класс Property

Класс Property является базовым для определения свойств моделей данных. Класс Property задает тип значения соответствующего свойства, механизм валидации значения и метод хранения данных в хранилище.

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

Введение

Класс свойства задает тип его значения, определяет значение по умолчанию, логику валидации и прочие возможности свойства, используемого в классе Model. Каждый класс свойства является наследником базового класса Property. Интерфейс Datastore API включает в себя классы свойств для каждого из типов данных, поддерживаемых хранилищем, и некоторые из них имеют дополнительные возможности. Смотрите раздел Классы типов свойств.

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

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

Конструктор

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

class Property(verbose_name=None, name=None, default=None, required=False, validator=None, choices=None)

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

Параметры:

verbose_name
Читаемое пользователями название свойства. Должен всегда быть первым параметром в конструкторе свойства. Библиотека djangoforms использует это значение для задания надписей в полях формы, прочие библиотеки могут работать с ним подобным образом.
name
Сохраняемое имя свойства, используемое в запросах. По умолчанию является именем атрибута класса модели, используемого для свойства. Так как классы модели имеют другие атрибуты, чем их свойства (которые не могут быть использованы в свойствах), свойство может определять параметр name для использования зарезервированного имени свойства в хранилище и для определения другого имени атрибута свойства в модели. Для дополнительной информации смотрите раздел Зарезервированные имена свойств.
default

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

Примечание: Определения классов моделей кэшируются вместе с остальным кодом приложения. В том числе это происходит со значениями по умолчанию, задаваемые свойствам. Никогда не присваивайте параметр default в определении модели, значение которого зависят от текущего запроса (к примеру, не задавайте результат функции users.get_current_user()). Вместо этого используйте метод __init__() класса Model для инициализации свойства соответствующими значениями.

required

Если задано значение True, то свойству не может присваиваться значение None. Значения всех таких обязательных свойств должны быть проинициализированы путем передачи их в конструктор модели. Если произойдет попытка создания нового объекта без задания ему обязательных свойств или одному из них будет присвоено значение None, то будет выдано исключение BadValueError.

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

validator
Функция, которая должна быть вызвана для проверки присваемого значения на его допустимость. Эта функция принимает только один параметр - проверяемое значение и выдает исключение, в том случае если его значение неверное. Заданный валидатор вызывается после проведения всех остальных стандартных проверок, таких как имеет ли обязательное свойство значение.
choices
Список значений, принимаемых свойством. Если параметр установлен, то свойству не может присваиваться значение, не содержащееся в списке. Вместе с указанием параметра required и дополнительной валидацией, экземпляр модели будет создаваться только с определением корректных значений, совпадающих с содержимым списка. Если параметр choices имеет значение None, тогда допускается присваивать все значения, прошедшие первичные проверки на допустимость.

Атрибуты класса

Наследники базового класса Property определяют следующий атрибут класса:

data_type
Тип данных языка Python или его класс, значения которого будут приниматься свойством.

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

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

default_value()

Возвращает значение по умолчанию этого свойства. Базовая реализация использует это значение для передачи с параметром default в конструктор. Класс свойства может перекрывать его для определения другого значения, к примеру для DateTimeProperty таким образом реализована возможность работы с параметром auto-now.

validate(value)

Процедура проверки на допустимость присваемого значения (валидации) для этого свойства. Если значение value допустимо, то метод возвращает его неизменным или приведенным к требуемому типу. В противном случае выдает соответствующее исключение.

Базовая реализация выполняет проверку, что значение value не является None, в том случае если оно обязательное (задан параметр required в конструкторе класса Property), значение является одним из допустимых из указанного списка (задан параметр choices) и передает его дополнительному валидатору (параметр validator).

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

empty(value)

Возвращает значение True если параметр value считается пустым значением этого типа свойства. В базовой реализации это эквивалентно "не присвоено значение", что является достаточным для большинства типов. Другие типы, к примеру Boolean, могут перекрывать этот метод для выполнения дополнительных проверок значения.

get_value_for_datastore(model_instance)

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

make_value_from_datastore(value)

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