Валидаторы

Написание валидаторов

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

Например, вот валидатор, который разрешает только чётные числа:

from django.core.exceptions import ValidationError
from django.utils.translation import gettext_lazy as _


def validate_even(value):
    if value % 2 != 0:
        raise ValidationError(
            _("%(value)s is not an even number"),
            params={"value": value},
        )

Его можно добавить в поле модели с помощью аргумента validators этого поля:

from django.db import models


class MyModel(models.Model):
    even_field = models.IntegerField(validators=[validate_even])

Поскольку значения преобразуются в Python до запуска валидаторов, один и тот же валидатор можно использовать даже с формами:

from django import forms


class MyForm(forms.Form):
    even_field = forms.IntegerField(validators=[validate_even])

Для более сложных валидаторов или валидаторов с настройками также можно использовать класс с методом __call__(). Например, RegexValidator использует этот подход. Если в параметре поля модели validators используется валидатор на основе класса, необходимо убедиться, что он сериализуем средствами системы миграций, добавив методы deconstruct() и __eq__().

Как запускаются валидаторы

Дополнительные сведения о запуске валидаторов в формах см. в разделе проверка форм, а о запуске в моделях — в разделе Проверка объектов. Обратите внимание, что валидаторы не запускаются автоматически при сохранении модели. Однако при использовании ModelForm валидаторы будут запущены для всех полей, включённых в форму. Сведения о взаимодействии проверки моделей с формами см. в документации по ModelForm.

Встроенные валидаторы

Модуль django.core.validators содержит набор вызываемых валидаторов для использования с полями моделей и форм. Они используются внутри Django, но доступны и для использования в собственных полях. Их можно использовать вместе с пользовательскими методами field.clean() или вместо них.

`RegexValidator`

class RegexValidator(regex=None, message=None, code=None, inverse_match=None, flags=0) [источник]

Параметры:

regex – Если значение не None, заменяет regex. Может быть строкой регулярного выражения или предварительно скомпилированным регулярным выражением.
message – Если значение не None, заменяет message.
code – Если значение не None, заменяет code.
inverse_match – Если значение не None, заменяет inverse_match.
flags – Если значение не None, заменяет flags. В этом случае regex должно быть строкой регулярного выражения, иначе будет вызвано исключение TypeError.

RegexValidator ищет в предоставленном значении value заданное регулярное выражение с помощью re.search(). По умолчанию, если совпадение не найдено, вызывается исключение ValidationError с сообщением message и кодом code. Поведение можно инвертировать, задав для inverse_match значение True; в этом случае исключение ValidationError вызывается, когда совпадение найдено.

regex: Шаблон регулярного выражения для поиска в предоставленном значении value с помощью re.search(). Это может быть строка или предварительно скомпилированное регулярное выражение, созданное с помощью re.compile(). По умолчанию используется пустая строка, которая найдётся в любом возможном значении value.

message: Сообщение об ошибке, используемое в ValidationError, если проверка не пройдена. По умолчанию — "Enter a valid value".

code: Код ошибки, используемый в ValidationError, если проверка не пройдена. По умолчанию — "invalid".

inverse_match: Режим сопоставления для regex. По умолчанию — False.

flags: флаги регулярного выражения, используемые при компиляции строки регулярного выражения regex. Если regex — предварительно скомпилированное регулярное выражение, а значение flags переопределено, вызывается исключение TypeError. По умолчанию — 0.

`EmailValidator`

class EmailValidator(message=None, code=None, allowlist=None) [источник]

Параметры:

message – Если значение не None, заменяет message.
code – Если значение не None, заменяет code.
allowlist – Если значение не None, заменяет allowlist.

EmailValidator проверяет, что значение похоже на адрес электронной почты, и если это не так, вызывает исключение ValidationError с сообщением message и кодом code. Значения длиной более 320 символов всегда считаются недопустимыми.

message: Сообщение об ошибке, используемое в ValidationError, если проверка не пройдена. По умолчанию — "Enter a valid email address".

code: Код ошибки, используемый в ValidationError, если проверка не пройдена. По умолчанию — "invalid".

allowlist: Список разрешённых доменов электронной почты. По умолчанию для проверки текста после знака @ используется регулярное выражение (атрибут domain_regex). Однако если эта строка присутствует в allowlist, проверка не выполняется. Если значение не указано, по умолчанию allowlist равно ['localhost']. Другие домены без точки не пройдут проверку, поэтому при необходимости их нужно добавить в allowlist.

`DomainNameValidator`

class DomainNameValidator(accept_idna=True, message=None, code=None) [источник]

Подкласс RegexValidator, проверяющий, что значение похоже на доменное имя. Значения длиной более 255 символов всегда считаются недопустимыми. IP-адреса не принимаются в качестве допустимых доменных имён.

Помимо необязательных аргументов родительского класса RegexValidator, DomainNameValidator принимает дополнительный необязательный атрибут:

accept_idna: Определяет, принимать ли интернационализированные доменные имена, то есть доменные имена, содержащие символы, отличные от ASCII. По умолчанию — True.

`URLValidator`

class URLValidator(schemes=None, regex=None, message=None, code=None) [источник]

Подкласс RegexValidator, проверяющий, что значение похоже на URL, и если это не так, возвращающий код ошибки 'invalid'. Значения длиной более max_length символов всегда считаются недопустимыми.

