フォームのバリデーションは、データがクリーニング (clean) されるときに実行されます。このプロセスをカスタムしたい場合は、様々な箇所に変更を加えることができ、それぞれが違う目的を持っています。クリーニング方法のうち 3 タイプは、フォームのプロセス中に実行されます。これらは、通常フォーム上の is_valid() メソッドを呼び出したときに実行されます。このほかにも、クリーニングとバリデーションのトリガーとなる処理 (直接 errors 属性にアクセスしたり、 full_clean() を直接呼び出す) がありますが、通常必要とはなりません。
一般的に、あらゆるクリーニング方法は ValidationError を投げる可能性があります。処理されるデータに問題がある場合、関連情報を ValidationError コンストラクタに渡します。下記項目 に、ValidationError を投げる際のベストプラクティスがあります。ValidationError が投げられない場合、メソッドはクリーニングされた (標準化された) データを Python オブジェクトとして返すはずです。
大半のバリデーションは、validators を使って行うことができます- シンプルなヘルパーで、再利用も簡単です。バリデータはシンプルな関数 (ないしカラブル) で、単一の引数を取り無効な入力において ValidationError を投げます。 バリデータは、フィールド to_python と validate メソッドが呼び出された後に実行されます。
フォームのバリデーションは複数のステップに分割されます。カスタムやオーバーライドすることができます:
\nField の to_python() メソッドはすべてのバリデーションの最初のステップとなります。これは、値をデータ型に正すことを強制し、それができない場合は ValidationError を投げます。このメソッドはウィジェットからそのままの値を受け取り、変換した値を返します。たとえば、FloatField は Python の float に変換されるか、もしくは ValidationError を投げます。
Field の validate() メソッドは、フィールド特有のバリデーションを行います。これはバリデータとしては不適です。正しいデータ型を強制された値を取り、エラーの際は ValidationError を投げます。このメソッドは何も返さず、また値の変更も行わないはずです。バリデータに記述したくないバリデーションロジックを実行するためには、このメソッドをオーバーライドしてください。
Field の run_validators() メソッドはフィールドのバリデータをすべて実行し、すべてのエラーを単一の ValidationError に統合します。このメソッドをオーバーライドする必要はないはずです。
Field サブクラスの clean() メソッドは、to_python()、validate()、run_validators() を正しい順序で実行し、エラーを伝達する役目を負っています。もしこの過程のどこかで ValidationError が投げられた場合、バリデーションは停止し、そのエラーを投げます。このメソッドはクリーニングされたデータを返し、フォームの cleaned_data ディクショナリに格納します。
clean_<fieldname>() メソッドは、フォームサブクラス上で呼び出されます -- <fieldname> がフォームのフィールド属性の名前と置き換えられます。このメソッドは、フィールドのタイプにかかわらず、その特定の属性に対するクリーニングを実行します。 このメソッドはパラメータを受け取りません。self.cleaned_data 内のフィールドの値を検索する必要があり、またこの時点ではフォーム上で元々送信された文字列ではなく Python オブジェクトであること覚えておいてください (これは cleaned_data 内にあります。上記に出てきた一般フィールドの clean() メソッドがすでに一度データをクリーニングしているからです)。
たとえば、 serialnumber と呼ばれる CharField の内容がユニークであることをバリデートしたいとき、 clean_serialnumber() が最も適切な場所となり得ます。 特定のフィールド (この場合 CharField) は必要ありませんが、フォームのフィールドに紐付いたバリデーションと、おそらくデータのクリーニングおよび標準化も必要となるでしょう。
このメソッドの戻り値は cleaned_data 内の既存の値を置き換えるため、(たとえこのメソッドが変更しなかったとしても) cleaned_data からのフィールドの値、ないし新しくクリーニングされた値になるはずです。
フォームのサブクラスの crean() メソッドは、複数のフォームフィールドにまたがるバリデーションにも使用できます。この場所には、たとえば「フィールド A が入力されたときフィールド B は有効なメールアドレスのはず」といったチェックを記述できます。このメソッドは、必要な場合はまったく違うディクショナリを返すこともでき、その場合は cleaned_data として使用されます。
フィールドバリデーションのメソッドは clean() が呼ばれる際に実行されるので、フォームの errors 属性にもアクセスできるようになります。これは各フィールドのクリーニングによって発生した例外をすべて含みます。
Form.clean() をオーバーライドして発生させた例外は、特定のフィールドに結びつかない点に注意してください。これらは特別な "フィールド" (__all__ と呼ばれます) に格納され、必要に応じて non_field_errors() メソッドを通じてアクセスできます。特定のフィールドにエラーを紐付けて格納したい場合は、add_error() を呼び出す必要があります。
ModelForm サブクラスの clean() メソッドをオーバーライドする際、特に考慮する点がまだあります (詳しくは ModelForm ドキュメント を参照してください)。
これらのメソッドは、一度に一つのフィールドに対し、先述した通りの順番で実行されます。フォーム内の各フィールドに対して (フォームの定義時に宣言された順序で)、Field.clean() メソッド (ないしそのオーバーライド) が実行され、その後 clean_<fieldname>() が実行されます。最後に、この 2 つのメソッドが全フィールドに対して実行された後、これらのメソッドでエラーが発生したかどうかにかかわらず Form.clean() メソッド (ないしそのオーバーライド) が実行されます。
各メソッドの例は後述します。
\n上述の通り、どのメソッドでも ValidationError が発生する可能性があります。どのフィールドに対しても、Field.clean() メソッドが ValidationError を発生させた場合、フィールド特有のクリーニングメソッドは呼ばれません。一方で、すべての残りのフィールドに対するクリーニングメソッドは呼び出されます。
ValidationError を発生させるLink to this heading#エラーメッセージを柔軟かつ簡単にオーバーライドできるようにするため、以下のガイドラインを検討してください:
\n説明のための code をコンストラクタに渡します:
# Good\nValidationError(_('Invalid value'), code='invalid')\n\n# Bad\nValidationError(_('Invalid value'))\nメッセージには変数を強制しません; プレースホルダとコンストラクタの params 引数を使用します:
# Good\nValidationError(\n _('Invalid value: %(value)s'),\n params={'value': '42'},\n)\n\n# Bad\nValidationError(_('Invalid value: %s') % value)\n位置指定ではなく、マッピングキーを使います。
\n# Good\nValidationError(\n _('Invalid value: %(value)s'),\n params={'value': '42'},\n)\n\n# Bad\nValidationError(\n _('Invalid value: %s'),\n params=('42',),\n)\nメッセージを gettext でラップし、翻訳できるようにします:
# Good\nValidationError(_('Invalid value'))\n\n# Bad\nValidationError('Invalid value')\n全てを一緒に記述すると以下のようになります:
\nraise ValidationError(\n _('Invalid value: %(value)s'),\n code='invalid',\n params={'value': '42'},\n)\n再利用可能なフォーム、フォームフィールド、モデルフィールドを記述した場合、特にこのガイドラインの遵守が必要となります。
\n推奨はされませんが、バリデーションチェーンの最後で (例えばフォームの clean() メソッド) エラーメッセージのオーバーライドを 決してしない ことが確かな場合は、より簡潔に記述することもできます:
ValidationError(_('Invalid value: %s') % value)\nForm.errors.as_data() や Form.errors.as_json() メソッドは、十分な機能を有する (code 名と params ディクショナリを持つ) ValidationError により大きな恩恵を受けます。
クリーニングメソッド内で複数のエラーを検証し、すべてのエラーをフォーム送信者に知らせたい場合、ValidationError コンストラクタにエラーのリストを引き渡すことが可能です。
上述の通り、ValidationError インスタンスには code と params を渡すことが推奨されていますが、文字列のリストも使うことができます:
# Good\nraise ValidationError([\n ValidationError(_('Error 1'), code='error1'),\n ValidationError(_('Error 2'), code='error2'),\n])\n\n# Bad\nraise ValidationError([\n _('Error 1'),\n _('Error 2'),\n])\n前のセクションでは、フォームに対する検証が一般にどのように働くかを説明しました。実際の使われ方を見た方が機能をよく理解できるということが往々にしてあります。ここでは、説明した各機能を使った一連の小さな使用例を説明します。
\nDjango のフォーム (とモデル) のフィールドは、バリデータと呼ばれるシンプルなユーティリティ関数とクラスの使用をサポートしています。バリデータはただのカラブルオブジェクトか関数で、値を取って、値が有効な場合は何も返さず、無効な場合は ValidationError を返します。フィールドの validators 引数を通してフィールドのコンストラクタに渡すことができます。もしくは、Field クラス自身で default_validators 属性を使って定義できます。
シンプルなバリデータはフィールドの内部で値を検証するために使用できます。Django の SlugField を見てみましょう:
from django.core import validators\nfrom django.forms import CharField\n\nclass SlugField(CharField):\n default_validators = [validators.validate_slug]\n見ての通り、SlugField はカスタマイズされたバリデータを伴う CharField で、このバリデータは送信されたテキストがいくつかの文字列ルールに従うかどうかを検証します。これはフィールド定義においても実装可能です:
slug = forms.SlugField()\nこれは以下と同じです:
\nslug = forms.CharField(validators=[validators.validate_slug])\n一般的なケース (例えば、E メールや正規表現に対する検証) は、Django が提供する既存のバリデータクラスを使って処理できます。例えば、validators.validate_slug は RegexValidator の第 1 引数をパターン ^[-a-zA-Z0-9_]+$ としたインスタンスです。バリデータを記述する のセクションを参照して、利用可能なバリデータのリストとバリデータの記述方法の例を確認できます。
まず、カンマで区切られたメールアドレスを含むかどうか検証するカスタムフォームフィールドを作成しましょう。クラスの全体像は以下のようになります:
\nfrom django import forms\nfrom django.core.validators import validate_email\n\nclass MultiEmailField(forms.Field):\n def to_python(self, value):\n """Normalize data to a list of strings."""\n # Return an empty list if no input was given.\n if not value:\n return []\n return value.split(',')\n\n def validate(self, value):\n """Check if value consists only of valid emails."""\n # Use the parent's handling of required fields, etc.\n super().validate(value)\n for email in value:\n validate_email(email)\nこのフィールドを使うすべてのフォームでは、フィールドのデータを使えるようになる前に、これらのメソッドが実行されます。これはこのタイプのフィールドに特有であり、それはこの後の使われ方には関係ありません。
\nシンプルな ContactForm を作って、このフィールドをどのように使うか見てみましょう:
class ContactForm(forms.Form):\n subject = forms.CharField(max_length=100)\n message = forms.CharField()\n sender = forms.EmailField()\n recipients = MultiEmailField()\n cc_myself = forms.BooleanField(required=False)\n他のフォームフィールドと同様に MultiEmailField を使用してください。フォーム上で is_valid() が呼び出されたとき、 クリーニングプロセスの一環として MultiEmailField.clean() メソッドが実行され、to_python() と validate() を順番に呼び出します。
上の例を引き続き使用して、ContactForm の recipients フィールドが常に``"fred@example.com"`` を含むようにしたいとします。これはフォームに特有のバリデーションなので、MultiEmailField クラスには記述したくありません。代わりに recipients フィールドで動作するクリーニングメソッドを記述します:
from django import forms\n\nclass ContactForm(forms.Form):\n # Everything as before.\n ...\n\n def clean_recipients(self):\n data = self.cleaned_data['recipients']\n if "fred@example.com" not in data:\n raise forms.ValidationError("You have forgotten about Fred!")\n\n # Always return a value to use as the new cleaned data, even if\n # this method didn't change it.\n return data\nコンタクトフォームに新たな要件を追加することを考えます: cc_myself フィールドが True の場合、subject には必ず "help" という言葉が含まれるという要件です。この場合、複数のフィールドにまたがったバリデーションを行うので、フォームの clean() メソッドで行うのが適切です。ここで注意すべきなのは、今扱っているのはフォームの clean() メソッドであり、上記で扱ってきたフィールドの clean() ではないということです。バリデーションを記述すする場所を決める際は、フィールドとフォームの違いを明確にすることが重要です。 フィールドは単一のデータポイントであり、フォームはフィールドの集まりです。
フォームの clean() メソッドが呼び出されるまでに、個別のフィールドのクリーンメソッドが呼び出されているので (上記 2 つのセクションで見た通りです)、self.cleaned_data にはこれまでのクリーニングで生き残ったデータが格納されています。したがって、検証しようとしているフィールドが、この個別フィールドのチェックを生き残っていない可能性を考慮する必要があります。
この段階でのエラーを通知するには 2 つの方法があります。おそらく最も一般的な方法は、フォームのトップでエラーを表示する方法です。このようなエラーを生成するには、crean() メソッドで ValidationError を発生させてください。例えば:
from django import forms\n\nclass ContactForm(forms.Form):\n # Everything as before.\n ...\n\n def clean(self):\n cleaned_data = super().clean()\n cc_myself = cleaned_data.get("cc_myself")\n subject = cleaned_data.get("subject")\n\n if cc_myself and subject:\n # Only do something if both fields are valid so far.\n if "help" not in subject:\n raise forms.ValidationError(\n "Did not send for 'help' in the subject despite "\n "CC'ing yourself."\n )\nこのコードではバリデーションエラーが発生すると、フォームのトップにエラーメッセージを表示し、(通常は) 問題を伝えます。
\n例のコードにある super().clean() の呼び出しは、親クラスのバリデーションロジックも維持されることを保証します。clean() メソッドで (必須ではないので) cleaned_data ディクショナリを返さないクラスを継承している場合、cleaned_data を super() の結果にアサインせず、代わりに self.cleaned_data を使用してください:
def clean(self):\n super().clean()\n cc_myself = self.cleaned_data.get("cc_myself")\n ...\nバリデーションエラーを通知するもう 1 つのアプローチは、エラーメッセージをフィールドの 1 つにアサインすることです。この場合、エラーメッセージはフォーム表示の "subject" と "cc_myself" の両方の行にアサインしましょう。この方法をとるときは、フォームの出力に混乱を招かないように注意してください。ここでは何が可能なのかを示しますが、実際の状況で効果的に実装するのはあなたとあなたのデザイナー次第です。(上の例を置き換えた) 新しいコードは以下のようになります:
\nfrom django import forms\n\nclass ContactForm(forms.Form):\n # Everything as before.\n ...\n\n def clean(self):\n cleaned_data = super().clean()\n cc_myself = cleaned_data.get("cc_myself")\n subject = cleaned_data.get("subject")\n\n if cc_myself and subject and "help" not in subject:\n msg = "Must put 'help' in subject when cc'ing yourself."\n self.add_error('cc_myself', msg)\n self.add_error('subject', msg)\nadd_error() の第 2 引数にはただの文字列か、できれば ValidationError のインスタンスを指定します。詳しくは ValidationError を発生させる を参照してください。add_error() は cleaned_data からフィールドを自動的に削除してしまうことに注意してください。