Валидаторы

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

Валидатор — это вызываемый объект, который принимает значение и поднимает исключение 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)

Параметры:

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 по мере необходимости.

Изменено в Django 3.2.20:

В более ранних версиях значения, длина которых превышала 320 символов, могли считаться валидными.

URLValidator

class URLValidator(schemes=None, regex=None, message=None, code=None)

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

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

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

schemes

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

max_length

Новое в Django 3.2.20.

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

Изменено в Django 3.2.20:

В более ранних версиях значения, длина которых превышала 2048 символов, могли считаться валидными.

validate_email

validate_email

Экземпляр EmailValidator без каких-либо настроек.

validate_slug

validate_slug

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

validate_unicode_slug

validate_unicode_slug

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

validate_ipv4_address

validate_ipv4_address

Экземпляр RegexValidator, который проверяет, соответствует ли значение формату IPv4-адреса.

validate_ipv6_address

validate_ipv6_address

Использует django.utils.ipv6 для проверки валидности 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)

Выводит ValidationError с кодом 'max_value', если значение value больше, чем limit_value, которое может быть вызываемой функцией.

MinValueValidator

class MinValueValidator(limit_value, message=None)

Выводит ValidationError с кодом 'min_value', если значение value меньше, чем limit_value, которое может быть вызываемой функцией.

MaxLengthValidator

class MaxLengthValidator(limit_value, message=None)

Выводит ValidationError с кодом 'max_length', если длина value больше, чем limit_value, которое может быть вызываемой функцией.

MinLengthValidator

class MinLengthValidator(limit_value, message=None)

Выводит ValidationError с кодом 'min_length', если длина value меньше, чем limit_value, которое может быть вызываемой функцией.

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)

Вызывает ValidationError с кодом 'invalid_extension' если расширение value.name (value — это File) не найдено в allowed_extensions. Расширение сравнивается с allowed_extensions без учёта регистра.

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

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

validate_image_file_extension

validate_image_file_extension

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

ProhibitNullCharactersValidator

class ProhibitNullCharactersValidator(message=None, code=None)

Вызывает 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)

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

Изменено в Django 5.0:

Добавлен аргумент offset.