|
1 Form and field validation |
|
2 ========================= |
|
3 |
|
4 .. versionchanged:: 1.2 |
|
5 |
|
6 Form validation happens when the data is cleaned. If you want to customize |
|
7 this process, there are various places you can change, each one serving a |
|
8 different purpose. Three types of cleaning methods are run during form |
|
9 processing. These are normally executed when you call the ``is_valid()`` |
|
10 method on a form. There are other things that can trigger cleaning and |
|
11 validation (accessing the ``errors`` attribute or calling ``full_clean()`` |
|
12 directly), but normally they won't be needed. |
|
13 |
|
14 In general, any cleaning method can raise ``ValidationError`` if there is a |
|
15 problem with the data it is processing, passing the relevant error message to |
|
16 the ``ValidationError`` constructor. If no ``ValidationError`` is raised, the |
|
17 method should return the cleaned (normalized) data as a Python object. |
|
18 |
|
19 If you detect multiple errors during a cleaning method and wish to signal all |
|
20 of them to the form submitter, it is possible to pass a list of errors to the |
|
21 ``ValidationError`` constructor. |
|
22 |
|
23 Most validation can be done using `validators`_ - simple helpers that can be |
|
24 reused easily. Validators are simple functions (or callables) that take a single |
|
25 argument and raise ``ValidationError`` on invalid input. Validators are run |
|
26 after the field's ``to_python`` and ``validate`` methods have been called. |
|
27 |
|
28 Validation of a Form is split into several steps, which can be customized or |
|
29 overridden: |
|
30 |
|
31 * The ``to_python()`` method on a Field is the first step in every |
|
32 validation. It coerces the value to correct datatype and raises |
|
33 ``ValidationError`` if that is not possible. This method accepts the raw |
|
34 value from the widget and returns the converted value. For example, a |
|
35 FloatField will turn the data into a Python ``float`` or raise a |
|
36 ``ValidationError``. |
|
37 |
|
38 * The ``validate()`` method on a Field handles field-specific validation |
|
39 that is not suitable for a validator, It takes a value that has been |
|
40 coerced to correct datatype and raises ``ValidationError`` on any error. |
|
41 This method does not return anything and shouldn't alter the value. You |
|
42 should override it to handle validation logic that you can't or don't |
|
43 want to put in a validator. |
|
44 |
|
45 * The ``run_validators()`` method on a Field runs all of the field's |
|
46 validators and aggregates all the errors into a single |
|
47 ``ValidationError``. You shouldn't need to override this method. |
|
48 |
|
49 * The ``clean()`` method on a Field subclass. This is responsible for |
|
50 running ``to_python``, ``validate`` and ``run_validators`` in the correct |
|
51 order and propagating their errors. If, at any time, any of the methods |
|
52 raise ``ValidationError``, the validation stops and that error is raised. |
|
53 This method returns the clean data, which is then inserted into the |
|
54 ``cleaned_data`` dictionary of the form. |
|
55 |
|
56 * The ``clean_<fieldname>()`` method in a form subclass -- where |
|
57 ``<fieldname>`` is replaced with the name of the form field attribute. |
|
58 This method does any cleaning that is specific to that particular |
|
59 attribute, unrelated to the type of field that it is. This method is not |
|
60 passed any parameters. You will need to look up the value of the field |
|
61 in ``self.cleaned_data`` and remember that it will be a Python object |
|
62 at this point, not the original string submitted in the form (it will be |
|
63 in ``cleaned_data`` because the general field ``clean()`` method, above, |
|
64 has already cleaned the data once). |
|
65 |
|
66 For example, if you wanted to validate that the contents of a |
|
67 ``CharField`` called ``serialnumber`` was unique, |
|
68 ``clean_serialnumber()`` would be the right place to do this. You don't |
|
69 need a specific field (it's just a ``CharField``), but you want a |
|
70 formfield-specific piece of validation and, possibly, |
|
71 cleaning/normalizing the data. |
|
72 |
|
73 Just like the general field ``clean()`` method, above, this method |
|
74 should return the cleaned data, regardless of whether it changed |
|
75 anything or not. |
|
76 |
|
77 * The Form subclass's ``clean()`` method. This method can perform |
|
78 any validation that requires access to multiple fields from the form at |
|
79 once. This is where you might put in things to check that if field ``A`` |
|
80 is supplied, field ``B`` must contain a valid e-mail address and the |
|
81 like. The data that this method returns is the final ``cleaned_data`` |
|
82 attribute for the form, so don't forget to return the full list of |
|
83 cleaned data if you override this method (by default, ``Form.clean()`` |
|
84 just returns ``self.cleaned_data``). |
|
85 |
|
86 Note that any errors raised by your ``Form.clean()`` override will not |
|
87 be associated with any field in particular. They go into a special |
|
88 "field" (called ``__all__``), which you can access via the |
|
89 ``non_field_errors()`` method if you need to. If you want to attach |
|
90 errors to a specific field in the form, you will need to access the |
|
91 ``_errors`` attribute on the form, which is `described later`_. |
|
92 |
|
93 Also note that there are special considerations when overriding |
|
94 the ``clean()`` method of a ``ModelForm`` subclass. (see the |
|
95 :ref:`ModelForm documentation |
|
96 <overriding-modelform-clean-method>` for more information) |
|
97 |
|
98 These methods are run in the order given above, one field at a time. That is, |
|
99 for each field in the form (in the order they are declared in the form |
|
100 definition), the ``Field.clean()`` method (or its override) is run, then |
|
101 ``clean_<fieldname>()``. Finally, once those two methods are run for every |
|
102 field, the ``Form.clean()`` method, or its override, is executed. |
|
103 |
|
104 Examples of each of these methods are provided below. |
|
105 |
|
106 As mentioned, any of these methods can raise a ``ValidationError``. For any |
|
107 field, if the ``Field.clean()`` method raises a ``ValidationError``, any |
|
108 field-specific cleaning method is not called. However, the cleaning methods |
|
109 for all remaining fields are still executed. |
|
110 |
|
111 The ``clean()`` method for the ``Form`` class or subclass is always run. If |
|
112 that method raises a ``ValidationError``, ``cleaned_data`` will be an empty |
|
113 dictionary. |
|
114 |
|
115 The previous paragraph means that if you are overriding ``Form.clean()``, you |
|
116 should iterate through ``self.cleaned_data.items()``, possibly considering the |
|
117 ``_errors`` dictionary attribute on the form as well. In this way, you will |
|
118 already know which fields have passed their individual validation requirements. |
|
119 |
|
120 .. _described later: |
|
121 |
|
122 Form subclasses and modifying field errors |
|
123 ------------------------------------------ |
|
124 |
|
125 Sometimes, in a form's ``clean()`` method, you will want to add an error |
|
126 message to a particular field in the form. This won't always be appropriate |
|
127 and the more typical situation is to raise a ``ValidationError`` from |
|
128 ``Form.clean()``, which is turned into a form-wide error that is available |
|
129 through the ``Form.non_field_errors()`` method. |
|
130 |
|
131 When you really do need to attach the error to a particular field, you should |
|
132 store (or amend) a key in the ``Form._errors`` attribute. This attribute is an |
|
133 instance of a ``django.forms.util.ErrorDict`` class. Essentially, though, it's |
|
134 just a dictionary. There is a key in the dictionary for each field in the form |
|
135 that has an error. Each value in the dictionary is a |
|
136 ``django.forms.util.ErrorList`` instance, which is a list that knows how to |
|
137 display itself in different ways. So you can treat ``_errors`` as a dictionary |
|
138 mapping field names to lists. |
|
139 |
|
140 If you want to add a new error to a particular field, you should check whether |
|
141 the key already exists in ``self._errors`` or not. If not, create a new entry |
|
142 for the given key, holding an empty ``ErrorList`` instance. In either case, |
|
143 you can then append your error message to the list for the field name in |
|
144 question and it will be displayed when the form is displayed. |
|
145 |
|
146 There is an example of modifying ``self._errors`` in the following section. |
|
147 |
|
148 .. admonition:: What's in a name? |
|
149 |
|
150 You may be wondering why is this attribute called ``_errors`` and not |
|
151 ``errors``. Normal Python practice is to prefix a name with an underscore |
|
152 if it's not for external usage. In this case, you are subclassing the |
|
153 ``Form`` class, so you are essentially writing new internals. In effect, |
|
154 you are given permission to access some of the internals of ``Form``. |
|
155 |
|
156 Of course, any code outside your form should never access ``_errors`` |
|
157 directly. The data is available to external code through the ``errors`` |
|
158 property, which populates ``_errors`` before returning it). |
|
159 |
|
160 Another reason is purely historical: the attribute has been called |
|
161 ``_errors`` since the early days of the forms module and changing it now |
|
162 (particularly since ``errors`` is used for the read-only property name) |
|
163 would be inconvenient for a number of reasons. You can use whichever |
|
164 explanation makes you feel more comfortable. The result is the same. |
|
165 |
|
166 Using validation in practice |
|
167 ---------------------------- |
|
168 |
|
169 The previous sections explained how validation works in general for forms. |
|
170 Since it can sometimes be easier to put things into place by seeing each |
|
171 feature in use, here are a series of small examples that use each of the |
|
172 previous features. |
|
173 |
|
174 .. _validators: |
|
175 |
|
176 Using validators |
|
177 ~~~~~~~~~~~~~~~~ |
|
178 .. versionadded:: 1.2 |
|
179 |
|
180 Django's form (and model) fields support use of simple utility functions and |
|
181 classes known as validators. These can be passed to a field's constructor, via |
|
182 the field's ``validators`` argument, or defined on the Field class itself with |
|
183 the ``default_validators`` attribute. |
|
184 |
|
185 Simple validators can be used to validate values inside the field, let's have |
|
186 a look at Django's ``EmailField``:: |
|
187 |
|
188 class EmailField(CharField): |
|
189 default_error_messages = { |
|
190 'invalid': _(u'Enter a valid e-mail address.'), |
|
191 } |
|
192 default_validators = [validators.validate_email] |
|
193 |
|
194 As you can see, ``EmailField`` is just a ``CharField`` with customized error |
|
195 message and a validator that validates e-mail addresses. This can also be done |
|
196 on field definition so:: |
|
197 |
|
198 email = forms.EmailField() |
|
199 |
|
200 is equivalent to:: |
|
201 |
|
202 email = forms.CharField(validators=[validators.validate_email], |
|
203 error_messages={'invalid': _(u'Enter a valid e-mail address.')}) |
|
204 |
|
205 |
|
206 Form field default cleaning |
|
207 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
208 |
|
209 Let's firstly create a custom form field that validates its input is a string |
|
210 containing comma-separated e-mail addresses. The full class looks like this:: |
|
211 |
|
212 from django import forms |
|
213 from django.core.validators import validate_email |
|
214 |
|
215 class MultiEmailField(forms.Field): |
|
216 def to_python(self, value): |
|
217 "Normalize data to a list of strings." |
|
218 |
|
219 # Return an empty list if no input was given. |
|
220 if not value: |
|
221 return [] |
|
222 return value.split(',') |
|
223 |
|
224 def validate(self, value): |
|
225 "Check if value consists only of valid emails." |
|
226 |
|
227 # Use the parent's handling of required fields, etc. |
|
228 super(MultiEmailField, self).validate(value) |
|
229 |
|
230 for email in value: |
|
231 validate_email(email) |
|
232 |
|
233 Every form that uses this field will have these methods run before anything |
|
234 else can be done with the field's data. This is cleaning that is specific to |
|
235 this type of field, regardless of how it is subsequently used. |
|
236 |
|
237 Let's create a simple ``ContactForm`` to demonstrate how you'd use this |
|
238 field:: |
|
239 |
|
240 class ContactForm(forms.Form): |
|
241 subject = forms.CharField(max_length=100) |
|
242 message = forms.CharField() |
|
243 sender = forms.EmailField() |
|
244 recipients = MultiEmailField() |
|
245 cc_myself = forms.BooleanField(required=False) |
|
246 |
|
247 Simply use ``MultiEmailField`` like any other form field. When the |
|
248 ``is_valid()`` method is called on the form, the ``MultiEmailField.clean()`` |
|
249 method will be run as part of the cleaning process and it will, in turn, call |
|
250 the custom ``to_python()`` and ``validate()`` methods. |
|
251 |
|
252 Cleaning a specific field attribute |
|
253 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
254 |
|
255 Continuing on from the previous example, suppose that in our ``ContactForm``, |
|
256 we want to make sure that the ``recipients`` field always contains the address |
|
257 ``"fred@example.com"``. This is validation that is specific to our form, so we |
|
258 don't want to put it into the general ``MultiEmailField`` class. Instead, we |
|
259 write a cleaning method that operates on the ``recipients`` field, like so:: |
|
260 |
|
261 class ContactForm(forms.Form): |
|
262 # Everything as before. |
|
263 ... |
|
264 |
|
265 def clean_recipients(self): |
|
266 data = self.cleaned_data['recipients'] |
|
267 if "fred@example.com" not in data: |
|
268 raise forms.ValidationError("You have forgotten about Fred!") |
|
269 |
|
270 # Always return the cleaned data, whether you have changed it or |
|
271 # not. |
|
272 return data |
|
273 |
|
274 Cleaning and validating fields that depend on each other |
|
275 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
276 |
|
277 Suppose we add another requirement to our contact form: if the ``cc_myself`` |
|
278 field is ``True``, the ``subject`` must contain the word ``"help"``. We are |
|
279 performing validation on more than one field at a time, so the form's |
|
280 ``clean()`` method is a good spot to do this. Notice that we are talking about |
|
281 the ``clean()`` method on the form here, whereas earlier we were writing a |
|
282 ``clean()`` method on a field. It's important to keep the field and form |
|
283 difference clear when working out where to validate things. Fields are single |
|
284 data points, forms are a collection of fields. |
|
285 |
|
286 By the time the form's ``clean()`` method is called, all the individual field |
|
287 clean methods will have been run (the previous two sections), so |
|
288 ``self.cleaned_data`` will be populated with any data that has survived so |
|
289 far. So you also need to remember to allow for the fact that the fields you |
|
290 are wanting to validate might not have survived the initial individual field |
|
291 checks. |
|
292 |
|
293 There are two way to report any errors from this step. Probably the most |
|
294 common method is to display the error at the top of the form. To create such |
|
295 an error, you can raise a ``ValidationError`` from the ``clean()`` method. For |
|
296 example:: |
|
297 |
|
298 class ContactForm(forms.Form): |
|
299 # Everything as before. |
|
300 ... |
|
301 |
|
302 def clean(self): |
|
303 cleaned_data = self.cleaned_data |
|
304 cc_myself = cleaned_data.get("cc_myself") |
|
305 subject = cleaned_data.get("subject") |
|
306 |
|
307 if cc_myself and subject: |
|
308 # Only do something if both fields are valid so far. |
|
309 if "help" not in subject: |
|
310 raise forms.ValidationError("Did not send for 'help' in " |
|
311 "the subject despite CC'ing yourself.") |
|
312 |
|
313 # Always return the full collection of cleaned data. |
|
314 return cleaned_data |
|
315 |
|
316 In this code, if the validation error is raised, the form will display an |
|
317 error message at the top of the form (normally) describing the problem. |
|
318 |
|
319 The second approach might involve assigning the error message to one of the |
|
320 fields. In this case, let's assign an error message to both the "subject" and |
|
321 "cc_myself" rows in the form display. Be careful when doing this in practice, |
|
322 since it can lead to confusing form output. We're showing what is possible |
|
323 here and leaving it up to you and your designers to work out what works |
|
324 effectively in your particular situation. Our new code (replacing the previous |
|
325 sample) looks like this:: |
|
326 |
|
327 class ContactForm(forms.Form): |
|
328 # Everything as before. |
|
329 ... |
|
330 |
|
331 def clean(self): |
|
332 cleaned_data = self.cleaned_data |
|
333 cc_myself = cleaned_data.get("cc_myself") |
|
334 subject = cleaned_data.get("subject") |
|
335 |
|
336 if cc_myself and subject and "help" not in subject: |
|
337 # We know these are not in self._errors now (see discussion |
|
338 # below). |
|
339 msg = u"Must put 'help' in subject when cc'ing yourself." |
|
340 self._errors["cc_myself"] = self.error_class([msg]) |
|
341 self._errors["subject"] = self.error_class([msg]) |
|
342 |
|
343 # These fields are no longer valid. Remove them from the |
|
344 # cleaned data. |
|
345 del cleaned_data["cc_myself"] |
|
346 del cleaned_data["subject"] |
|
347 |
|
348 # Always return the full collection of cleaned data. |
|
349 return cleaned_data |
|
350 |
|
351 As you can see, this approach requires a bit more effort, not withstanding the |
|
352 extra design effort to create a sensible form display. The details are worth |
|
353 noting, however. Firstly, earlier we mentioned that you might need to check if |
|
354 the field name keys already exist in the ``_errors`` dictionary. In this case, |
|
355 since we know the fields exist in ``self.cleaned_data``, they must have been |
|
356 valid when cleaned as individual fields, so there will be no corresponding |
|
357 entries in ``_errors``. |
|
358 |
|
359 Secondly, once we have decided that the combined data in the two fields we are |
|
360 considering aren't valid, we must remember to remove them from the |
|
361 ``cleaned_data``. |
|
362 |
|
363 In fact, Django will currently completely wipe out the ``cleaned_data`` |
|
364 dictionary if there are any errors in the form. However, this behaviour may |
|
365 change in the future, so it's not a bad idea to clean up after yourself in the |
|
366 first place. |