验证器

编写验证器

验证器是一个可调用对象，它接受一个值，如果不符合某些条件，则会引发 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，它将在你的表单中包含的任何字段上运行验证器。请参阅 模型表单文档，了解模型验证如何与表单交互。

内置验证器

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 用 re.search() 为给定的正则表达式搜索提供的 value。默认情况下，如果没有 找到 匹配的，会引发一个 ValidationError，包含 message 和 code。它的行为可以通过将 inverse_match 设置为 True 来反转，在这种情况下，当 找到 匹配的时，就会引发 ValidationError。

regex

使用 re.search() 在提供的 value 中搜索的正则表达式模式。可以是一个字符串，也可以是用 re.compile() 创建的预先编译的正则表达式。默认为空字符串，将在所有可能的 value 中找到。

message

当验证失败时 ValidationError 使用的错误信息。默认值为 "Enter a valid value"。

code

ValidationError 验证失败时使用的错误代码。默认值为 "invalid"。

inverse_match

regex 的匹配模式。默认为 False。

flags

在编译正则表达式字符串 regex 时使用的 regex flags。如果 regex 是一个预先编译的正则表达式，并且 flags 被覆盖，则 TypeError 被引发。默认值为 0。

EmailValidator

class EmailValidator(message=None, code=None, allowlist=None)[source]
参数:

  • message -- 如果不是 None，则覆盖 message。

  • code -- 如果不是 None，则覆盖 code。

  • allowlist -- 如果不是 None，则覆盖 allowlist。

EmailValidator 确保一个值看起来像一个电子邮件，并且如果不是，则引发带有 message 和 code 的 ValidationError。长度超过 320 个字符的值总是被认为是无效的。

message

如果验证失败， ValidationError 使用的错误信息。默认为 "Enter a valid email address"。

code

ValidationError 验证失败时使用的错误代码。默认值为 "invalid"。

allowlist

电子邮件域名的允许列表。默认情况下，会使用正则表达式（domain_regex 属性）来验证出现在 @ 符号后面的内容。但是，如果该字符串出现在 allowlist 中，将绕过此验证。如果未提供，默认的 allowlist 是 ['localhost']。其他不包含点的域名将无法通过验证，因此您需要根据需要将它们添加到 allowlist 中。

DomainNameValidator

New in Django 5.1.
class DomainNameValidator(accept_idna=True, message=None, code=None)[source]

A RegexValidator subclass that ensures a value looks like a domain name. Values longer than 255 characters are always considered invalid. IP addresses are not accepted as valid domain names.

In addition to the optional arguments of its parent RegexValidator class, DomainNameValidator accepts an extra optional attribute:

accept_idna

Determines whether to accept internationalized domain names, that is, domain names that contain non-ASCII characters. Defaults to True.

URLValidator

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

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 协议 列表。

Warning

以 file:/// 开头的值即使提供了 file 方案也不会通过验证。有效值必须包含主机信息。

max_length

可以被视为有效的值的最大长度。默认为 2048 个字符。

validate_email

validate_email

一个 EmailValidator 实例，没有任何自定义。

validate_domain_name

New in Django 5.1.
validate_domain_name

A DomainNameValidator instance without any customizations.

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]

如果 value 大于 limit_value，会引发一个 ValidationError，代码为 'max_value'，这可能是一个可调用对象。

MinValueValidator

class MinValueValidator(limit_value, message=None)[source]

如果 value 小于 limit_value，会引发一个 ValidationError，代码为 'min_value'，这可能是一个可调用对象。

MaxLengthValidator

class MaxLengthValidator(limit_value, message=None)[source]

如果 value 的长度大于 limit_value，会引发一个 ValidationError，代码为 'max_length'。

MinLengthValidator

class MinLengthValidator(limit_value, message=None)[source]

如果 value 小于 limit_value，会引发一个 ValidationError，代码为 'min_length'，这可能是一个可调用对象。

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]

如果 value.name （value 是一个 File`）的扩展名没有在 allowed_extensions 中找到，会引发一个 ValidationError，代码为 'invalid_extension'。该扩展名将与 allowed_extensions 进行不区分大小写的比较。

Warning

不要依赖文件扩展名的验证来确定文件的类型。文件可以重命名为任何扩展名，无论它们包含什么数据。

validate_image_file_extension

validate_image_file_extension[source]

使用 Pillow 确保 value.name （value 是一个 File）具有 一个有效的图像扩展名 。

ProhibitNullCharactersValidator

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

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

如果 value 不是 limit_value 的整数倍，其中 limit_value 可以是浮点数、整数、小数值或可调用对象，则会引发一个代码为 'step_size' 的 ValidationError。当设置了 offset 时，验证将针对 limit_value 加上 offset 进行。例如，对于 StepValueValidator(3, offset=1.4)，有效的值包括 1.4、4.4、7.4、10.4 等等。

Changed in Django 5.0:

添加了 offset 参数。

Back to Top