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

Refs #20199 #16986.

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

1 files changed, 20 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~