Валидаторы

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

Валидатор — это вызываемый объект, который принимает значение и вызывает исключение 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 содержит набор вызываемых валидаторов для использования с полями моделей и форм. Они используются во внутренней работе, но также доступны для использования с вашими собственными полями. Их можно использовать дополнительно к или вместо пользовательских field.clean() методов.

`RegexValidator`

class RegexValidator(regex=None, message=None, code=None, inverse_match=None, flags=0) [source]

Параметры:

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) [source]

Параметры:

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`

Новое в Django 5.1.

class DomainNameValidator(accept_idna=True, message=None, code=None) [source]

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

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

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

`URLValidator`

class URLValidator(schemes=None, regex=None, message=None, code=None) [source]

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

Циклические адреса и зарезервированные IP-пространства считаются валидными. Поддерживаются литеральные IPv6-адреса (RFC 3986 Раздел 3.2.2) и доменные имена с Unicode.

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

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

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

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

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

`validate_email`

validate_email: Экземпляр EmailValidator без настроек.

`validate_domain_name`

Новое в Django 5.1.

validate_domain_name: Экземпляр DomainNameValidator без настроек.

`validate_slug`

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

`validate_unicode_slug`

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

`validate_ipv4_address`

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

`validate_ipv6_address`

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

`validate_ipv46_address`

validate_ipv46_address [source]: Использует как 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) [source]: Возвращает экземпляр RegexValidator, который проверяет, состоит ли строка из целых чисел, разделённых sep. Разрешает отрицательные целые числа, если allow_negative равно True.

`MaxValueValidator`

class MaxValueValidator(limit_value, message=None) [source]: Вызывает ValidationError с кодом 'max_value', если value больше, чем limit_value, которое может быть вызываемой функцией.

`MinValueValidator`

class MinValueValidator(limit_value, message=None) [source]: Вызывает ValidationError с кодом 'min_value', если value меньше, чем limit_value, которое может быть вызываемой функцией.

`MaxLengthValidator`

class MaxLengthValidator(limit_value, message=None) [source]: Вызывает ValidationError с кодом 'max_length', если длина value больше, чем limit_value, которое может быть вызываемой функцией.

`MinLengthValidator`

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

`DecimalValidator`

class DecimalValidator(max_digits, decimal_places) [source]

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

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

`FileExtensionValidator`

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

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

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

`validate_image_file_extension`

validate_image_file_extension [source]: Использует Pillow для проверки того, что value.name (value это File) имеет валидное расширение изображения.

`ProhibitNullCharactersValidator`

class ProhibitNullCharactersValidator(message=None, code=None) [source]

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

Параметры:

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) [source]: Вызывает ValidationError с кодом 'step_size', если value не является целым кратным limit_value, которое может быть значением с плавающей точкой, целым числом или десятичным значением, или вызываемым объектом. Если 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/5.2/ref/validators/