Адреса обратной петли и зарезервированные диапазоны IP считаются допустимыми. Поддерживаются как IPv6-адреса в буквальной записи (раздел 3.2.2 RFC 3986), так и домены в Юникоде.

Помимо необязательных аргументов родительского класса RegexValidator, URLValidator принимает дополнительный необязательный атрибут:

schemes: Список схем URL/URI для проверки. Если список не указан, используется список по умолчанию ['http', 'https', 'ftp', 'ftps']. Для справки на сайте IANA приведён полный список допустимых схем URI.

Предупреждение

Значения, начинающиеся с file:///, не пройдут проверку, даже если указана схема file. Допустимые значения должны содержать хост.

max_length: Максимальная длина значений, которые могут считаться допустимыми. По умолчанию — 2048 символов.

`validate_email`

validate_email: Экземпляр EmailValidator без дополнительных настроек.

`validate_domain_name`

validate_domain_name: Экземпляр DomainNameValidator без дополнительных настроек.

`validate_slug`

validate_slug: Экземпляр RegexValidator, проверяющий, что значение состоит только из букв, цифр, символов подчёркивания или дефисов.

`validate_unicode_slug`

validate_unicode_slug: Экземпляр RegexValidator, проверяющий, что значение состоит только из букв Юникода, цифр, символов подчёркивания или дефисов.

`validate_ipv4_address`

validate_ipv4_address [источник]: Экземпляр RegexValidator, проверяющий, что значение похоже на IPv4-адрес.

`validate_ipv6_address`

validate_ipv6_address [источник]: Для проверки корректности IPv6-адреса используется django.utils.ipv6.

`validate_ipv46_address`

validate_ipv46_address [источник]: Используются оба валидатора — validate_ipv4_address и validate_ipv6_address, — чтобы проверить, что значение является допустимым IPv4- или IPv6-адресом.

`validate_comma_separated_integer_list`

validate_comma_separated_integer_list: Экземпляр RegexValidator, проверяющий, что значение является списком целых чисел, разделённых запятыми.

`int_list_validator`

int_list_validator(sep=',', message=None, code='invalid', allow_negative=False) [источник]: Возвращает экземпляр RegexValidator, проверяющий, что строка состоит из целых чисел, разделённых sep. Отрицательные целые числа допускаются, если allow_negative равно True.

`MaxValueValidator`

class MaxValueValidator(limit_value, message=None) [источник]: Если value больше limit_value (которое может быть вызываемым объектом), вызывается исключение ValidationError с кодом 'max_value'.

`MinValueValidator`

class MinValueValidator(limit_value, message=None) [источник]: Если value меньше limit_value (которое может быть вызываемым объектом), вызывается исключение ValidationError с кодом 'min_value'.

`MaxLengthValidator`

class MaxLengthValidator(limit_value, message=None) [источник]: Если длина value превышает limit_value (которое может быть вызываемым объектом), вызывается исключение ValidationError с кодом 'max_length'.

`MinLengthValidator`

class MinLengthValidator(limit_value, message=None) [источник]: Если длина value меньше limit_value (которое может быть вызываемым объектом), вызывается исключение ValidationError с кодом 'min_length'.

`DecimalValidator`

class DecimalValidator(max_digits, decimal_places) [источник]

Вызывает исключение ValidationError со следующими кодами:

'max_digits', если количество цифр больше max_digits.
'max_decimal_places', если количество десятичных знаков больше decimal_places.
'max_whole_digits', если количество целых цифр больше разницы между max_digits и decimal_places.

`FileExtensionValidator`

class FileExtensionValidator(allowed_extensions, message, code) [источник]: Если расширение value.name (value является File) не найдено в allowed_extensions, вызывается исключение ValidationError с кодом 'invalid_extension'. Расширение сравнивается без учёта регистра с allowed_extensions.

Предупреждение

Не полагайтесь на проверку расширения файла при определении его типа. Файлам можно присвоить любое расширение независимо от содержащихся в них данных.

`validate_image_file_extension`

validate_image_file_extension [источник]: С помощью Pillow проверяет, что у value.name (value является File) допустимое расширение файла изображения.

`ProhibitNullCharactersValidator`

class ProhibitNullCharactersValidator(message=None, code=None) [источник]

Если str(value) содержит один или несколько нулевых символов ('\x00'), вызывается исключение ValidationError.

Параметры:

message – Если значение не None, заменяет message.
code – Если значение не None, заменяет code.

message: Сообщение об ошибке, используемое в ValidationError, если проверка не пройдена. По умолчанию — "Null characters are not allowed.".

code: Код ошибки, используемый в ValidationError, если проверка не пройдена. По умолчанию — "null_characters_not_allowed".

`StepValueValidator`

class StepValueValidator(limit_value, message=None, offset=None) [источник]: Если value не кратно limit_value (которое может быть числом с плавающей точкой, целым числом, десятичным значением или вызываемым объектом), вызывается исключение ValidationError с кодом 'step_size'. Если задано offset, проверка выполняется относительно суммы limit_value и offset. Например, для StepValueValidator(3, offset=1.4) допустимы значения 1.4, 4.4, 7.4, 10.4 и так далее.

© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/6.0/ref/validators/