Add new exception ExtraItemsError

CHANGES.rst

@@ -9,6 +9,9 @@ Platform
 Features
 ~~~~~~~~
 
+- Add new exception ExtraItemsError. Used to pass to the caller a list of extra
+  field detected in cstruct.
+
 - Add ``min_err`` and ``max_err`` arguments to ``Length``, thus allowing
   customization of its error messages.
 

CONTRIBUTORS.txt

@@ -125,3 +125,4 @@ Contributors
 - Nando Florestan, 2014/11/27
 - Amos Latteier, 2014/11/30
 - Jimmy Thrasibule, 2014/12/11
+- Dmitry Bogun, 2015/09/10

colander/__init__.py

@@ -205,6 +205,18 @@ def __str__(self):
         result of an execution of this exception's ``asdict`` method"""
         return pprint.pformat(self.asdict())
 
+
+class ExtraItemsError(Invalid):
+    """
+    Exception used when schema object detect "extra" fields in cstruct during
+    deserialize.
+    """
+
+    def __init__(self, node, extras, msg=_('Unrecognized items')):
+        super(ExtraItemsError, self).__init__(node, msg)
+        self.extras = extras
+
+
 class All(object):
     """ Composite validator which succeeds if none of its
     subvalidators raises an :class:`colander.Invalid` exception"""
@@ -640,11 +652,10 @@ def _impl(self, node, value, callback):
 
         if self.unknown == 'raise':
             if value:
-                raise Invalid(
-                    node,
-                    _('Unrecognized keys in mapping: "${val}"',
-                      mapping={'val':value})
-                    )
+                raise ExtraItemsError(
+                    node, value,
+                    msg=_('Unrecognized keys in mapping: "${val}"',
+                          mapping={'val': value}))
 
         elif self.unknown == 'preserve':
             result.update(value)

docs/api.rst

@@ -48,6 +48,15 @@ Exceptions
        from a widget as the value which should be redisplayed when an
        error is shown.
 
+  .. autoclass:: ExtraItemsError
+
+     .. attribute:: extras
+
+        The ``dict`` with all detected extra field and their values.
+
+        Node that contain extra fields can be located by position of
+        this exception into exception tree hierarchy.
+
   .. autoclass:: UnboundDeferredError