バリデータ (Validator)

バリデータを記述する

バリデータ (validator) は呼び出し可能なオブジェクトで、値を受け取り、ある基準を満たしていない場合に 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__() メソッドを追加して マイグレーションフレームワークによりシリアライズ可能 になるようにしてください。

バリデータはどのように実行されるか

バリデータが実行される方法については、フォーム上での実行は フォームのバリデーション、モデル上の実行は オブジェクトを検証する にそれぞれ詳細が記載されています。モデルを save してもバリデータは自動的には呼び出されませんが、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() で検索します。デフォルトでは、一致が 見つからない 場合に message と code を持つ ValidationError を発生させます。inverse_match を True に設定することで、動作を逆にできます。この場合、一致が 見つかった ときに ValidationError が発生します。

regex

re.search() を使用して、指定された value 内を検索する正規表現パターンです。これは文字列か re.compile() で作成されたコンパイル済みの正規表現です。 デフォルトは空文字列で、すべての value から検索されます。

message

バリデーションが失敗した場合に ValidationError で使用されるエラーメッセージです。デフォルトは "Enter a valid value" です。

code

バリデーションが失敗した場合に ValidationError で使用されるエラーコードです。デフォルトは "invalid" です。

inverse_match

regex に対する match モードです。デフォルトは False です。

flags

正規表現の文字列 regex とともにコンパイルに使われる regex フラグ です。regex にコンパイル済みの正規表現を指定した場合、flags をオーバーライドすると TypeError が発生します。デフォルトは 0 です。

EmailValidator

class EmailValidator(message=None, code=None, allowlist=None)

パラメータ:	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 に追加する必要があります。

Changed in 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のウェブサイトに valid URI schemes の完全なリストがあります。

警告

file:/// で始まる値は、 file スキームが指定されていてもバリデーションを通過しません。ホスト名を追加する必要があります。

max_length

New in Django 3.2.20.

有効な値とみなされる最大長。デフォルトは2048文字です。

Changed in Django 3.2.20:

古いバージョンでは、2048文字より長い値が有効とみなされることがありました。

validate_email

validate_email

カスタマイズされていない EmailValidator インスタンスです。

validate_slug

validate_slug

値が文字、数字、アンダースコアまたはハイフンのみで構成されていることを確認する RegexValidator インスタンスです。

validate_unicode_slug

validate_unicode_slug

値が Unicode 文字、数字、アンダースコア、またはハイフンのみで構成されていることを確認する RegexValidator インスタンスです。

validate_ipv4_address

validate_ipv4_address

値がIPv4アドレスとして解釈可能であることを保証する RegexValidator インスタンスです。

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)

文字列が sep で区切られた整数で構成されていることを確認する RegexValidator インスタンスを返します。これは allow_negative が True の場合に負の整数を許容します。

MaxValueValidator

class MaxValueValidator(limit_value, message=None)

value が limit_value よりも大きい場合、'max_value' のエラーコードを持つ ValidationError を発生させます。limit_value には呼び出し可能オブジェクトを指定可能です。

MinValueValidator

class MinValueValidator(limit_value, message=None)

value が limit_value よりも小さい場合、'min_value' のエラーコードを持つ ValidationError を発生させます。limit_value には呼び出し可能オブジェクトを指定できます。

MaxLengthValidator

class MaxLengthValidator(limit_value, message=None)

value が limit_value よりも長い場合、'max_length' のエラーコードを持つ ValidationError を発生させます。limit_value には呼び出し可能オブジェクトを指定できます。

MinLengthValidator

class MinLengthValidator(limit_value, message=None)

value が limit_value よりも短い場合、'min_length' のエラーコードを持つ ValidationError を発生させます。limit_value には呼び出し可能オブジェクトを指定できます。

DecimalValidator

class DecimalValidator(max_digits, decimal_places)

以下のコードで ValidationError を例外を発生させます：

• 桁数が max_digits より大きい場合は 'max_digits' 。
• 小数点以下の桁数が decimal_places より大きい場合は 'max_decimal_places' 。
• 整数部の桁数が max_digits と decimal_places の差よりも大きい場合は、'max_whole_digits' 。

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) に null 文字 ('˶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)

値が limit_value の整数倍でない場合、 ValidationError を 'step_size' のコードで発生させます。 offset が設定されている場合は、 limit_value と offset を足した値に対してバリデーションが行われます。たとえば、 StepValueValidator(3, offset=1.4) の場合、有効な値は 1.4、4.4、7.4、10.4 などです。

Changed in Django 5.0:

offset 引数が追加されました。