--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/parts/django/docs/ref/forms/validation.txt Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,366 @@
+Form and field validation
+=========================
+
+.. versionchanged:: 1.2
+
+Form validation happens when the data is cleaned. If you want to customize
+this process, there are various places you can change, each one serving a
+different purpose. Three types of cleaning methods are run during form
+processing. These are normally executed when you call the ``is_valid()``
+method on a form. There are other things that can trigger cleaning and
+validation (accessing the ``errors`` attribute or calling ``full_clean()``
+directly), but normally they won't be needed.
+
+In general, any cleaning method can raise ``ValidationError`` if there is a
+problem with the data it is processing, passing the relevant error message to
+the ``ValidationError`` constructor. If no ``ValidationError`` is raised, the
+method should return the cleaned (normalized) data as a Python object.
+
+If you detect multiple errors during a cleaning method and wish to signal all
+of them to the form submitter, it is possible to pass a list of errors to the
+``ValidationError`` constructor.
+
+Most validation can be done using `validators`_ - simple helpers that can be
+reused easily. Validators are simple functions (or callables) that take a single
+argument and raise ``ValidationError`` on invalid input. Validators are run
+after the field's ``to_python`` and ``validate`` methods have been called.
+
+Validation of a Form is split into several steps, which can be customized or
+overridden:
+
+ * The ``to_python()`` method on a Field is the first step in every
+ validation. It coerces the value to correct datatype and raises
+ ``ValidationError`` if that is not possible. This method accepts the raw
+ value from the widget and returns the converted value. For example, a
+ FloatField will turn the data into a Python ``float`` or raise a
+ ``ValidationError``.
+
+ * The ``validate()`` method on a Field handles field-specific validation
+ that is not suitable for a validator, It takes a value that has been
+ coerced to correct datatype and raises ``ValidationError`` on any error.
+ This method does not return anything and shouldn't alter the value. You
+ should override it to handle validation logic that you can't or don't
+ want to put in a validator.
+
+ * The ``run_validators()`` method on a Field runs all of the field's
+ validators and aggregates all the errors into a single
+ ``ValidationError``. You shouldn't need to override this method.
+
+ * The ``clean()`` method on a Field subclass. This is responsible for
+ running ``to_python``, ``validate`` and ``run_validators`` in the correct
+ order and propagating their errors. If, at any time, any of the methods
+ raise ``ValidationError``, the validation stops and that error is raised.
+ This method returns the clean data, which is then inserted into the
+ ``cleaned_data`` dictionary of the form.
+
+ * The ``clean_<fieldname>()`` method in a form subclass -- where
+ ``<fieldname>`` is replaced with the name of the form field attribute.
+ This method does any cleaning that is specific to that particular
+ attribute, unrelated to the type of field that it is. This method is not
+ passed any parameters. You will need to look up the value of the field
+ in ``self.cleaned_data`` and remember that it will be a Python object
+ at this point, not the original string submitted in the form (it will be
+ in ``cleaned_data`` because the general field ``clean()`` method, above,
+ has already cleaned the data once).
+
+ For example, if you wanted to validate that the contents of a
+ ``CharField`` called ``serialnumber`` was unique,
+ ``clean_serialnumber()`` would be the right place to do this. You don't
+ need a specific field (it's just a ``CharField``), but you want a
+ formfield-specific piece of validation and, possibly,
+ cleaning/normalizing the data.
+
+ Just like the general field ``clean()`` method, above, this method
+ should return the cleaned data, regardless of whether it changed
+ anything or not.
+
+ * The Form subclass's ``clean()`` method. This method can perform
+ any validation that requires access to multiple fields from the form at
+ once. This is where you might put in things to check that if field ``A``
+ is supplied, field ``B`` must contain a valid e-mail address and the
+ like. The data that this method returns is the final ``cleaned_data``
+ attribute for the form, so don't forget to return the full list of
+ cleaned data if you override this method (by default, ``Form.clean()``
+ just returns ``self.cleaned_data``).
+
+ Note that any errors raised by your ``Form.clean()`` override will not
+ be associated with any field in particular. They go into a special
+ "field" (called ``__all__``), which you can access via the
+ ``non_field_errors()`` method if you need to. If you want to attach
+ errors to a specific field in the form, you will need to access the
+ ``_errors`` attribute on the form, which is `described later`_.
+
+ Also note that there are special considerations when overriding
+ the ``clean()`` method of a ``ModelForm`` subclass. (see the
+ :ref:`ModelForm documentation
+ <overriding-modelform-clean-method>` for more information)
+
+These methods are run in the order given above, one field at a time. That is,
+for each field in the form (in the order they are declared in the form
+definition), the ``Field.clean()`` method (or its override) is run, then
+``clean_<fieldname>()``. Finally, once those two methods are run for every
+field, the ``Form.clean()`` method, or its override, is executed.
+
+Examples of each of these methods are provided below.
+
+As mentioned, any of these methods can raise a ``ValidationError``. For any
+field, if the ``Field.clean()`` method raises a ``ValidationError``, any
+field-specific cleaning method is not called. However, the cleaning methods
+for all remaining fields are still executed.
+
+The ``clean()`` method for the ``Form`` class or subclass is always run. If
+that method raises a ``ValidationError``, ``cleaned_data`` will be an empty
+dictionary.
+
+The previous paragraph means that if you are overriding ``Form.clean()``, you
+should iterate through ``self.cleaned_data.items()``, possibly considering the
+``_errors`` dictionary attribute on the form as well. In this way, you will
+already know which fields have passed their individual validation requirements.
+
+.. _described later:
+
+Form subclasses and modifying field errors
+------------------------------------------
+
+Sometimes, in a form's ``clean()`` method, you will want to add an error
+message to a particular field in the form. This won't always be appropriate
+and the more typical situation is to raise a ``ValidationError`` from
+``Form.clean()``, which is turned into a form-wide error that is available
+through the ``Form.non_field_errors()`` method.
+
+When you really do need to attach the error to a particular field, you should
+store (or amend) a key in the ``Form._errors`` attribute. This attribute is an
+instance of a ``django.forms.util.ErrorDict`` class. Essentially, though, it's
+just a dictionary. There is a key in the dictionary for each field in the form
+that has an error. Each value in the dictionary is a
+``django.forms.util.ErrorList`` instance, which is a list that knows how to
+display itself in different ways. So you can treat ``_errors`` as a dictionary
+mapping field names to lists.
+
+If you want to add a new error to a particular field, you should check whether
+the key already exists in ``self._errors`` or not. If not, create a new entry
+for the given key, holding an empty ``ErrorList`` instance. In either case,
+you can then append your error message to the list for the field name in
+question and it will be displayed when the form is displayed.
+
+There is an example of modifying ``self._errors`` in the following section.
+
+.. admonition:: What's in a name?
+
+ You may be wondering why is this attribute called ``_errors`` and not
+ ``errors``. Normal Python practice is to prefix a name with an underscore
+ if it's not for external usage. In this case, you are subclassing the
+ ``Form`` class, so you are essentially writing new internals. In effect,
+ you are given permission to access some of the internals of ``Form``.
+
+ Of course, any code outside your form should never access ``_errors``
+ directly. The data is available to external code through the ``errors``
+ property, which populates ``_errors`` before returning it).
+
+ Another reason is purely historical: the attribute has been called
+ ``_errors`` since the early days of the forms module and changing it now
+ (particularly since ``errors`` is used for the read-only property name)
+ would be inconvenient for a number of reasons. You can use whichever
+ explanation makes you feel more comfortable. The result is the same.
+
+Using validation in practice
+----------------------------
+
+The previous sections explained how validation works in general for forms.
+Since it can sometimes be easier to put things into place by seeing each
+feature in use, here are a series of small examples that use each of the
+previous features.
+
+.. _validators:
+
+Using validators
+~~~~~~~~~~~~~~~~
+.. versionadded:: 1.2
+
+Django's form (and model) fields support use of simple utility functions and
+classes known as validators. These can be passed to a field's constructor, via
+the field's ``validators`` argument, or defined on the Field class itself with
+the ``default_validators`` attribute.
+
+Simple validators can be used to validate values inside the field, let's have
+a look at Django's ``EmailField``::
+
+ class EmailField(CharField):
+ default_error_messages = {
+ 'invalid': _(u'Enter a valid e-mail address.'),
+ }
+ default_validators = [validators.validate_email]
+
+As you can see, ``EmailField`` is just a ``CharField`` with customized error
+message and a validator that validates e-mail addresses. This can also be done
+on field definition so::
+
+ email = forms.EmailField()
+
+is equivalent to::
+
+ email = forms.CharField(validators=[validators.validate_email],
+ error_messages={'invalid': _(u'Enter a valid e-mail address.')})
+
+
+Form field default cleaning
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's firstly create a custom form field that validates its input is a string
+containing comma-separated e-mail addresses. The full class looks like this::
+
+ from django import forms
+ from django.core.validators import validate_email
+
+ class MultiEmailField(forms.Field):
+ def to_python(self, value):
+ "Normalize data to a list of strings."
+
+ # Return an empty list if no input was given.
+ if not value:
+ return []
+ return value.split(',')
+
+ def validate(self, value):
+ "Check if value consists only of valid emails."
+
+ # Use the parent's handling of required fields, etc.
+ super(MultiEmailField, self).validate(value)
+
+ for email in value:
+ validate_email(email)
+
+Every form that uses this field will have these methods run before anything
+else can be done with the field's data. This is cleaning that is specific to
+this type of field, regardless of how it is subsequently used.
+
+Let's create a simple ``ContactForm`` to demonstrate how you'd use this
+field::
+
+ class ContactForm(forms.Form):
+ subject = forms.CharField(max_length=100)
+ message = forms.CharField()
+ sender = forms.EmailField()
+ recipients = MultiEmailField()
+ cc_myself = forms.BooleanField(required=False)
+
+Simply use ``MultiEmailField`` like any other form field. When the
+``is_valid()`` method is called on the form, the ``MultiEmailField.clean()``
+method will be run as part of the cleaning process and it will, in turn, call
+the custom ``to_python()`` and ``validate()`` methods.
+
+Cleaning a specific field attribute
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Continuing on from the previous example, suppose that in our ``ContactForm``,
+we want to make sure that the ``recipients`` field always contains the address
+``"fred@example.com"``. This is validation that is specific to our form, so we
+don't want to put it into the general ``MultiEmailField`` class. Instead, we
+write a cleaning method that operates on the ``recipients`` field, like so::
+
+ class ContactForm(forms.Form):
+ # Everything as before.
+ ...
+
+ def clean_recipients(self):
+ data = self.cleaned_data['recipients']
+ if "fred@example.com" not in data:
+ raise forms.ValidationError("You have forgotten about Fred!")
+
+ # Always return the cleaned data, whether you have changed it or
+ # not.
+ return data
+
+Cleaning and validating fields that depend on each other
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Suppose we add another requirement to our contact form: if the ``cc_myself``
+field is ``True``, the ``subject`` must contain the word ``"help"``. We are
+performing validation on more than one field at a time, so the form's
+``clean()`` method is a good spot to do this. Notice that we are talking about
+the ``clean()`` method on the form here, whereas earlier we were writing a
+``clean()`` method on a field. It's important to keep the field and form
+difference clear when working out where to validate things. Fields are single
+data points, forms are a collection of fields.
+
+By the time the form's ``clean()`` method is called, all the individual field
+clean methods will have been run (the previous two sections), so
+``self.cleaned_data`` will be populated with any data that has survived so
+far. So you also need to remember to allow for the fact that the fields you
+are wanting to validate might not have survived the initial individual field
+checks.
+
+There are two way to report any errors from this step. Probably the most
+common method is to display the error at the top of the form. To create such
+an error, you can raise a ``ValidationError`` from the ``clean()`` method. For
+example::
+
+ class ContactForm(forms.Form):
+ # Everything as before.
+ ...
+
+ def clean(self):
+ cleaned_data = self.cleaned_data
+ cc_myself = cleaned_data.get("cc_myself")
+ subject = cleaned_data.get("subject")
+
+ if cc_myself and subject:
+ # Only do something if both fields are valid so far.
+ if "help" not in subject:
+ raise forms.ValidationError("Did not send for 'help' in "
+ "the subject despite CC'ing yourself.")
+
+ # Always return the full collection of cleaned data.
+ return cleaned_data
+
+In this code, if the validation error is raised, the form will display an
+error message at the top of the form (normally) describing the problem.
+
+The second approach might involve assigning the error message to one of the
+fields. In this case, let's assign an error message to both the "subject" and
+"cc_myself" rows in the form display. Be careful when doing this in practice,
+since it can lead to confusing form output. We're showing what is possible
+here and leaving it up to you and your designers to work out what works
+effectively in your particular situation. Our new code (replacing the previous
+sample) looks like this::
+
+ class ContactForm(forms.Form):
+ # Everything as before.
+ ...
+
+ def clean(self):
+ cleaned_data = self.cleaned_data
+ cc_myself = cleaned_data.get("cc_myself")
+ subject = cleaned_data.get("subject")
+
+ if cc_myself and subject and "help" not in subject:
+ # We know these are not in self._errors now (see discussion
+ # below).
+ msg = u"Must put 'help' in subject when cc'ing yourself."
+ self._errors["cc_myself"] = self.error_class([msg])
+ self._errors["subject"] = self.error_class([msg])
+
+ # These fields are no longer valid. Remove them from the
+ # cleaned data.
+ del cleaned_data["cc_myself"]
+ del cleaned_data["subject"]
+
+ # Always return the full collection of cleaned data.
+ return cleaned_data
+
+As you can see, this approach requires a bit more effort, not withstanding the
+extra design effort to create a sensible form display. The details are worth
+noting, however. Firstly, earlier we mentioned that you might need to check if
+the field name keys already exist in the ``_errors`` dictionary. In this case,
+since we know the fields exist in ``self.cleaned_data``, they must have been
+valid when cleaned as individual fields, so there will be no corresponding
+entries in ``_errors``.
+
+Secondly, once we have decided that the combined data in the two fields we are
+considering aren't valid, we must remember to remove them from the
+``cleaned_data``.
+
+In fact, Django will currently completely wipe out the ``cleaned_data``
+dictionary if there are any errors in the form. However, this behaviour may
+change in the future, so it's not a bad idea to clean up after yourself in the
+first place.