From 465122e037f0cf856e3286831cf220897613cdea Mon Sep 17 00:00:00 2001
From: Dmitry Bogun <dbogun@mirantis.com>
Date: Wed, 9 Sep 2015 22:35:38 -0500
Subject: [PATCH] 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          |  3 +++
 CONTRIBUTORS.txt     |  1 +
 colander/__init__.py | 21 ++++++++++++++++-----
 docs/api.rst         |  9 +++++++++
 4 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 0b3c91b..bdf98b1 100644
--- a/CHANGES.rst
+++ b/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.
 
diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt
index 81031f0..6892752 100644
--- a/CONTRIBUTORS.txt
+++ b/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
diff --git a/colander/__init__.py b/colander/__init__.py
index 20695ea..f3d03a5 100644
--- a/colander/__init__.py
+++ b/colander/__init__.py
@@ -205,6 +205,18 @@ class Invalid(Exception):
         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 @@ class Mapping(SchemaType):
 
         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)
diff --git a/docs/api.rst b/docs/api.rst
index e3584c8..33a25b9 100644
--- a/docs/api.rst
+++ b/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