Form-level errors

CHANGES.rst

@@ -25,6 +25,7 @@ Unreleased
     :pr:`608`
 -   Choices shortcut for :class:`~fields.core.SelectMultipleField`.
     :issue:`603` :pr:`605`
+-   Forms can have form-level errors. :issue:`55` :pr:`595`
 
 
 Version 2.3.1

docs/forms.rst

@@ -47,6 +47,15 @@ The Form class
         A dict containing a list of errors for each field. Empty if the form
         hasn't been validated, or there were no errors.
 
+        If present, the key ``None`` contains the content of
+        :attr:`~wtforms.forms.Form.form_errors`.
+
+    .. attribute:: form_errors
+
+        A list of form-level errors. Those are errors that does not concern a
+        particuliar field, but the whole form consistency. Those errors are
+        often set when overriding :meth:`~wtforms.forms.Form.validate`.
+
     .. attribute:: meta
 
         This is an object which contains various configuration options and also

src/wtforms/fields/core.py

@@ -398,7 +398,7 @@ def bind(self, form, name, prefix="", translations=None, **kwargs):
 
     def __repr__(self):
         return "<UnboundField({}, {!r}, {!r})>".format(
-            self.field_class.__name__, self.args, self.kwargs,
+            self.field_class.__name__, self.args, self.kwargs
         )
 
 

src/wtforms/form.py

@@ -46,6 +46,8 @@ def __init__(self, fields, prefix="", meta=_default_meta):
             field = meta.bind_field(self, unbound_field, options)
             self._fields[name] = field
 
+        self.form_errors = []
+
     def __iter__(self):
         """Iterate form fields in creation order."""
         return iter(self._fields.values())
@@ -140,7 +142,10 @@ def data(self):
 
     @property
     def errors(self):
-        return {name: f.errors for name, f in self._fields.items() if f.errors}
+        errors = {name: f.errors for name, f in self._fields.items() if f.errors}
+        if self.form_errors:
+            errors[None] = self.form_errors
+        return errors
 
 
 class FormMeta(type):

tests/test_fields.py

@@ -1154,7 +1154,7 @@ def _build_value(self, key, form_input, expected_html, data=unset_value):
             data = form_input
         if expected_html.startswith("type="):
             expected_html = '<input id="{}" name="{}" {} value="{}">'.format(
-                key, key, expected_html, form_input,
+                key, key, expected_html, form_input
             )
         return {
             "key": key,

tests/test_form.py

@@ -174,6 +174,31 @@ def extra(form, field):
         form = F2(test="nope", other="extra")
         assert not form.validate(extra_validators={"other": [extra]})
 
+    def test_form_level_errors(self):
+        class F(Form):
+            a = IntegerField()
+            b = IntegerField()
+
+            def validate(self):
+                if not super().validate():
+                    return False
+
+                if (self.a.data + self.b.data) % 2 != 0:
+                    self.form_errors.append("a + b should be even")
+                    return False
+
+                return True
+
+        f = F(a=1, b=1)
+        assert f.validate()
+        assert not f.form_errors
+        assert not f.errors
+
+        f = F(a=0, b=1)
+        assert not f.validate()
+        assert ["a + b should be even"] == f.form_errors
+        assert ["a + b should be even"] == f.errors[None]
+
     def test_field_adding_disabled(self):
         form = self.F()
         with pytest.raises(TypeError):