验证器¶
编写验证器¶
验证器是一个可调用对象,它接受一个值,如果不符合某些条件,则会引发 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)[源代码]¶
- 参数:
一个
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"
。
EmailValidator
¶
- class EmailValidator(message=None, code=None, allowlist=None)[源代码]¶
- 参数:
EmailValidator
确保一个值看起来像一个电子邮件,并且如果不是,则引发带有message
和code
的ValidationError
。长度超过 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)[源代码]¶
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)[源代码]¶
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 协议 列表。警告
以
file:///
开头的值即使提供了file
方案也不会通过验证。有效值必须包含主机信息。
- max_length¶
可以被视为有效的值的最大长度。默认为 2048 个字符。
validate_email
¶
- validate_email¶
一个
EmailValidator
实例,没有任何自定义。
validate_domain_name
¶
- 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[源代码]¶
一个
RegexValidator
实例,确保一个值看起来像一个 IPv4 地址。
validate_ipv6_address
¶
validate_ipv46_address
¶
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¶
如果验证失败,
ValidationError
使用的错误信息。默认值为"Null characters are not allowed."
。
- code¶
当验证失败时
ValidationError
所使用的错误代码。默认为"null_characters_not_allowed"
。
StepValueValidator
¶
- class StepValueValidator(limit_value, message=None, offset=None)[源代码]¶
如果
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
参数。