ENH: wrap to_dict() tracebacks for more user-friendly errors

altair/utils/schemapi.py

@@ -3,8 +3,10 @@
 import collections
 import contextlib
 import json
+import textwrap
 
 import jsonschema
+import six
 
 
 # If DEBUG_MODE is True, then schema objects are converted to dict and
@@ -36,6 +38,35 @@ def debug_mode(arg):
         DEBUG_MODE = original
 
 
+class SchemaValidationError(jsonschema.ValidationError):
+    """A wrapper for jsonschema.ValidationError with friendlier traceback"""
+    def __init__(self, obj, err):
+        super(SchemaValidationError, self).__init__(**err._contents())
+        self.obj = obj
+
+    def __unicode__(self):
+        cls = self.obj.__class__
+        schema_path = ['{0}.{1}'.format(cls.__module__,cls.__name__)]
+        schema_path.extend(self.schema_path)
+        schema_path = ' ->'.join(val for val in schema_path[:-1]
+                                if val not in ('properties',
+                                               'additionalProperties',
+                                               'patternProperties'))
+        return """Invalid specification
+
+        {0}, validating {1!r}
+
+        {2}
+        """.format(schema_path, self.validator, self.message)
+
+    if six.PY3:
+        __str__ = __unicode__
+    else:
+        def __str__(self):
+            return unicode(self).encode("utf-8")
+
+
+
 class UndefinedType(object):
     """A singleton object for marking undefined attributes"""
     __instance = None
@@ -146,9 +177,11 @@ def to_dict(self, validate=True, ignore=[], context={}):
 
         Parameters
         ----------
-        validate : boolean
+        validate : boolean or string
             If True (default), then validate the output dictionary
-            against the schema.
+            against the schema. If "deep" then recursively validate
+            all objects in the spec. This takes much more time, but
+            it results in friendlier tracebacks for large objects.
         ignore : list
             A list of keys to ignore. This will *not* passed to child to_dict
             function calls.
@@ -166,10 +199,11 @@ def to_dict(self, validate=True, ignore=[], context={}):
         jsonschema.ValidationError :
             if validate=True and the dict does not conform to the schema
         """
-        # TODO: add validate='once' and validate='deep'
+        sub_validate = 'deep' if validate == 'deep' else False
+
         def _todict(val):
             if isinstance(val, SchemaBase):
-                return val.to_dict(validate=False, context=context)
+                return val.to_dict(validate=sub_validate, context=context)
             elif isinstance(val, list):
                 return [_todict(v) for v in val]
             elif isinstance(val, dict):
@@ -187,7 +221,10 @@ def _todict(val):
             raise ValueError("{0} instance has both a value and properties : "
                              "cannot serialize to dict".format(self.__class__))
         if validate:
-            self.validate(result)
+            try:
+                self.validate(result)
+            except jsonschema.ValidationError as err:
+                raise SchemaValidationError(self, err)
         return result
 
     @classmethod

altair/vegalite/api.py

@@ -1 +1 @@
-from .v1.api import *
+from .v2.api import *

altair/vegalite/schema.py

@@ -1,3 +1,3 @@
 """Altair schema wrappers"""
 
-from .v1.schema import *
+from .v2.schema import *

altair/vegalite/v2/api.py

@@ -202,7 +202,16 @@ def to_dict(self, *args, **kwargs):
             context['data'] = original_data
         kwargs['context'] = context
 
-        dct = super(TopLevelMixin, copy).to_dict(*args, **kwargs)
+        try:
+            dct = super(TopLevelMixin, copy).to_dict(*args, **kwargs)
+        except jsonschema.ValidationError:
+            dct = None
+
+        # If we hit an error, then re-convert with validate='deep' to get
+        # a more useful traceback
+        if dct is None:
+            kwargs['validate'] = 'deep'
+            dct = super(TopLevelMixin, copy).to_dict(*args, **kwargs)
 
         if is_top_level:
             # since this is top-level we add $schema if it's missing
@@ -412,7 +421,11 @@ def _wrap_in_channel_class(obj, prop):
 
             if 'value' in obj:
                 clsname += 'Value'
-            cls = getattr(channels, clsname)
+
+            try:
+                cls = getattr(channels, clsname)
+            except AttributeError:
+                raise ValueError("Unrecognized encoding channel '{0}'".format(prop))
 
             try:
                 # Don't force validation here; some objects won't be valid until

tools/schemapi/schemapi.py

@@ -1,8 +1,10 @@
 import collections
 import contextlib
 import json
+import textwrap
 
 import jsonschema
+import six
 
 
 # If DEBUG_MODE is True, then schema objects are converted to dict and
@@ -34,6 +36,35 @@ def debug_mode(arg):
         DEBUG_MODE = original
 
 
+class SchemaValidationError(jsonschema.ValidationError):
+    """A wrapper for jsonschema.ValidationError with friendlier traceback"""
+    def __init__(self, obj, err):
+        super(SchemaValidationError, self).__init__(**err._contents())
+        self.obj = obj
+
+    def __unicode__(self):
+        cls = self.obj.__class__
+        schema_path = ['{0}.{1}'.format(cls.__module__,cls.__name__)]
+        schema_path.extend(self.schema_path)
+        schema_path = ' ->'.join(val for val in schema_path[:-1]
+                                if val not in ('properties',
+                                               'additionalProperties',
+                                               'patternProperties'))
+        return """Invalid specification
+
+        {0}, validating {1!r}
+
+        {2}
+        """.format(schema_path, self.validator, self.message)
+
+    if six.PY3:
+        __str__ = __unicode__
+    else:
+        def __str__(self):
+            return unicode(self).encode("utf-8")
+
+
+
 class UndefinedType(object):
     """A singleton object for marking undefined attributes"""
     __instance = None
@@ -144,9 +175,11 @@ def to_dict(self, validate=True, ignore=[], context={}):
 
         Parameters
         ----------
-        validate : boolean
+        validate : boolean or string
             If True (default), then validate the output dictionary
-            against the schema.
+            against the schema. If "deep" then recursively validate
+            all objects in the spec. This takes much more time, but
+            it results in friendlier tracebacks for large objects.
         ignore : list
             A list of keys to ignore. This will *not* passed to child to_dict
             function calls.
@@ -164,10 +197,11 @@ def to_dict(self, validate=True, ignore=[], context={}):
         jsonschema.ValidationError :
             if validate=True and the dict does not conform to the schema
         """
-        # TODO: add validate='once' and validate='deep'
+        sub_validate = 'deep' if validate == 'deep' else False
+
         def _todict(val):
             if isinstance(val, SchemaBase):
-                return val.to_dict(validate=False, context=context)
+                return val.to_dict(validate=sub_validate, context=context)
             elif isinstance(val, list):
                 return [_todict(v) for v in val]
             elif isinstance(val, dict):
@@ -185,7 +219,10 @@ def _todict(val):
             raise ValueError("{0} instance has both a value and properties : "
                              "cannot serialize to dict".format(self.__class__))
         if validate:
-            self.validate(result)
+            try:
+                self.validate(result)
+            except jsonschema.ValidationError as err:
+                raise SchemaValidationError(self, err)
         return result
 
     @classmethod