From 73b5b0b4a5989f159c6dadcb670ab30b01402382 Mon Sep 17 00:00:00 2001 From: I am Clinton Date: Sat, 23 May 2015 20:57:02 -0500 Subject: [PATCH] Minor edits to docs/ref/forms/validation.txt --- docs/ref/forms/validation.txt | 37 +++++++++++++++++------------------ 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt index 29b2cbd138..c19ae34c29 100644 --- a/docs/ref/forms/validation.txt +++ b/docs/ref/forms/validation.txt @@ -6,10 +6,10 @@ Form and field validation ========================= 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 +this process, there are various places to make changes, 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 +method on a form. There are other things that can also trigger cleaning and validation (accessing the ``errors`` attribute or calling ``full_clean()`` directly), but normally they won't be needed. @@ -25,35 +25,35 @@ 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 +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 +* The ``to_python()`` method on a ``Field`` is the first step in every + validation. It coerces the value to a 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 + ``FloatField`` will turn the data into a Python ``float`` or raise a ``ValidationError``. -* The ``validate()`` method on a Field handles field-specific validation +* 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. + coerced to a 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 +* 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 +* The ``clean()`` method on a ``Field`` subclass 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_()`` method in a form subclass -- where +* The ``clean_()`` method is called on a form subclass -- where ```` 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 @@ -70,15 +70,14 @@ overridden: formfield-specific piece of validation and, possibly, cleaning/normalizing the data. - This method should return the cleaned value obtained from cleaned_data, + This method should return the cleaned value obtained from ``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 email address and the - like. This method can return a completely different dictionary if it wishes, - which will be used as the ``cleaned_data``. +* The form subclass's ``clean()`` method can perform validation that requires + access to multiple form fields. This is where you might put in checks such as + "if field ``A``is supplied, field ``B`` must contain a valid email address". + This method can return a completely different dictionary if it wishes, which + will be used as the ``cleaned_data``. Since the field validation methods have been run by the time ``clean()`` is called, you also have access to the form's ``errors`` attribute which