Documentation of the return value of clean_<fieldname>() could be clarified

[Christian Ullrich]

The documentation on form validation (/ref/forms/validation/) has this to say regarding the clean_<fieldname> method on a Form subclass:

This method should return the cleaned value obtained from cleaned_data, regardless of whether it changed anything or not.

This is incorrect; the method should return the value to be used for further processing, because its result is unconditionally put into cleaned_data:

(from django.forms.forms.Form._clean_fields():)

if hasattr(self, 'clean_%s' % name):
                    value = getattr(self, 'clean_%s' % name)()
                    self.cleaned_data[name] = value

[Tim Graham]

I see how the current wording could be interpreted incorrectly. What do you think of this proposal:

docs/ref/forms/validation.txt

@@ -69 +69 @@
   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 is inserted into the form's ``cleaned_data``,
+  so it must be the field's value from ``cleaned_data`` (even if you 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 +316 @@
             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:

[Christian Ullrich]

"The return value of this method replaces the existing value in cleaned_data, so [...]", perhaps? Otherwise it looks good to me.

[Tim Graham <timograham@…>]

In 8863c475:

Fixed #27821 -- Clarified docs of the return value of Form.clean_<fieldname>().

Thanks Christian Ullrich for the report and review.

[Tim Graham <timograham@…>]

In 638bab2c:

[1.11.x] Fixed #27821 -- Clarified docs of the return value of Form.clean_<fieldname>().

Thanks Christian Ullrich for the report and review.

Backport of 8863c475c53f2b44113f25b749a124a5bf3a02f2 from master

[Tim Graham <timograham@…>]

In f993872:

[1.10.x] Fixed #27821 -- Clarified docs of the return value of Form.clean_<fieldname>().

Thanks Christian Ullrich for the report and review.

Backport of 8863c475c53f2b44113f25b749a124a5bf3a02f2 from master