From 638bab2cabceb76b03798fd15f4f2905c9fdf94c Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Wed, 8 Feb 2017 08:38:08 -0500 Subject: [PATCH] [1.11.x] Fixed #27821 -- Clarified docs of the return value of Form.clean_(). Thanks Christian Ullrich for the report and review. Backport of 8863c475c53f2b44113f25b749a124a5bf3a02f2 from master --- docs/ref/forms/validation.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt index b57f44cb6c..719175e9f1 100644 --- a/docs/ref/forms/validation.txt +++ b/docs/ref/forms/validation.txt @@ -69,8 +69,9 @@ overridden: formfield-specific piece of validation and, possibly, cleaning/normalizing the data. - This method should return the cleaned value obtained from ``cleaned_data``, - regardless of whether it changed anything or not. + The return value of this method replaces the existing value in + ``cleaned_data``, so it must be the field's value from ``cleaned_data`` (even + if this method didn't change it) or a new cleaned value. * 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 @@ -315,8 +316,8 @@ write a cleaning method that operates on the ``recipients`` field, like so:: 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. + # Always return a value to use as the new cleaned data, even if + # this method didn't change it. return data .. _validating-fields-with-clean: