Валидация форм и полей¶
Валидация формы происходит при очистке данных. Если вы хотите настроить этот процесс, есть различные места для внесения изменений, каждое из которых служит для разных целей. В процессе обработки формы выполняются три типа методов очистки. Обычно они выполняются, когда вы вызываете метод is_valid() на форме. Есть и другие вещи, которые также могут вызвать очистку и проверку (обращение к атрибуту errors или прямой вызов full_clean() ), но обычно они не нужны.
Валидация формы разбита на несколько этапов, которые можно настроить или отменить:
Например, если вы хотите проверить, что содержимое CharField под названием serialnumber является уникальным, clean_serialnumber() будет подходящим местом для этого. Вам не нужно конкретное поле (это CharField ), но вам нужна специфическая для поля формы часть валидации и, возможно, очистки/нормализации данных.
Примеры каждого из этих методов приведены ниже.
Поднятие ValidationError ¶
Чтобы сделать сообщения об ошибках гибкими и легко переопределяемыми, примите во внимание следующие рекомендации:
Предоставить описательную ошибку code конструктору:
Не вставляйте переменные в сообщение; используйте заполнители и аргумент params конструктора:
Используйте ключи отображения вместо позиционного форматирования. Это позволяет располагать переменные в любом порядке или вообще их не использовать при переписывании сообщения:
Собираем все вместе:
Следование этим рекомендациям особенно необходимо, если вы пишете многократно используемые формы, поля форм и поля моделей.
Хотя это и не рекомендуется, если вы находитесь в конце цепочки валидации (т.е. ваша форма clean() метод) и вы знаете, что вам никогда не понадобится переопределять сообщение об ошибке, вы можете выбрать менее многословный вариант:
Методы Form.errors.as_data() и Form.errors.as_json() значительно выигрывают от полнофункциональных ValidationError s (с code именем и params словарем).
Возникновение множества ошибок¶
Использование валидации на практике¶
В предыдущих разделах объяснялось, как работает валидация в целом для форм. Поскольку иногда бывает проще понять, как работает каждая функция, здесь приведена серия небольших примеров, в которых используется каждая из предыдущих функций.
Использование валидаторов¶
Валидаторы могут быть использованы для проверки значений внутри поля, давайте посмотрим на Django’s SlugField :
Очистка полей формы по умолчанию¶
В каждой форме, использующей это поле, эти методы будут выполняться до того, как с данными поля можно будет сделать что-либо еще. Это очистка, специфичная для данного типа поля, независимо от того, как оно будет использоваться в дальнейшем.
Очистка определенного атрибута поля¶
Очистка и проверка полей, которые зависят друг от друга¶
К моменту вызова метода clean() формы будут запущены все методы очистки отдельных полей (предыдущие два раздела), поэтому self.cleaned_data будет заполнен любыми данными, которые сохранились до сих пор. Поэтому вам также нужно помнить о том, что поля, которые вы хотите проверить, могут не выдержать первоначальной проверки отдельных полей.
Вызов super().clean() в коде примера гарантирует, что любая логика валидации в родительских классах будет сохранена. Если ваша форма наследует другую, которая не возвращает словарь cleaned_data в своем методе clean() (это необязательно), то не присваивайте cleaned_data результату вызова super() и используйте self.cleaned_data вместо этого:
Второй подход для сообщения об ошибках валидации может включать присвоение сообщения об ошибке одному из полей. В данном случае давайте присвоим сообщение об ошибке обеим строкам «subject» и «cc_myself» в отображении формы. Будьте осторожны, делая это на практике, так как это может привести к запутанному выводу формы. Мы показываем, что здесь возможно, и предоставляем вам и вашим дизайнерам самим решать, что будет эффективно работать в вашей конкретной ситуации. Наш новый код (заменяющий предыдущий пример) выглядит следующим образом:
Документация Django 3.0
Проверка формы происходит при нормализации её данных. При возникновении необходимости вмешаться в этот процесс, есть много мест, где можно это сделать и которые влияют на разные этапы проверки. Во время обработки формы вызываются три типа методов для нормализации данных. Процесс проверки запускается при вызове метода is_valid() формы. Существуют ситуации, которые запускают нормализацию и проверку данных (обращение к свойству errors или прямой вызов метода full_clean() ), но они возникают достаточно редко.
Проверка формы состоит из нескольких этапов, каждый из которых может быть настроен или переопределён:
Метод validate() поля выполняет специфическую для поля проверку данных и приводит значение к правильному типу данных, или вызывает исключение ValidationError на любую ошибку. Этот метод не возвращает значение и не должен изменять проверяемые данные. Если вам надо обеспечить логику, которую невозможно или нежелательно выносить в валидатор, то вам следует переопределить этот метод.
For example, if you wanted to validate that the contents of a CharField called serialnumber was unique, clean_serialnumber() would be the right place to do this. You don’t need a specific field (it’s a CharField ), but you want a formfield-specific piece of validation and, possibly, cleaning/normalizing the data.
Метод clean() потомка формы может выполнять любую проверку, которая нуждается в одновременном доступе к данным нескольких полей. Именно здесь вы можете проверять, что если поле A заполнено, то поле B должно содержать правильный адрес электронной почты и так далее. Данные, которые возвращает этот метод, помещаются в свойство cleaned_data формы.
Примеры для каждого из этих методов показаны ниже.
Вызов ValidationError ¶
Для удобной работы с ошибками валидации используйте следующие правила:
Передайте при создании код ошибки через аргумент code :
Используйте именованные параметры в сообщении. Это позволит использовать переменные в любом параметре при переопределении сообщения:
Оберните сообщения в gettext для последующего перевода:
Соблюдать правила очень важно при создании переносимых форм, полей форм и моделей.
Не рекомендуется, но если вы в конце цепочки валидации(например, метод clean() формы) и никогда не будете переопределять сообщение, можно просто сделать:
Методы Form.errors.as_data() и Form.errors.as_json() используют все возможности ValidationError (включая code и params ).
Вызов нескольких ошибок¶
При обнаружении нескольких ошибок в процессе нормализации поля и при наличии желания отобразить их одновременно на форме, следует передать их в виде списка в конструктор исключения.
Использование проверки на практике¶
Выше мы рассмотрели как осуществляется проверка форм в целом. Так как временами бывает проще разобраться с функционалом, просмотрев его в действии, далее показан ряд небольших примеров, которые используют описанные возможности.
Использование валидаторов¶
Django’s form (and model) fields support use of utility functions and classes known as validators. A validator is a callable object or function that takes a value and returns nothing if the value is valid or raises a ValidationError if not. These can be passed to a field’s constructor, via the field’s validators argument, or defined on the Field class itself with the default_validators attribute.
Validators can be used to validate values inside the field, let’s have a look at Django’s SlugField :
As you can see, SlugField is a CharField with a customized validator that validates that submitted text obeys to some character rules. This can also be done on field definition so:
Встроенная проверка поля формы¶
Давайте сначала создадим собственное поле формы, которое проверяет, что переданные ему данные — это строка, содержащая адреса электронной почты, разделенные запятыми. Класс такого поля будет выглядеть следующим образом:
Каждая форма, использующая такое поле, будет вызывать эти методы до выполнения всех остальных действий с данными поля. Такая проверка привязана к этому типу поля и не зависит от дальнейшего его использования.
Let’s create a ContactForm to demonstrate how you’d use this field:
Use MultiEmailField like any other form field. When the is_valid() method is called on the form, the MultiEmailField.clean() method will be run as part of the cleaning process and it will, in turn, call the custom to_python() and validate() methods.
Проверка атрибута определённого поля¶
Очистка и проверка полей, которые зависят друг от друга¶
К моменту вызова метода формы clean() все clean() методы полей уже отработали. Таким образом, свойство формы self.cleaned_data будет заполнено данными, прошедшими проверку. Следовательно, надо принять во внимание возможность того, что данные некоторых полей не прошли начальную поверку.
В данном коде, при возникновении ошибки во время проверки данных, форма отобразит сообщение об ошибке сверху (обычное поведение), описывая проблему.
Вызов super().clean() обеспечивает проверку данных в родительском классе. Если ваша форма наследуется от класса, который не возвращает словарь cleaned_data из метода clean() (это не обязательно), не записывайте в cleaned_data результат вызова super() и используйте вместо этого self.cleaned_data :
Второй способ подразумевает назначение ошибки одному из полей. В нашем случае, давайте назначим сообщение об ошибке обоим полям («subject» и «cc_myself») при отображении формы. Использовать этот способ надо аккуратно, так как он может запутать пользователя. Мы лишь показываем возможные варианты, оставляя решение конкретной задачи вам и вашим дизайнерам. Наш новый код (заменяющий предыдущий пример) выглядит так:
Проверка форм и полей ¶
Проверка формы происходит при очистке данных. Если вы хотите настроить этот процесс, есть несколько точек входа, где можно внести изменения, каждая из которых преследует разные цели. При обработке формы используются три метода очистки. Обычно они выполняются при is_valid() вызове метода формы. Существуют и другие операции, которые также могут вызывать очистку и проверку (доступ к атрибуту errors или прямой вызов full_clean() ), но в принципе это не является частью обычного процесса.
Проверка формы разделена на несколько шагов, которые можно персонализировать или перегружать:
Метод validate() поля Field заботится о конкретной проверке поля, что не подходит для валидатора. Он принимает значение, которое уже было преобразовано в правильный тип, и генерирует исключение в ValidationError случае возникновения ошибки. Этот метод ничего не возвращает и не должен изменять значение. Его можно перегружать для обработки логики проверки, которую вы не можете или не хотите добавлять в валидатор.
Поскольку методы проверки поля выполнялись во время clean() вызова, у вас также есть доступ к атрибуту errors формы, который содержит все ошибки, сгенерированные во время очистки отдельного поля.
Также обратите внимание на то, что при переопределении clean() метода подкласса необходимо учитывать особые моменты ( дополнительную информацию ModelForm см. В документации ModelForm ).
Примеры для каждого из этих методов показаны ниже.
Генерация ValidationError ¶
Для большей гибкости сообщений об ошибках и облегчения их переопределения вот несколько рекомендаций:
Предоставьте конструктору code описательную ошибку:
Не объединяйте переменные в сообщениях; используйте заполнители, а также параметр params конструктора:
Предпочитайте подстановку словарного ключа позиционному форматированию. Это позволяет размещать переменные в любом порядке или даже полностью их опускать при перезаписи сообщения:
Включите сообщение в вызов, gettext чтобы активировать его перевод:
Следование этим рекомендациям особенно полезно при написании многоразовых форм, полей форм или полей шаблонов.
Методы Form.errors.as_data() и Form.errors.as_json() значительно выигрывают от ValidationError полностью заполненных объектов (с именем code и словарем params ).
Генерация нескольких ошибок ¶
Использование валидации на практике ¶
В предыдущих разделах объяснялось, как в целом работает проверка форм. Поскольку иногда легче расставить вещи по своим местам, изучив код в контексте, вот серия небольших примеров, в которых используется каждая из функций, описанных выше.
Использование валидаторов ¶
Валидаторы могут использоваться для проверки значений поля; Например, давайте посмотрим на поле SlugField Django:
Очистка полей формы по умолчанию ¶
Во-первых, давайте создадим настраиваемое поле формы, которое проверяет, что его входное значение представляет собой строку, содержащую адреса электронной почты, разделенные запятыми. Полный класс выглядит так:
Для каждой формы, использующей это поле, эти методы будут выполняться до того, как что-либо будет сделано с данными в поле. Это очистка, специфичная для этого типа поля, независимо от того, как оно будет использоваться позже.
Давайте создадим форму, ContactForm чтобы показать, как можно использовать это поле:
Очистка определенного атрибута поля ¶
Очистка и проверка полей, которые зависят друг от друга ¶
К моменту clean() вызова метода формы все методы очистки для каждого поля уже будут выполнены (см. Два предыдущих раздела), так что self.cleaned_data они будут заполнены любыми данными, прошедшими проверку до этого момента. Поэтому вы также должны помнить о том, что поля, которые вы хотите проверить, возможно, не прошли предварительный этап проверки на уровне отдельного поля.
Второй подход к сообщению об ошибках проверки может включать назначение сообщения об ошибке одному из полей. В этом случае давайте назначим сообщение об ошибке для строк «subject» и «cc_myself» в представлении формы. Будьте осторожны, если будете делать это на практике, так как это может привести к путанице в представлении формы. Здесь мы показываем, что возможно, но оставляем вам самому решать, что можно сделать в вашем конкретном контексте. Наш новый код (заменяющий предыдущий пример) выглядит так:
Документация Django 1.9
Проверка формы происходит при нормализации её данных. При возникновении необходимости вмешаться в этот процесс, есть много мест, где можно это сделать и которые влияют на разные этапы проверки. Во время обработки формы вызываются три типа методов для нормализации данных. Процесс проверки запускается при вызове метода is_valid() формы. Существуют ситуации, которые запускают нормализацию и проверку данных (обращение к свойству errors или прямой вызов метода full_clean() ), но они возникают достаточно редко.
Проверка формы состоит из нескольких этапов, каждый из которых может быть настроен или переопределён:
Метод validate() поля выполняет специфическую для поля проверку данных и приводит значение к правильному типу данных, или вызывает исключение ValidationError на любую ошибку. Этот метод не возвращает значение и не должен изменять проверяемые данные. Если вам надо обеспечить логику, которую невозможно или нежелательно выносить в валидатор, то вам следует переопределить этот метод.
Например, если требуется проверить, что содержимое CharField поля с именем serialnumber является уникальным, то метод clean_serialnumber() будет правильным местом для такого функционала. Вам не нужно специальное поле (пусть будет CharField ), но требуется хитрая проверка данных и, возможно, очистка/нормализация данных.
Этот метод должен возвращать очищенное значение, полученное из cleaned_data независимо, изменилось оно или нет.
Метод clean() потомка формы. Этот метод может выполнять любую проверку, которая нуждается в одновременном доступе к данным нескольких полей. Именно здесь вы можете проверять, что если поле A заполнено, то поле B должно содержать правильный адрес электронной почты и так далее. Данные, которые возвращает этот метод, помещаются в свойство cleaned_data формы.
Примеры для каждого из этих методов показаны ниже.
Вызов ValidationError ¶
Для удобной работы с ошибками валидации используйте следующие правила:
Передайте при создании код ошибки через аргумент code :
Используйте именованные параметры в сообщении. Это позволит использовать переменные в любом параметре при переопределении сообщения:
Оберните сообщения в gettext для последующего перевода:
Соблюдать правила очень важно при создании переносимых форм, полей форм и моделей.
Не рекомендуется, но если вы в конце цепочки валидации(например, метод clean() формы) и никогда не будете переопределять сообщение, можно просто сделать:
Методы Form.errors.as_data() и Form.errors.as_json() используют все возможности ValidationError (включая code и params ).
Вызов нескольких ошибок¶
При обнаружении нескольких ошибок в процессе нормализации поля и при наличии желания отобразить их одновременно на форме, следует передать их в виде списка в конструктор исключения.
Использование проверки на практике¶
Выше мы рассмотрели как осуществляется проверка форм в целом. Так как временами бывает проще разобраться с функционалом, просмотрев его в действии, далее показан ряд небольших примеров, которые используют описанные возможности.
Использование валидаторов¶
Простые валидаторы могут использоваться для проверки значений внутри полей. Давайте рассмотрим SlugField :
Встроенная проверка поля формы¶
Давайте сначала создадим собственное поле формы, которое проверяет, что переданные ему данные — это строка, содержащая адреса электронной почты, разделенные запятыми. Класс такого поля будет выглядеть следующим образом:
Каждая форма, использующая такое поле, будет вызывать эти методы до выполнения всех остальных действий с данными поля. Такая проверка привязана к этому типу поля и не зависит от дальнейшего его использования.
Проверка атрибута определённого поля¶
Очистка и проверка полей, которые зависят друг от друга¶
К моменту вызова метода формы clean() все clean() методы полей уже отработали. Таким образом, свойство формы self.cleaned_data будет заполнено данными, прошедшими проверку. Следовательно, надо принять во внимание возможность того, что данные некоторых полей не прошли начальную поверку.
В данном коде, при возникновении ошибки во время проверки данных, форма отобразит сообщение об ошибке сверху (обычное поведение), описывая проблему.
Вызов super(ContactForm, self).clean() обеспечивает проверку данных в родительском классе. Если ваша форма наследуется от класса, который не возвращает словарь cleaned_data из метода clean() (это не обязательно), не записывайте в cleaned_data результат вызова super() и используйте вместо этого self.cleaned_data :
Второй способ подразумевает назначение ошибки одному из полей. В нашем случае, давайте назначим сообщение об ошибке обоим полям («subject» и «cc_myself») при отображении формы. Использовать этот способ надо аккуратно, так как он может запутать пользователя. Мы лишь показываем возможные варианты, оставляя решение конкретной задачи вам и вашим дизайнерам. Наш новый код (заменяющий предыдущий пример) выглядит так:
Документация Django 1.8
Проверка формы происходит при нормализации её данных. При возникновении необходимости вмешаться в этот процесс, есть много мест, где можно это сделать и которые влияют на разные этапы проверки. Во время обработки формы вызываются три типа методов для нормализации данных. Процесс проверки запускается при вызове метода is_valid() формы. Существуют ситуации, которые запускают нормализацию и проверку данных (обращение к свойству errors или прямой вызов метода full_clean() ), но они возникают достаточно редко.
Проверка формы состоит из нескольких этапов, каждый из которых может быть настроен или переопределён:
Метод validate() поля выполняет специфическую для поля проверку данных и приводит значение к правильному типу данных, или вызывает исключение ValidationError на любую ошибку. Этот метод не возвращает значение и не должен изменять проверяемые данные. Если вам надо обеспечить логику, которую невозможно или нежелательно выносить в валидатор, то вам следует переопределить этот метод.
Например, если требуется проверить, что содержимое CharField поля с именем serialnumber является уникальным, то метод clean_serialnumber() будет правильным местом для такого функционала. Вам не нужно специальное поле (пусть будет CharField ), но требуется хитрая проверка данных и, возможно, очистка/нормализация данных.
Этот метод должен возвращать очищенное значение, полученное из cleaned_data независимо, изменилось оно или нет.
Метод clean() потомка формы. Этот метод может выполнять любую проверку, которая нуждается в одновременном доступе к данным нескольких полей. Именно здесь вы можете проверять, что если поле A заполнено, то поле B должно содержать правильный адрес электронной почты и так далее. Данные, которые возвращает этот метод, помещаются в свойство cleaned_data формы.
Примеры для каждого из этих методов показаны ниже.
Вызов ValidationError ¶
Для удобной работы с ошибками валидации используйте следующие правила:
Передайте при создании код ошибки через аргумент code :
Используйте именованные параметры в сообщении. Это позволит использовать переменные в любом параметре при переопределении сообщения:
Оберните сообщения в gettext для последующего перевода:
Соблюдать правила очень важно при создании переносимых форм, полей форм и моделей.
Не рекомендуется, но если вы в конце цепочки валидации(например, метод clean() формы) и никогда не будете переопределять сообщение, можно просто сделать:
Вызов нескольких ошибок¶
При обнаружении нескольких ошибок в процессе нормализации поля и при наличии желания отобразить их одновременно на форме, следует передать их в виде списка в конструктор исключения.
Использование проверки на практике¶
Выше мы рассмотрели как осуществляется проверка форм в целом. Так как временами бывает проще разобраться с функционалом, просмотрев его в действии, далее показан ряд небольших примеров, которые используют описанные возможности.
Использование валидаторов¶
Простые валидаторы могут использоваться для проверки значений внутри полей. Давайте рассмотрим SlugField :
Встроенная проверка поля формы¶
Давайте сначала создадим собственное поле формы, которое проверяет, что переданные ему данные — это строка, содержащая адреса электронной почты, разделенные запятыми. Класс такого поля будет выглядеть следующим образом:
Каждая форма, использующая такое поле, будет вызывать эти методы до выполнения всех остальных действий с данными поля. Такая проверка привязана к этому типу поля и не зависит от дальнейшего его использования.
Проверка атрибута определённого поля¶
Очистка и проверка полей, которые зависят друг от друга¶
К моменту вызова метода формы clean() все clean() методы полей уже отработали. Таким образом, свойство формы self.cleaned_data будет заполнено данными, прошедшими проверку. Следовательно, надо принять во внимание возможность того, что данные некоторых полей не прошли начальную поверку.
В данном коде, при возникновении ошибки во время проверки данных, форма отобразит сообщение об ошибке сверху (обычное поведение), описывая проблему.
Следует отметить, что вызов super(ContactForm, self).clean() в приведенном коде обеспечивает выполнение дополнительной проверки средствами базового класса.
Второй способ подразумевает назначение ошибки одному из полей. В нашем случае, давайте назначим сообщение об ошибке обоим полям («subject» и «cc_myself») при отображении формы. Использовать этот способ надо аккуратно, так как он может запутать пользователя. Мы лишь показываем возможные варианты, оставляя решение конкретной задачи вам и вашим дизайнерам. Наш новый код (заменяющий предыдущий пример) выглядит так: