Add top-level IPython.nbformat API

to avoid method:module conflict, renamed convert->converter

IPython/nbformat/__init__.py

@@ -0,0 +1,143 b''
+"""The IPython notebook format
+
+Use this module to read or write notebook files as particular nbformat versions.
+"""
+
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+from IPython.utils.log import get_logger
+
+from . import v1
+from . import v2
+from . import v3
+from . import v4
+
+versions = {
+    1: v1,
+    2: v2,
+    3: v3,
+    4: v4,
+}
+
+from .validator import validate, ValidationError
+from .converter import convert
+from . import reader
+
+from .v4 import (
+    nbformat as current_nbformat,
+    nbformat_minor as current_nbformat_minor,
+)
+
+class NBFormatError(ValueError):
+    pass
+
+# no-conversion singleton
+NO_CONVERT = object()
+
+def reads(s, as_version, **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.
+    The notebook will be returned `as_version`, converting, if necessary.
+
+    Notebook format errors will be logged.
+
+    Parameters
+    ----------
+    s : unicode
+        The raw unicode string to read the notebook from.
+    as_version : int
+        The version of the notebook format to return.
+        The notebook will be converted, if necessary.
+        Pass nbformat.NO_CONVERT to prevent conversion.
+
+    Returns
+    -------
+    nb : NotebookNode
+        The notebook that was read.
+    """
+    nb = reader.reads(s, **kwargs)
+    if as_version is not NO_CONVERT:
+        nb = convert(nb, as_version)
+    try:
+        validate(nb)
+    except ValidationError as e:
+        get_logger().error("Notebook JSON is invalid: %s", e)
+    return nb
+
+
+def writes(nb, version, **kwargs):
+    """Write a notebook to a string in a given format in the given nbformat version.
+
+    Any notebook format errors will be logged.
+
+    Parameters
+    ----------
+    nb : NotebookNode
+        The notebook to write.
+    version : int
+        The nbformat version to write.
+        If nb is not this version, it will be converted.
+        Pass nbformat.NO_CONVERT to prevent conversion.
+
+    Returns
+    -------
+    s : unicode
+        The notebook as a JSON string.
+    """
+    if version is not NO_CONVERT:
+        nb = convert(nb, version)
+    else:
+        version, _ = reader.get_version(nb)
+    try:
+        validate(nb)
+    except ValidationError as e:
+        get_logger().error("Notebook JSON is invalid: %s", e)
+    return versions[version].writes_json(nb, **kwargs)
+
+
+def read(fp, as_version, **kwargs):
+    """Read a notebook from a file as a NotebookNode of the given version.
+
+    The string can contain a notebook of any version.
+    The notebook will be returned `as_version`, converting, if necessary.
+
+    Notebook format errors will be logged.
+
+    Parameters
+    ----------
+    fp : file
+        Any file-like object with a read method.
+    as_version: int
+        The version of the notebook format to return.
+        The notebook will be converted, if necessary.
+        Pass nbformat.NO_CONVERT to prevent conversion.
+
+    Returns
+    -------
+    nb : NotebookNode
+        The notebook that was read.
+    """
+    return reads(fp.read(), as_version, **kwargs)
+
+
+def write(fp, nb, version, **kwargs):
+    """Write a notebook to a file in a given nbformat version.
+    
+    The file-like object must accept unicode input.
+    
+    Parameters
+    ----------
+    fp : file
+        Any file-like object with a write method that accepts unicode.
+    nb : NotebookNode
+        The notebook to write.
+    version : int
+        The nbformat version to write.
+        If nb is not this version, it will be converted.
+    """
+    s = writes(nb, version, **kwargs)
+    if isinstance(s, bytes):
+        s = s.decode('utf8')
+    return fp.write(s)

IPython/nbformat/converter.py

@@ -1,53 +1,54 b''
 """API for converting notebooks between versions."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
-from .reader import get_version, versions
+from . import versions
+from .reader import get_version
 
 
 def convert(nb, to_version):
     """Convert a notebook node object to a specific version.  Assumes that
     all the versions starting from 1 to the latest major X are implemented.
     In other words, there should never be a case where v1 v2 v3 v5 exist without
     a v4.  Also assumes that all conversions can be made in one step increments
     between major versions and ignores minor revisions.
 
     Parameters
     ----------
     nb : NotebookNode
     to_version : int
         Major revision to convert the notebook to.  Can either be an upgrade or
         a downgrade.
     """
 
     # Get input notebook version.
     (version, version_minor) = get_version(nb)
 
-    # Check if destination is current version, if so return contents
+    # Check if destination is target version, if so return contents
     if version == to_version:
         return nb
 
     # If the version exist, try to convert to it one step at a time.
     elif to_version in versions:
 
         # Get the the version that this recursion will convert to as a step 
         # closer to the final revision.  Make sure the newer of the conversion
         # functions is used to perform the conversion.
         if to_version > version:
             step_version = version + 1
             convert_function = versions[step_version].upgrade
         else:
             step_version = version - 1
             convert_function = versions[version].downgrade
 
         # Convert and make sure version changed during conversion.
         converted = convert_function(nb)
         if converted.get('nbformat', 1) == version:
             raise ValueError("Failed to convert notebook from v%d to v%d." % (version, step_version))
 
         # Recursively convert until target version is reached.
         return convert(converted, to_version)
     else:
         raise ValueError("Cannot convert notebook to v%d because that " \
                         "version doesn't exist" % (to_version))

IPython/nbformat/current.py

@@ -1,182 +1,182 b''
 """The official API for working with notebooks in the current format version."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from __future__ import print_function
 
 import re
 import warnings
 
 from IPython.nbformat.v3 import (
     NotebookNode,
     new_code_cell, new_text_cell, new_notebook, new_output, new_worksheet,
     parse_filename, new_metadata, new_author, new_heading_cell, nbformat,
     nbformat_minor, nbformat_schema, to_notebook_json,
 )
 from IPython.nbformat import v3 as _v_latest
 
 from .reader import reads as reader_reads
-from .reader import versions
-from .convert import convert
+from . import versions
+from .converter import convert
 from .validator import validate, ValidationError
 
 from IPython.utils.log import get_logger
 
 __all__ = ['NotebookNode', 'new_code_cell', 'new_text_cell', 'new_notebook',
 'new_output', 'new_worksheet', 'parse_filename', 'new_metadata', 'new_author',
 'new_heading_cell', 'nbformat', 'nbformat_minor', 'nbformat_schema',
 'to_notebook_json', 'convert', 'validate', 'NBFormatError', 'parse_py',
 'reads_json', 'writes_json', 'reads_py', 'writes_py', 'reads', 'writes', 'read',
 'write']
 
 current_nbformat = nbformat
 current_nbformat_minor = nbformat_minor
 current_nbformat_module = _v_latest.__name__
 
 
 class NBFormatError(ValueError):
     pass
 
 
 def _warn_format():
     warnings.warn("""Non-JSON file support in nbformat is deprecated.
     Use nbconvert to create files of other formats.""")
 
 
 def parse_py(s, **kwargs):
     """Parse a string into a (nbformat, string) tuple."""
     nbf = current_nbformat
     nbm = current_nbformat_minor
     
     pattern = r'# <nbformat>(?P<nbformat>\d+[\.\d+]*)</nbformat>'
     m = re.search(pattern,s)
     if m is not None:
         digits = m.group('nbformat').split('.')
         nbf = int(digits[0])
         if len(digits) > 1:
             nbm = int(digits[1])
 
     return nbf, nbm, s
 
 
 def reads_json(nbjson, **kwargs):
     """DEPRECATED, use reads"""
     warnings.warn("reads_json is deprecated, use reads")
     return reads(nbjson)
 
 def writes_json(nb, **kwargs):
     """DEPRECATED, use writes"""
     warnings.warn("writes_json is deprecated, use writes")
     return writes(nb, **kwargs)
 
 def reads_py(s, **kwargs):
     """DEPRECATED: use nbconvert"""
     _warn_format()
     nbf, nbm, s = parse_py(s, **kwargs)
     if nbf in (2, 3):
         nb = versions[nbf].to_notebook_py(s, **kwargs)
     else:
         raise NBFormatError('Unsupported PY nbformat version: %i' % nbf)
     return nb
 
 def writes_py(nb, **kwargs):
     """DEPRECATED: use nbconvert"""
     _warn_format()
     return versions[3].writes_py(nb, **kwargs)
 
 
 # High level API
 
 
 def reads(s, format='DEPRECATED', version=current_nbformat, **kwargs):
     """Read a notebook from a string and return the NotebookNode object.
 
     This function properly handles notebooks of any version. The notebook
     returned will always be in the current version's format.
 
     Parameters
     ----------
     s : unicode
         The raw unicode string to read the notebook from.
 
     Returns
     -------
     nb : NotebookNode
         The notebook that was read.
     """
     if format not in {'DEPRECATED', 'json'}:
         _warn_format()
     nb = reader_reads(s, **kwargs)
     nb = convert(nb, version)
     try:
         validate(nb)
     except ValidationError as e:
         get_logger().error("Notebook JSON is invalid: %s", e)
     return nb
 
 
 def writes(nb, format='DEPRECATED', version=current_nbformat, **kwargs):
     """Write a notebook to a string in a given format in the current nbformat version.
 
     This function always writes the notebook in the current nbformat version.
 
     Parameters
     ----------
     nb : NotebookNode
         The notebook to write.
     version : int
         The nbformat version to write.
         Used for downgrading notebooks.
 
     Returns
     -------
     s : unicode
         The notebook string.
     """
     if format not in {'DEPRECATED', 'json'}:
         _warn_format()
     nb = convert(nb, version)
     try:
         validate(nb)
     except ValidationError as e:
         get_logger().error("Notebook JSON is invalid: %s", e)
     return versions[version].writes_json(nb, **kwargs)
 
 
 def read(fp, format='DEPRECATED', **kwargs):
     """Read a notebook from a file and return the NotebookNode object.
 
     This function properly handles notebooks of any version. The notebook
     returned will always be in the current version's format.
 
     Parameters
     ----------
     fp : file
         Any file-like object with a read method.
 
     Returns
     -------
     nb : NotebookNode
         The notebook that was read.
     """
     return reads(fp.read(), **kwargs)
 
 
 def write(nb, fp, format='DEPRECATED', **kwargs):
     """Write a notebook to a file in a given format in the current nbformat version.
 
     This function always writes the notebook in the current nbformat version.
 
     Parameters
     ----------
     nb : NotebookNode
         The notebook to write.
     fp : file
         Any file-like object with a write method.
     """
     s = writes(nb, **kwargs)
     if isinstance(s, bytes):
         s = s.decode('utf8')
     return fp.write(s)
 

IPython/nbformat/reader.py

@@ -1,95 +1,82 b''
 """API for reading notebooks of different versions"""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import json
 
-from . import v1
-from . import v2
-from . import v3
-from . import v4
-
-versions = {
-    1: v1,
-    2: v2,
-    3: v3,
-    4: v4,
-    }
-
-
 class NotJSONError(ValueError):
     pass
 
 def parse_json(s, **kwargs):
     """Parse a JSON string into a dict."""
     try:
         nb_dict = json.loads(s, **kwargs)
     except ValueError:
         # Limit the error message to 80 characters.  Display whatever JSON will fit.
         raise NotJSONError(("Notebook does not appear to be JSON: %r" % s)[:77] + "...")
     return nb_dict
 
 # High level API
 
 def get_version(nb):
     """Get the version of a notebook.
 
     Parameters
     ----------
     nb : dict
         NotebookNode or dict containing notebook data.
 
     Returns
     -------
     Tuple containing major (int) and minor (int) version numbers
     """
     major = nb.get('nbformat', 1)
     minor = nb.get('nbformat_minor', 0)
     return (major, minor)
 
 
 def reads(s, **kwargs):
     """Read a notebook from a json string and return the 
     NotebookNode object.
 
     This function properly reads notebooks of any version.  No version 
     conversion is performed.
 
     Parameters
     ----------
     s : unicode
         The raw unicode string to read the notebook from.
 
     Returns
     -------
     nb : NotebookNode
         The notebook that was read.
     """
-    from .current import NBFormatError
+    from . import versions, NBFormatError
     
     nb_dict = parse_json(s, **kwargs)
     (major, minor) = get_version(nb_dict)
     if major in versions:
         return versions[major].to_notebook_json(nb_dict, minor=minor)
     else:
         raise NBFormatError('Unsupported nbformat version %s' % major)
 
 
 def read(fp, **kwargs):
     """Read a notebook from a file and return the NotebookNode object.
 
     This function properly reads notebooks of any version.  No version 
     conversion is performed.
 
     Parameters
     ----------
     fp : file
         Any file-like object with a read method.
 
     Returns
     -------
     nb : NotebookNode
         The notebook that was read.
     """
     return reads(fp.read(), **kwargs)

IPython/nbformat/sign.py

@@ -1,305 +1,306 b''
 """Functions for signing notebooks"""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import base64
 from contextlib import contextmanager
 import hashlib
 from hmac import HMAC
 import io
 import os
 
+from IPython.utils.io import atomic_writing
 from IPython.utils.py3compat import string_types, unicode_type, cast_bytes
 from IPython.utils.traitlets import Instance, Bytes, Enum, Any, Unicode, Bool
 from IPython.config import LoggingConfigurable, MultipleInstanceError
 from IPython.core.application import BaseIPythonApplication, base_flags
 
-from .current import read, write
+from . import read, write, NO_CONVERT
 
 try:
     # Python 3
     algorithms = hashlib.algorithms_guaranteed
 except AttributeError:
     algorithms = hashlib.algorithms
 
 
 def yield_everything(obj):
     """Yield every item in a container as bytes
     
     Allows any JSONable object to be passed to an HMAC digester
     without having to serialize the whole thing.
     """
     if isinstance(obj, dict):
         for key in sorted(obj):
             value = obj[key]
             yield cast_bytes(key)
             for b in yield_everything(value):
                 yield b
     elif isinstance(obj, (list, tuple)):
         for element in obj:
             for b in yield_everything(element):
                 yield b
     elif isinstance(obj, unicode_type):
         yield obj.encode('utf8')
     else:
         yield unicode_type(obj).encode('utf8')
 
 
 @contextmanager
 def signature_removed(nb):
     """Context manager for operating on a notebook with its signature removed
     
     Used for excluding the previous signature when computing a notebook's signature.
     """
     save_signature = nb['metadata'].pop('signature', None)
     try:
         yield
     finally:
         if save_signature is not None:
             nb['metadata']['signature'] = save_signature
 
 
 class NotebookNotary(LoggingConfigurable):
     """A class for computing and verifying notebook signatures."""
     
     profile_dir = Instance("IPython.core.profiledir.ProfileDir")
     def _profile_dir_default(self):
         from IPython.core.application import BaseIPythonApplication
         app = None
         try:
             if BaseIPythonApplication.initialized():
                 app = BaseIPythonApplication.instance()
         except MultipleInstanceError:
             pass
         if app is None:
             # create an app, without the global instance
             app = BaseIPythonApplication()
             app.initialize(argv=[])
         return app.profile_dir
     
     algorithm = Enum(algorithms, default_value='sha256', config=True,
         help="""The hashing algorithm used to sign notebooks."""
     )
     def _algorithm_changed(self, name, old, new):
         self.digestmod = getattr(hashlib, self.algorithm)
     
     digestmod = Any()
     def _digestmod_default(self):
         return getattr(hashlib, self.algorithm)
     
     secret_file = Unicode(config=True,
         help="""The file where the secret key is stored."""
     )
     def _secret_file_default(self):
         if self.profile_dir is None:
             return ''
         return os.path.join(self.profile_dir.security_dir, 'notebook_secret')
     
     secret = Bytes(config=True,
         help="""The secret key with which notebooks are signed."""
     )
     def _secret_default(self):
         # note : this assumes an Application is running
         if os.path.exists(self.secret_file):
             with io.open(self.secret_file, 'rb') as f:
                 return f.read()
         else:
             secret = base64.encodestring(os.urandom(1024))
             self._write_secret_file(secret)
             return secret
     
     def _write_secret_file(self, secret):
         """write my secret to my secret_file"""
         self.log.info("Writing notebook-signing key to %s", self.secret_file)
         with io.open(self.secret_file, 'wb') as f:
             f.write(secret)
         try:
             os.chmod(self.secret_file, 0o600)
         except OSError:
             self.log.warn(
                 "Could not set permissions on %s",
                 self.secret_file
             )
         return secret
     
     def compute_signature(self, nb):
         """Compute a notebook's signature
         
         by hashing the entire contents of the notebook via HMAC digest.
         """
         hmac = HMAC(self.secret, digestmod=self.digestmod)
         # don't include the previous hash in the content to hash
         with signature_removed(nb):
             # sign the whole thing
             for b in yield_everything(nb):
                 hmac.update(b)
         
         return hmac.hexdigest()
     
     def check_signature(self, nb):
         """Check a notebook's stored signature
         
         If a signature is stored in the notebook's metadata,
         a new signature is computed and compared with the stored value.
         
         Returns True if the signature is found and matches, False otherwise.
         
         The following conditions must all be met for a notebook to be trusted:
         - a signature is stored in the form 'scheme:hexdigest'
         - the stored scheme matches the requested scheme
         - the requested scheme is available from hashlib
         - the computed hash from notebook_signature matches the stored hash
         """
         stored_signature = nb['metadata'].get('signature', None)
         if not stored_signature \
             or not isinstance(stored_signature, string_types) \
             or ':' not in stored_signature:
             return False
         stored_algo, sig = stored_signature.split(':', 1)
         if self.algorithm != stored_algo:
             return False
         my_signature = self.compute_signature(nb)
         return my_signature == sig
     
     def sign(self, nb):
         """Sign a notebook, indicating that its output is trusted
         
         stores 'algo:hmac-hexdigest' in notebook.metadata.signature
         
         e.g. 'sha256:deadbeef123...'
         """
         signature = self.compute_signature(nb)
         nb['metadata']['signature'] = "%s:%s" % (self.algorithm, signature)
     
     def mark_cells(self, nb, trusted):
         """Mark cells as trusted if the notebook's signature can be verified
         
         Sets ``cell.metadata.trusted = True | False`` on all code cells,
         depending on whether the stored signature can be verified.
         
         This function is the inverse of check_cells
         """
         for cell in nb['cells']:
             if cell['cell_type'] == 'code':
                 cell['metadata']['trusted'] = trusted
     
     def _check_cell(self, cell):
         """Do we trust an individual cell?
         
         Return True if:
         
         - cell is explicitly trusted
         - cell has no potentially unsafe rich output
         
         If a cell has no output, or only simple print statements,
         it will always be trusted.
         """
         # explicitly trusted
         if cell['metadata'].pop("trusted", False):
             return True
         
         # explicitly safe output
         safe = {
             'text/plain', 'image/png', 'image/jpeg',
         }
         
         for output in cell['outputs']:
             output_type = output['output_type']
             if output_type in {'execute_result', 'display_data'}:
                 # if there are any data keys not in the safe whitelist
                 output_keys = set(output).difference({"output_type", "execution_count", "metadata"})
                 if output_keys.difference(safe):
                     return False
         
         return True
     
     def check_cells(self, nb):
         """Return whether all code cells are trusted
         
         If there are no code cells, return True.
         
         This function is the inverse of mark_cells.
         """
         trusted = True
         for cell in nb['cells']:
             if cell['cell_type'] != 'code':
                 continue
             # only distrust a cell if it actually has some output to distrust
             if not self._check_cell(cell):
                 trusted = False
 
         return trusted
 
 
 trust_flags = {
     'reset' : (
         {'TrustNotebookApp' : { 'reset' : True}},
         """Generate a new key for notebook signature.
         All previously signed notebooks will become untrusted.
         """
     ),
 }
 trust_flags.update(base_flags)
 trust_flags.pop('init')
 
 
 class TrustNotebookApp(BaseIPythonApplication):
     
     description="""Sign one or more IPython notebooks with your key,
     to trust their dynamic (HTML, Javascript) output.
     
     Trusting a notebook only applies to the current IPython profile.
     To trust a notebook for use with a profile other than default,
     add `--profile [profile name]`.
     
     Otherwise, you will have to re-execute the notebook to see output.
     """
     
     examples = """
     ipython trust mynotebook.ipynb and_this_one.ipynb
     ipython trust --profile myprofile mynotebook.ipynb
     """
     
     flags = trust_flags
     
     reset = Bool(False, config=True,
         help="""If True, generate a new key for notebook signature.
         After reset, all previously signed notebooks will become untrusted.
         """
     )
     
     notary = Instance(NotebookNotary)
     def _notary_default(self):
         return NotebookNotary(parent=self, profile_dir=self.profile_dir)
     
     def sign_notebook(self, notebook_path):
         if not os.path.exists(notebook_path):
             self.log.error("Notebook missing: %s" % notebook_path)
             self.exit(1)
         with io.open(notebook_path, encoding='utf8') as f:
-            nb = read(f, 'json')
+            nb = read(f, NO_CONVERT)
         if self.notary.check_signature(nb):
             print("Notebook already signed: %s" % notebook_path)
         else:
             print("Signing notebook: %s" % notebook_path)
             self.notary.sign(nb)
-            with io.open(notebook_path, 'w', encoding='utf8') as f:
-                write(nb, f, 'json')
+            with atomic_writing(notebook_path) as f:
+                write(f, nb, NO_CONVERT)
     
     def generate_new_key(self):
         """Generate a new notebook signature key"""
         print("Generating new notebook key: %s" % self.notary.secret_file)
         self.notary._write_secret_file(os.urandom(1024))
     
     def start(self):
         if self.reset:
             self.generate_new_key()
             return
         if not self.extra_args:
             self.log.critical("Specify at least one notebook to sign.")
             self.exit(1)
         
         for notebook_path in self.extra_args:
             self.sign_notebook(notebook_path)
 

IPython/nbformat/tests/test_api.py

@@ -1,41 +1,37 b''
-"""
-Contains tests class for current.py
-"""
+"""Test the APIs at the top-level of nbformat"""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
-import io
 import json
-import tempfile
 
 from .base import TestsBase
 
 from ..reader import get_version
-from ..current import read, current_nbformat, validate, writes
+from IPython.nbformat import read, current_nbformat, writes
 
 
-class TestCurrent(TestsBase):
+class TestAPI(TestsBase):
 
     def test_read(self):
         """Can older notebooks be opened and automatically converted to the current 
         nbformat?"""
 
         # Open a version 2 notebook.
-        with self.fopen(u'test2.ipynb', u'r') as f:
-            nb = read(f)
+        with self.fopen(u'test2.ipynb', 'r') as f:
+            nb = read(f, as_version=current_nbformat)
 
         # Check that the notebook was upgraded to the latest version automatically.
         (major, minor) = get_version(nb)
         self.assertEqual(major, current_nbformat)
 
     def test_write_downgrade_2(self):
         """dowgrade a v3 notebook to v2"""
         # Open a version 3 notebook.
         with self.fopen(u'test3.ipynb', 'r') as f:
-            nb = read(f, u'json')
+            nb = read(f, as_version=3)
 
         jsons = writes(nb, version=2)
         nb2 = json.loads(jsons)
         (major, minor) = get_version(nb2)
         self.assertEqual(major, 2)

IPython/nbformat/tests/test_convert.py

@@ -1,57 +1,57 b''
 """Tests for nbformat.convert"""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from .base import TestsBase
 
-from ..convert import convert
+from ..converter import convert
 from ..reader import read, get_version
-from ..current import current_nbformat
+from .. import current_nbformat
 
 
 class TestConvert(TestsBase):
 
     def test_downgrade_3_2(self):
         """Do notebook downgrades work?"""
 
         # Open a version 3 notebook and attempt to downgrade it to version 2.
         with self.fopen(u'test3.ipynb', u'r') as f:
             nb = read(f)
         nb = convert(nb, 2)
 
         # Check if downgrade was successful.
         (major, minor) = get_version(nb)
         self.assertEqual(major, 2)
 
 
     def test_upgrade_2_3(self):
         """Do notebook upgrades work?"""
 
         # Open a version 2 notebook and attempt to upgrade it to version 3.
         with self.fopen(u'test2.ipynb', u'r') as f:
             nb = read(f)
         nb = convert(nb, 3)
 
         # Check if upgrade was successful.
         (major, minor) = get_version(nb)
         self.assertEqual(major, 3)
 
 
     def test_open_current(self):
         """Can an old notebook be opened and converted to the current version 
         while remembering the original version of the notebook?"""
 
         # Open a version 2 notebook and attempt to upgrade it to the current version
         # while remembering it's version information.
         with self.fopen(u'test2.ipynb', u'r') as f:
             nb = read(f)
         (original_major, original_minor) = get_version(nb)
         nb = convert(nb, current_nbformat)
 
         # Check if upgrade was successful.
         (major, minor) = get_version(nb)
         self.assertEqual(major, current_nbformat)
 
         # Check if the original major revision was remembered.
         self.assertEqual(original_major, 2)

IPython/nbformat/tests/test_sign.py

@@ -1,112 +1,111 b''
 """Test Notebook signing"""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
-from .. import sign
 from .base import TestsBase
 
-from ..current import read
+from IPython.nbformat import read, sign
 from IPython.core.getipython import get_ipython
 
 
 class TestNotary(TestsBase):
     
     def setUp(self):
         self.notary = sign.NotebookNotary(
             secret=b'secret',
             profile_dir=get_ipython().profile_dir
         )
         with self.fopen(u'test3.ipynb', u'r') as f:
-            self.nb = read(f, u'json')
+            self.nb = read(f, as_version=4)
     
     def test_algorithms(self):
         last_sig = ''
         for algo in sign.algorithms:
             self.notary.algorithm = algo
             self.notary.sign(self.nb)
             sig = self.nb.metadata.signature
             print(sig)
             self.assertEqual(sig[:len(self.notary.algorithm)+1], '%s:' % self.notary.algorithm)
             self.assertNotEqual(last_sig, sig)
             last_sig = sig
     
     def test_sign_same(self):
         """Multiple signatures of the same notebook are the same"""
         sig1 = self.notary.compute_signature(self.nb)
         sig2 = self.notary.compute_signature(self.nb)
         self.assertEqual(sig1, sig2)
     
     def test_change_secret(self):
         """Changing the secret changes the signature"""
         sig1 = self.notary.compute_signature(self.nb)
         self.notary.secret = b'different'
         sig2 = self.notary.compute_signature(self.nb)
         self.assertNotEqual(sig1, sig2)
     
     def test_sign(self):
         self.notary.sign(self.nb)
         sig = self.nb.metadata.signature
         self.assertEqual(sig[:len(self.notary.algorithm)+1], '%s:' % self.notary.algorithm)
     
     def test_check_signature(self):
         nb = self.nb
         md = nb.metadata
         notary = self.notary
         check_signature = notary.check_signature
         # no signature:
         md.pop('signature', None)
         self.assertFalse(check_signature(nb))
         # hash only, no algo
         md.signature = notary.compute_signature(nb)
         self.assertFalse(check_signature(nb))
         # proper signature, algo mismatch
         notary.algorithm = 'sha224'
         notary.sign(nb)
         notary.algorithm = 'sha256'
         self.assertFalse(check_signature(nb))
         # check correctly signed notebook
         notary.sign(nb)
         self.assertTrue(check_signature(nb))
     
     def test_mark_cells_untrusted(self):
         cells = self.nb.cells
         self.notary.mark_cells(self.nb, False)
         for cell in cells:
             self.assertNotIn('trusted', cell)
             if cell.cell_type == 'code':
                 self.assertIn('trusted', cell.metadata)
                 self.assertFalse(cell.metadata.trusted)
             else:
                 self.assertNotIn('trusted', cell.metadata)
     
     def test_mark_cells_trusted(self):
         cells = self.nb.cells
         self.notary.mark_cells(self.nb, True)
         for cell in cells:
             self.assertNotIn('trusted', cell)
             if cell.cell_type == 'code':
                 self.assertIn('trusted', cell.metadata)
                 self.assertTrue(cell.metadata.trusted)
             else:
                 self.assertNotIn('trusted', cell.metadata)
     
     def test_check_cells(self):
         nb = self.nb
         self.notary.mark_cells(nb, True)
         self.assertTrue(self.notary.check_cells(nb))
         for cell in nb.cells:
             self.assertNotIn('trusted', cell)
         self.notary.mark_cells(nb, False)
         self.assertFalse(self.notary.check_cells(nb))
         for cell in nb.cells:
             self.assertNotIn('trusted', cell)
     
     def test_trust_no_output(self):
         nb = self.nb
         self.notary.mark_cells(nb, False)
         for cell in nb.cells:
             if cell.cell_type == 'code':
                 cell.outputs = []
         self.assertTrue(self.notary.check_cells(nb))
 

IPython/nbformat/tests/test_validator.py

@@ -1,58 +1,58 b''
 """Test nbformat.validator"""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import os
 
 from .base import TestsBase
 from jsonschema import ValidationError
-from ..current import read
+from IPython.nbformat import read
 from ..validator import isvalid, validate
 
 
 class TestValidator(TestsBase):
 
     def test_nb2(self):
         """Test that a v2 notebook converted to current passes validation"""
         with self.fopen(u'test2.ipynb', u'r') as f:
-            nb = read(f, u'json')
+            nb = read(f, as_version=4)
         validate(nb)
         self.assertEqual(isvalid(nb), True)
 
     def test_nb3(self):
         """Test that a v3 notebook passes validation"""
         with self.fopen(u'test3.ipynb', u'r') as f:
-            nb = read(f, u'json')
+            nb = read(f, as_version=4)
         validate(nb)
         self.assertEqual(isvalid(nb), True)
 
     def test_nb4(self):
         """Test that a v4 notebook passes validation"""
         with self.fopen(u'test4.ipynb', u'r') as f:
-            nb = read(f, u'json')
+            nb = read(f, as_version=4)
         validate(nb)
         self.assertEqual(isvalid(nb), True)
 
     def test_invalid(self):
         """Test than an invalid notebook does not pass validation"""
         # this notebook has a few different errors:
         # - one cell is missing its source
         # - invalid cell type
         # - invalid output_type
         with self.fopen(u'invalid.ipynb', u'r') as f:
-            nb = read(f, u'json')
+            nb = read(f, as_version=4)
         with self.assertRaises(ValidationError):
             validate(nb)
         self.assertEqual(isvalid(nb), False)
 
     def test_future(self):
         """Test than a notebook from the future with extra keys passes validation"""
         with self.fopen(u'test4plus.ipynb', u'r') as f:
-            nb = read(f)
+            nb = read(f, as_version=4)
         with self.assertRaises(ValidationError):
             validate(nb, version=4)
         
         self.assertEqual(isvalid(nb, version=4), False)
         self.assertEqual(isvalid(nb), True)
 

IPython/nbformat/v4/convert.py

@@ -1,249 +1,249 b''
 """Code for converting notebooks to and from v3."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import json
 import re
 
 from .nbbase import (
     nbformat, nbformat_minor,
     NotebookNode,
 )
 
 from IPython.nbformat import v3
 from IPython.utils.log import get_logger
 
 def _warn_if_invalid(nb, version):
     """Log validation errors, if there are any."""
-    from IPython.nbformat.current import validate, ValidationError
+    from IPython.nbformat import validate, ValidationError
     try:
         validate(nb, version=version)
     except ValidationError as e:
         get_logger().error("Notebook JSON is not valid v%i: %s", version, e)
 
 def upgrade(nb, from_version=3, from_minor=0):
     """Convert a notebook to v4.
 
     Parameters
     ----------
     nb : NotebookNode
         The Python representation of the notebook to convert.
     from_version : int
         The original version of the notebook to convert.
     from_minor : int
         The original minor version of the notebook to convert (only relevant for v >= 3).
     """
     if from_version == 3:
         # Validate the notebook before conversion
         _warn_if_invalid(nb, from_version)
 
         # Mark the original nbformat so consumers know it has been converted
         orig_nbformat = nb.pop('orig_nbformat', None)
         nb.metadata.orig_nbformat = orig_nbformat or 3
 
         # Mark the new format
         nb.nbformat = nbformat
         nb.nbformat_minor = nbformat_minor
 
         # remove worksheet(s)
         nb['cells'] = cells = []
         # In the unlikely event of multiple worksheets,
         # they will be flattened
         for ws in nb.pop('worksheets', []):
             # upgrade each cell
             for cell in ws['cells']:
                 cells.append(upgrade_cell(cell))
         # upgrade metadata
         nb.metadata.pop('name', '')
         # Validate the converted notebook before returning it
         _warn_if_invalid(nb, nbformat)
         return nb
     elif from_version == 4:
         # nothing to do
         if from_minor != nbformat_minor:
             nb.metadata.orig_nbformat_minor = from_minor
         nb.nbformat_minor = nbformat_minor
 
         return nb
     else:
         raise ValueError('Cannot convert a notebook directly from v%s to v4.  ' \
                 'Try using the IPython.nbformat.convert module.' % from_version)
 
 def upgrade_cell(cell):
     """upgrade a cell from v3 to v4
 
     heading cell -> markdown heading
     code cell:
         - remove language metadata
         - cell.input -> cell.source
         - cell.prompt_number -> cell.execution_count
         - update outputs
     """
     cell.setdefault('metadata', NotebookNode())
     if cell.cell_type == 'code':
         cell.pop('language', '')
         if 'collapsed' in cell:
             cell.metadata['collapsed'] = cell.pop('collapsed')
         cell.source = cell.pop('input', '')
         cell.execution_count = cell.pop('prompt_number', None)
         cell.outputs = upgrade_outputs(cell.outputs)
     elif cell.cell_type == 'heading':
         cell.cell_type = 'markdown'
         level = cell.pop('level', 1)
         cell.source = '{hashes} {single_line}'.format(
             hashes='#' * level,
             single_line = ' '.join(cell.get('source', '').splitlines()),
         )
     elif cell.cell_type == 'html':
         # Technically, this exists. It will never happen in practice.
         cell.cell_type = 'markdown'
     return cell
 
 def downgrade_cell(cell):
     """downgrade a cell from v4 to v3
 
     code cell:
         - set cell.language
         - cell.input <- cell.source
         - cell.prompt_number <- cell.execution_count
         - update outputs
     markdown cell:
         - single-line heading -> heading cell
     """
     if cell.cell_type == 'code':
         cell.language = 'python'
         cell.input = cell.pop('source', '')
         cell.prompt_number = cell.pop('execution_count', None)
         cell.collapsed = cell.metadata.pop('collapsed', False)
         cell.outputs = downgrade_outputs(cell.outputs)
     elif cell.cell_type == 'markdown':
         source = cell.get('source', '')
         if '\n' not in source and source.startswith('#'):
             prefix, text = re.match(r'(#+)\s*(.*)', source).groups()
             cell.cell_type = 'heading'
             cell.source = text
             cell.level = len(prefix)
     return cell
 
 _mime_map = {
     "text" : "text/plain",
     "html" : "text/html",
     "svg" : "image/svg+xml",
     "png" : "image/png",
     "jpeg" : "image/jpeg",
     "latex" : "text/latex",
     "json" : "application/json",
     "javascript" : "application/javascript",
 };
 
 def to_mime_key(d):
     """convert dict with v3 aliases to plain mime-type keys"""
     for alias, mime in _mime_map.items():
         if alias in d:
             d[mime] = d.pop(alias)
     return d
 
 def from_mime_key(d):
     """convert dict with mime-type keys to v3 aliases"""
     for alias, mime in _mime_map.items():
         if mime in d:
             d[alias] = d.pop(mime)
     return d
 
 def upgrade_output(output):
     """upgrade a single code cell output from v3 to v4
 
     - pyout -> execute_result
     - pyerr -> error
     - output.type -> output.data.mime/type
     - mime-type keys
     - stream.stream -> stream.name
     """
     if output['output_type'] in {'pyout', 'display_data'}:
         output.setdefault('metadata', NotebookNode())
         if output['output_type'] == 'pyout':
             output['output_type'] = 'execute_result'
             output['execution_count'] = output.pop('prompt_number', None)
 
         # move output data into data sub-dict
         data = {}
         for key in list(output):
             if key in {'output_type', 'execution_count', 'metadata'}:
                 continue
             data[key] = output.pop(key)
         to_mime_key(data)
         output['data'] = data
         to_mime_key(output.metadata)
         if 'application/json' in data:
             data['application/json'] = json.loads(data['application/json'])
         # promote ascii bytes (from v2) to unicode
         for key in ('image/png', 'image/jpeg'):
             if key in data and isinstance(data[key], bytes):
                 data[key] = data[key].decode('ascii')
     elif output['output_type'] == 'pyerr':
         output['output_type'] = 'error'
     elif output['output_type'] == 'stream':
         output['name'] = output.pop('stream')
     return output
 
 def downgrade_output(output):
     """downgrade a single code cell output to v3 from v4
 
     - pyout <- execute_result
     - pyerr <- error
     - output.data.mime/type -> output.type
     - un-mime-type keys
     - stream.stream <- stream.name
     """
     if output['output_type'] in {'execute_result', 'display_data'}:
         if output['output_type'] == 'execute_result':
             output['output_type'] = 'pyout'
             output['prompt_number'] = output.pop('execution_count', None)
 
         # promote data dict to top-level output namespace
         data = output.pop('data', {})
         if 'application/json' in data:
             data['application/json'] = json.dumps(data['application/json'])
         from_mime_key(data)
         output.update(data)
         from_mime_key(output.get('metadata', {}))
     elif output['output_type'] == 'error':
         output['output_type'] = 'pyerr'
     elif output['output_type'] == 'stream':
         output['stream'] = output.pop('name')
     return output
 
 def upgrade_outputs(outputs):
     """upgrade outputs of a code cell from v3 to v4"""
     return [upgrade_output(op) for op in outputs]
 
 def downgrade_outputs(outputs):
     """downgrade outputs of a code cell to v3 from v4"""
     return [downgrade_output(op) for op in outputs]
 
 def downgrade(nb):
     """Convert a v4 notebook to v3.
 
     Parameters
     ----------
     nb : NotebookNode
         The Python representation of the notebook to convert.
     """
     if nb.nbformat != nbformat:
         return nb
 
     # Validate the notebook before conversion
     _warn_if_invalid(nb, nbformat)
 
     nb.nbformat = v3.nbformat
     nb.nbformat_minor = v3.nbformat_minor
     cells = [ downgrade_cell(cell) for cell in nb.pop('cells') ]
     nb.worksheets = [v3.new_worksheet(cells=cells)]
     nb.metadata.setdefault('name', '')
     nb.metadata.pop('orig_nbformat', None)
     nb.metadata.pop('orig_nbformat_minor', None)
 
     # Validate the converted notebook before returning it
     _warn_if_invalid(nb, v3.nbformat)
     return nb

IPython/nbformat/v4/nbbase.py

@@ -1,149 +1,149 b''
 """Python API for composing notebook elements
 
 The Python representation of a notebook is a nested structure of
 dictionary subclasses that support attribute access
 (IPython.utils.ipstruct.Struct). The functions in this module are merely
 helpers to build the structs in the right form.
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from IPython.utils.ipstruct import Struct
 
 # Change this when incrementing the nbformat version
 nbformat = 4
 nbformat_minor = 0
 nbformat_schema = 'nbformat.v4.schema.json'
 
 
 def validate(node, ref=None):
     """validate a v4 node"""
-    from ..current import validate
+    from .. import validate
     return validate(node, ref=ref, version=nbformat)
 
 
 class NotebookNode(Struct):
     pass
 
 def from_dict(d):
     if isinstance(d, dict):
         return NotebookNode({k:from_dict(v) for k,v in d.items()})
     elif isinstance(d, (tuple, list)):
         return [from_dict(i) for i in d]
     else:
         return d
 
 
 def new_output(output_type, data=None, **kwargs):
     """Create a new output, to go in the ``cell.outputs`` list of a code cell."""
     output = NotebookNode(output_type=output_type)
 
     # populate defaults:
     if output_type == 'stream':
         output.name = u'stdout'
         output.text = u''
     elif output_type in {'execute_result', 'display_data'}:
         output.metadata = NotebookNode()
         output.data = NotebookNode()
     # load from args:
     output.update(from_dict(kwargs))
     if data is not None:
         output.data = from_dict(data)
     # validate
     validate(output, output_type)
     return output
 
 
 def output_from_msg(msg):
     """Create a NotebookNode for an output from a kernel's IOPub message.
 
     Returns
     -------
 
     NotebookNode: the output as a notebook node.
 
     Raises
     ------
 
     ValueError: if the message is not an output message.
 
     """
     msg_type = msg['header']['msg_type']
     content = msg['content']
 
     if msg_type == 'execute_result':
         return new_output(output_type=msg_type,
             metadata=content['metadata'],
             data=content['data'],
             execution_count=content['execution_count'],
         )
     elif msg_type == 'stream':
         return new_output(output_type=msg_type,
             name=content['name'],
             text=content['text'],
         )
     elif msg_type == 'display_data':
         return new_output(output_type=msg_type,
             metadata=content['metadata'],
             data=content['data'],
         )
     elif msg_type == 'error':
         return new_output(output_type=msg_type,
             ename=content['ename'],
             evalue=content['evalue'],
             traceback=content['traceback'],
         )
     else:
         raise ValueError("Unrecognized output msg type: %r" % msg_type)
 
 
 def new_code_cell(source='', **kwargs):
     """Create a new code cell"""
     cell = NotebookNode(
         cell_type='code',
         metadata=NotebookNode(),
         execution_count=None,
         source=source,
         outputs=[],
     )
     cell.update(from_dict(kwargs))
 
     validate(cell, 'code_cell')
     return cell
 
 def new_markdown_cell(source='', **kwargs):
     """Create a new markdown cell"""
     cell = NotebookNode(
         cell_type='markdown',
         source=source,
         metadata=NotebookNode(),
     )
     cell.update(from_dict(kwargs))
 
     validate(cell, 'markdown_cell')
     return cell
 
 def new_raw_cell(source='', **kwargs):
     """Create a new raw cell"""
     cell = NotebookNode(
         cell_type='raw',
         source=source,
         metadata=NotebookNode(),
     )
     cell.update(from_dict(kwargs))
 
     validate(cell, 'raw_cell')
     return cell
 
 def new_notebook(**kwargs):
     """Create a new notebook"""
     nb = NotebookNode(
         nbformat=nbformat,
         nbformat_minor=nbformat_minor,
         metadata=NotebookNode(),
         cells=[],
     )
     nb.update(from_dict(kwargs))
     validate(nb)
     return nb

IPython/nbformat/v4/tests/test_convert.py

@@ -1,67 +1,67 b''
 import copy
 
 import nose.tools as nt
 
-from IPython.nbformat.current import validate
+from IPython.nbformat import validate
 from .. import convert
 
 from . import nbexamples
 from IPython.nbformat.v3.tests import nbexamples as v3examples
 from IPython.nbformat import v3, v4
 
 def test_upgrade_notebook():
     nb03 = copy.deepcopy(v3examples.nb0)
     validate(nb03)
     nb04 = convert.upgrade(nb03)
     validate(nb04)
 
 def test_downgrade_notebook():
     nb04 = copy.deepcopy(nbexamples.nb0)
     validate(nb04)
     nb03 = convert.downgrade(nb04)
     validate(nb03)
 
 def test_upgrade_heading():
     v3h = v3.new_heading_cell
     v4m = v4.new_markdown_cell
     for v3cell, expected in [
         (
             v3h(source='foo', level=1),
             v4m(source='# foo'),
         ),
         (
             v3h(source='foo\nbar\nmulti-line\n', level=4),
             v4m(source='#### foo bar multi-line'),
         ),
     ]:
         upgraded = convert.upgrade_cell(v3cell)
         nt.assert_equal(upgraded, expected)
 
 def test_downgrade_heading():
     v3h = v3.new_heading_cell
     v4m = v4.new_markdown_cell
     v3m = lambda source: v3.new_text_cell('markdown', source)
     for v4cell, expected in [
         (
             v4m(source='# foo'),
             v3h(source='foo', level=1),
         ),
         (
             v4m(source='#foo'),
             v3h(source='foo', level=1),
         ),
         (
             v4m(source='#\tfoo'),
             v3h(source='foo', level=1),
         ),
         (
             v4m(source='# \t  foo'),
             v3h(source='foo', level=1),
         ),
         (
             v4m(source='# foo\nbar'),
             v3m(source='# foo\nbar'),
         ),
     ]:
         downgraded = convert.downgrade_cell(v4cell)
         nt.assert_equal(downgraded, expected)

IPython/nbformat/validator.py

@@ -1,146 +1,147 b''
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from __future__ import print_function
 import json
 import os
 import warnings
 
 try:
     from jsonschema import ValidationError
     from jsonschema import Draft4Validator as Validator
 except ImportError as e:
     verbose_msg = """
 
     IPython notebook format depends on the jsonschema package:
     
         https://pypi.python.org/pypi/jsonschema
     
     Please install it first.
     """
     raise ImportError(str(e) + verbose_msg)
 
 from IPython.utils.importstring import import_item
 
 
 validators = {}
 
 def _relax_additional_properties(obj):
     """relax any `additionalProperties`"""
     if isinstance(obj, dict):
         for key, value in obj.items():
             if key == 'additionalProperties':
                 print(obj)
                 value = True
             else:
                 value = _relax_additional_properties(value)
             obj[key] = value
     elif isinstance(obj, list):
         for i, value in enumerate(obj):
             obj[i] = _relax_additional_properties(value)
     return obj
 
 def get_validator(version=None, version_minor=None):
     """Load the JSON schema into a Validator"""
     if version is None:
-        from .current import nbformat as version
+        from .. import current_nbformat
+        version = current_nbformat
 
     v = import_item("IPython.nbformat.v%s" % version)
     current_minor = v.nbformat_minor
     if version_minor is None:
         version_minor = current_minor
 
     version_tuple = (version, version_minor)
 
     if version_tuple not in validators:
         try:
             v.nbformat_schema
         except AttributeError:
             # no validator
             return None
         schema_path = os.path.join(os.path.dirname(v.__file__), v.nbformat_schema)
         with open(schema_path) as f:
             schema_json = json.load(f)
 
         if current_minor < version_minor:
             # notebook from the future, relax all `additionalProperties: False` requirements
             schema_json = _relax_additional_properties(schema_json)
 
         validators[version_tuple] = Validator(schema_json)
     return validators[version_tuple]
 
 def isvalid(nbjson, ref=None, version=None, version_minor=None):
     """Checks whether the given notebook JSON conforms to the current
     notebook format schema. Returns True if the JSON is valid, and
     False otherwise.
 
     To see the individual errors that were encountered, please use the
     `validate` function instead.
     """
     try:
         validate(nbjson, ref, version, version_minor)
     except ValidationError:
         return False
     else:
         return True
 
 
 def better_validation_error(error, version, version_minor):
     """Get better ValidationError on oneOf failures
 
     oneOf errors aren't informative.
     if it's a cell type or output_type error,
     try validating directly based on the type for a better error message
     """
     key = error.schema_path[-1]
     if key.endswith('Of'):
 
         ref = None
         if isinstance(error.instance, dict):
             if 'cell_type' in error.instance:
                 ref = error.instance['cell_type'] + "_cell"
             elif 'output_type' in error.instance:
                 ref = error.instance['output_type']
 
         if ref:
             try:
                 validate(error.instance,
                     ref,
                     version=version,
                     version_minor=version_minor,
                 )
             except ValidationError as e:
                 return better_validation_error(e, version, version_minor)
             except:
                 # if it fails for some reason,
                 # let the original error through
                 pass
 
     return error
 
 
 def validate(nbjson, ref=None, version=None, version_minor=None):
     """Checks whether the given notebook JSON conforms to the current
     notebook format schema.
 
     Raises ValidationError if not valid.
     """
     if version is None:
         from .reader import get_version
         (version, version_minor) = get_version(nbjson)
 
     validator = get_validator(version, version_minor)
 
     if validator is None:
         # no validator
         warnings.warn("No schema for validating v%s notebooks" % version, UserWarning)
         return
 
     try:
         if ref:
             return validator.validate(nbjson, {'$ref' : '#/definitions/%s' % ref})
         else:
             return validator.validate(nbjson)
     except ValidationError as e:
         raise better_validation_error(e, version, version_minor)