Проверка форм и полей

Вызов нескольких ошибок

Если во время очистки вы обнаружили несколько ошибок и хотите сообщить о них отправителю формы, можно передать список ошибок конструктору ValidationError.

Как и выше, рекомендуется передавать список экземпляров ValidationError с атрибутами code и params, но подойдет и список строк:

# Good
raise ValidationError(
    [
        ValidationError(_("Error 1"), code="error1"),
        ValidationError(_("Error 2"), code="error2"),
    ]
)

# Bad
raise ValidationError(
    [
        _("Error 1"),
        _("Error 2"),
    ]
)

Использование валидаторов

Поля форм (и моделей) Django поддерживают вспомогательные функции и классы, называемые валидаторами. Валидатор — это вызываемый объект или функция, которая принимает значение и ничего не возвращает, если оно допустимо, либо вызывает ValidationError, если значение недопустимо. Валидаторы можно передать конструктору поля через аргумент validators или определить непосредственно в классе Field с помощью атрибута default_validators.

Валидаторы можно использовать для проверки значений внутри поля. Рассмотрим SlugField в Django:

from django.core import validators
from django.forms import CharField


class SlugField(CharField):
    default_validators = [validators.validate_slug]

Как видно, SlugField — это CharField с настраиваемым валидатором, проверяющим, соответствует ли отправленный текст определенным правилам для символов. Это можно сделать и при определении поля:

slug = forms.SlugField()

что эквивалентно следующему:

slug = forms.CharField(validators=[validators.validate_slug])

Для распространенных случаев, например проверки адреса электронной почты или соответствия регулярному выражению, можно использовать готовые классы валидаторов Django. Например, validators.validate_slug — это экземпляр RegexValidator, созданный с шаблоном в качестве первого аргумента: ^[-a-zA-Z0-9_]+\Z. Список доступных валидаторов и пример создания собственного валидатора приведены в разделе создание валидаторов.

Очистка данных поля формы по умолчанию

Для начала создадим пользовательское поле формы, проверяющее, что его значение — строка с адресами электронной почты, разделенными запятыми. Полный класс выглядит так:

from django import forms
from django.core.validators import validate_email


class MultiEmailField(forms.Field):
    def to_python(self, value):
        """Normalize data to a list of strings."""
        # Return an empty list if no input was given.
        if not value:
            return []
        return value.split(",")

    def validate(self, value):
        """Check if value consists only of valid emails."""
        # Use the parent's handling of required fields, etc.
        super().validate(value)
        for email in value:
            validate_email(email)

Для каждой формы, использующей это поле, эти методы будут выполняться до того, как с данными поля можно будет сделать что-либо еще. Это очистка, относящаяся к данному типу поля, независимо от дальнейшего использования.

Создадим ContactForm, чтобы показать, как использовать это поле:

class ContactForm(forms.Form):
    subject = forms.CharField(max_length=100)
    message = forms.CharField()
    sender = forms.EmailField()
    recipients = MultiEmailField()
    cc_myself = forms.BooleanField(required=False)

Используйте MultiEmailField как любое другое поле формы. При вызове метода is_valid() формы метод MultiEmailField.clean() будет выполнен в рамках процесса очистки и, в свою очередь, вызовет пользовательские методы to_python() и validate().

Очистка определенного атрибута поля

Продолжим предыдущий пример: предположим, что в нашем ContactForm мы хотим убедиться, что поле recipients всегда содержит адрес "fred@example.com". Эта проверка относится к конкретной форме, поэтому мы не хотим помещать ее в общий класс MultiEmailField. Вместо этого мы напишем метод очистки для поля recipients, например:

from django import forms
from django.core.exceptions import ValidationError


class ContactForm(forms.Form):
    # Everything as before.
    ...

    def clean_recipients(self):
        data = self.cleaned_data["recipients"]
        if "fred@example.com" not in data:
            raise ValidationError("You have forgotten about Fred!")

        # Always return a value to use as the new cleaned data, even if
        # this method didn't change it.
        return data

Очистка и проверка взаимозависимых полей

Предположим, мы добавим еще одно требование к нашей контактной форме: если поле cc_myself имеет значение True, поле subject должно содержать слово "help". Мы проверяем сразу несколько полей, поэтому для этого подойдет метод clean() формы. Обратите внимание: здесь речь идет о методе clean() формы, тогда как ранее мы писали метод clean() для поля. При выборе места для проверок важно различать поля и формы. Поля — это отдельные элементы данных, а формы представляют собой набор полей.

К моменту вызова метода clean() формы будут выполнены все методы очистки отдельных полей (описанные в двух предыдущих разделах), поэтому self.cleaned_data будет содержать все данные, прошедшие предыдущие проверки. Поэтому следует учитывать, что поля, которые нужно проверить, могли не пройти начальные проверки отдельных полей.

Есть два способа сообщить об ошибках на этом этапе. Чаще всего ошибку отображают в верхней части формы. Чтобы создать такую ошибку, можно вызвать ValidationError из метода clean(). Например:

from django import forms
from django.core.exceptions import ValidationError


class ContactForm(forms.Form):
    # Everything as before.
    ...

    def clean(self):
        cleaned_data = super().clean()
        cc_myself = cleaned_data.get("cc_myself")
        subject = cleaned_data.get("subject")

        if cc_myself and subject:
            # Only do something if both fields are valid so far.
            if "help" not in subject:
                raise ValidationError(
                    "Did not send for 'help' in the subject despite CC'ing yourself."
                )

В этом коде, если будет вызвана ошибка проверки, в верхней части формы (обычно) отобразится сообщение с описанием проблемы. Такие ошибки не связаны с конкретным полем; в шаблоне они отображаются с помощью {{ form.non_field_errors }}.

Вызов super().clean() в примере гарантирует, что логика проверки родительских классов сохранится. Если ваша форма наследуется от другой формы, метод clean() которой не возвращает словарь cleaned_data (это необязательно), не присваивайте cleaned_data результату вызова super() и используйте вместо этого self.cleaned_data:

def clean(self):
    super().clean()
    cc_myself = self.cleaned_data.get("cc_myself")
    ...

Второй способ сообщить об ошибках проверки — назначить сообщение об ошибке одному из полей. В этом примере назначим сообщение об ошибке строкам “subject” и “cc_myself” в отображении формы. Будьте осторожны при использовании этого способа: он может привести к непонятному отображению формы. Здесь мы показываем возможный вариант, а вам и вашим дизайнерам предстоит решить, что лучше подойдет для конкретной ситуации. Новый код (заменяющий предыдущий пример) выглядит так:

from django import forms


class ContactForm(forms.Form):
    # Everything as before.
    ...

    def clean(self):
        cleaned_data = super().clean()
        cc_myself = cleaned_data.get("cc_myself")
        subject = cleaned_data.get("subject")

        if cc_myself and subject and "help" not in subject:
            msg = "Must put 'help' in subject when cc'ing yourself."
            self.add_error("cc_myself", msg)
            self.add_error("subject", msg)

Второй аргумент add_error() может быть строкой, но предпочтительнее передавать экземпляр ValidationError. Подробнее см. в разделе Вызов ValidationError. Обратите внимание: add_error() автоматически удаляет поле из cleaned_data.