Fixed #20867 -- Added the Form.add_error() method.

Refs #20199 #16986.

Thanks @akaariai, @bmispelon, @mjtamlyn, @timgraham for the reviews.

3 files changed, 51 insertions, 0 deletions

diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index c15f748308..c06a836bef 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -117,6 +117,26 @@ The validation routines will only get called once, regardless of how many times
 you access :attr:`~Form.errors` or call :meth:`~Form.is_valid`. This means that
 if validation has side effects, those side effects will only be triggered once.
 
+.. method:: Form.add_error(field, error)
+
+.. versionadded:: 1.7
+
+This method allows adding errors to specific fields from within the
+``Form.clean()`` method, or from outside the form altogether; for instance
+from a view. This is a better alternative to fiddling directly with
+``Form._errors`` as described in :ref:`modifying-field-errors`.
+
+The ``field`` argument is the name of the field to which the errors
+should be added. If its value is ``None`` the error will be treated as
+a non-field error as returned by ``Form.non_field_errors()``.
+
+The ``error`` argument can be a simple string, or preferably an instance of
+``ValidationError``. See :ref:`raising-validation-error` for best practices
+when defining form errors.
+
+Note that ``Form.add_error()`` automatically removes the relevant field from
+``cleaned_data``.
+
 Behavior of unbound forms
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt
index ea294c4108..3c7715dfcb 100644
--- a/docs/ref/forms/validation.txt
+++ b/docs/ref/forms/validation.txt
@@ -464,3 +464,31 @@ 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``. `cleaned_data`` is present even if the form doesn't
 validate, but it contains only field values that did validate.
+
+.. versionchanged:: 1.7
+
+In lieu of manipulating ``_errors`` directly, it's now possible to add errors
+to specific fields with :meth:`django.forms.Form.add_error()`::
+
+    from django import forms
+
+    class ContactForm(forms.Form):
+        # Everything as before.
+        ...
+
+        def clean(self):
+            cleaned_data = super(ContactForm, self).clean()
+            cc_myself = cleaned_data.get("cc_myself")
+            subject = cleaned_data.get("subject")
+
+            if cc_myself and subject and "help" not in subject:
+                msg = u"Must put 'help' in subject when cc'ing yourself."
+                self.add_error('cc_myself', msg)
+                self.add_error('subject', msg)
+
+The second argument of ``add_error()`` can be a simple string, or preferably
+an instance of ``ValidationError``. See :ref:`raising-validation-error` for
+more details.
+
+Unlike the ``_errors`` approach, ``add_error()` automatically removes the field
+from ``cleaned_data``.
diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index 9cb907aded..0767659540 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -350,6 +350,9 @@ Forms
 * It's now possible to opt-out from a ``Form`` field declared in a parent class
   by shadowing it with a non-``Field`` value.
 
+* The new :meth:`~django.forms.Form.add_error()` method allows adding errors
+  to specific form fields.
+
 Internationalization
 ^^^^^^^^^^^^^^^^^^^^