Merge pull request #249 from kevin-bates/capture-validation-error

.gitignore

@@ -17,3 +17,4 @@ __pycache__
 .coverage
 .cache
 .python-version
+.idea

nbformat/__init__.py

@@ -48,7 +48,7 @@ class NBFormatError(ValueError):
     """)
 
 
-def reads(s, as_version, **kwargs):
+def reads(s, as_version, capture_validation_error=None, **kwargs):
     """Read a notebook from a string and return the NotebookNode object as the given version.
 
     The string can contain a notebook of any version.
@@ -64,6 +64,10 @@ def reads(s, as_version, **kwargs):
         The version of the notebook format to return.
         The notebook will be converted, if necessary.
         Pass nbformat.NO_CONVERT to prevent conversion.
+    capture_validation_error : dict, optional
+        If provided, a key of "ValidationError" with a
+        value of the ValidationError instance will be added
+        to the dictionary.
 
     Returns
     -------
@@ -77,10 +81,12 @@ def reads(s, as_version, **kwargs):
         validate(nb)
     except ValidationError as e:
         get_logger().error("Notebook JSON is invalid: %s", e)
+        if isinstance(capture_validation_error, dict):
+            capture_validation_error['ValidationError'] = e
     return nb
 
 
-def writes(nb, version=NO_CONVERT, **kwargs):
+def writes(nb, version=NO_CONVERT, capture_validation_error=None, **kwargs):
     """Write a notebook to a string in a given format in the given nbformat version.
 
     Any notebook format errors will be logged.
@@ -93,6 +99,10 @@ def writes(nb, version=NO_CONVERT, **kwargs):
         The nbformat version to write.
         If unspecified, or specified as nbformat.NO_CONVERT,
         the notebook's own version will be used and no conversion performed.
+    capture_validation_error : dict, optional
+        If provided, a key of "ValidationError" with a
+        value of the ValidationError instance will be added
+        to the dictionary.
 
     Returns
     -------
@@ -107,10 +117,12 @@ def writes(nb, version=NO_CONVERT, **kwargs):
         validate(nb)
     except ValidationError as e:
         get_logger().error("Notebook JSON is invalid: %s", e)
+        if isinstance(capture_validation_error, dict):
+            capture_validation_error['ValidationError'] = e
     return versions[version].writes_json(nb, **kwargs)
 
 
-def read(fp, as_version, **kwargs):
+def read(fp, as_version, capture_validation_error=None, **kwargs):
     """Read a notebook from a file as a NotebookNode of the given version.
 
     The string can contain a notebook of any version.
@@ -127,6 +139,10 @@ def read(fp, as_version, **kwargs):
         The version of the notebook format to return.
         The notebook will be converted, if necessary.
         Pass nbformat.NO_CONVERT to prevent conversion.
+    capture_validation_error : dict, optional
+        If provided, a key of "ValidationError" with a
+        value of the ValidationError instance will be added
+        to the dictionary.
 
     Returns
     -------
@@ -138,12 +154,12 @@ def read(fp, as_version, **kwargs):
         buf = fp.read()
     except AttributeError:
         with io.open(fp, encoding='utf-8') as f:
-            return reads(f.read(), as_version, **kwargs)
+            return reads(f.read(), as_version, capture_validation_error, **kwargs)
 
-    return reads(buf, as_version, **kwargs)
+    return reads(buf, as_version, capture_validation_error, **kwargs)
 
 
-def write(nb, fp, version=NO_CONVERT, **kwargs):
+def write(nb, fp, version=NO_CONVERT, capture_validation_error=None, **kwargs):
     """Write a notebook to a file in a given nbformat version.
 
     The file-like object must accept unicode input.
@@ -160,8 +176,12 @@ def write(nb, fp, version=NO_CONVERT, **kwargs):
         If nb is not this version, it will be converted.
         If unspecified, or specified as nbformat.NO_CONVERT,
         the notebook's own version will be used and no conversion performed.
+    capture_validation_error : dict, optional
+        If provided, a key of "ValidationError" with a
+        value of the ValidationError instance will be added
+        to the dictionary.
     """
-    s = writes(nb, version, **kwargs)
+    s = writes(nb, version, capture_validation_error, **kwargs)
     if isinstance(s, bytes):
         s = s.decode('utf8')
 

nbformat/tests/test_api.py

@@ -10,9 +10,11 @@
 import unittest
 
 from .base import TestsBase
+from jsonschema import ValidationError
 
 from tempfile import TemporaryDirectory
 from ..reader import get_version
+from ..validator import isvalid
 from nbformat import read, current_nbformat, writes, write
 
 
@@ -64,3 +66,34 @@ def test_read_write_pathlib_object(self):
             dest = pathlib.Path(td) / 'echidna.ipynb'
             write(nb, dest)
             assert os.path.isfile(dest)
+
+    def test_capture_validation_error(self):
+        """Test that validation error can be captured on read() and write()"""
+        validation_error = {}
+        path = os.path.join(self._get_files_path(), u'invalid.ipynb')
+        nb = read(path, as_version=4, capture_validation_error=validation_error)
+        assert not isvalid(nb)
+        assert 'ValidationError' in validation_error
+        assert isinstance(validation_error['ValidationError'], ValidationError)
+
+        validation_error = {}
+        with TemporaryDirectory() as td:
+            dest = os.path.join(td, 'invalid.ipynb')
+            write(nb, dest, capture_validation_error=validation_error)
+            assert os.path.isfile(dest)
+            assert 'ValidationError' in validation_error
+            assert isinstance(validation_error['ValidationError'], ValidationError)
+
+        # Repeat with a valid notebook file
+        validation_error = {}
+        path = os.path.join(self._get_files_path(), u'test4.ipynb')
+        nb = read(path, as_version=4, capture_validation_error=validation_error)
+        assert isvalid(nb)
+        assert 'ValidationError' not in validation_error
+
+        validation_error = {}
+        with TemporaryDirectory() as td:
+            dest = os.path.join(td, 'test4.ipynb')
+            write(nb, dest, capture_validation_error=validation_error)
+            assert os.path.isfile(dest)
+            assert 'ValidationError' not in validation_error