Add new exception ExtraItemsError

This allow caller to analise errors from extra fields programmatically.
Without this error type to know which fields treated as "extra" caller
must parse error string.

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