Version conversion, support for X to Y even if Y < X (nbformat)

IPython/nbformat/convert.py

@@ -0,0 +1,73 @@
+"""API for converting notebooks between versions.
+
+Authors:
+
+* Jonathan Frederic
+"""
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2013  The IPython Development Team
+#
+#  Distributed under the terms of the BSD License.  The full license is in
+#  the file COPYING, distributed as part of this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+import re
+
+from .reader import get_version, versions
+
+#-----------------------------------------------------------------------------
+# Functions
+#-----------------------------------------------------------------------------
+
+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)
+    version_numbers = versions.keys()
+
+    # Check if destination is current 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 version_numbers:
+
+        # 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) #todo
+        if converted.get('nbformat', 1) == version:
+            raise Exception("Cannot convert notebook from v%d to v%d.  Operation" \
+                "failed silently." % (major, step_version))
+
+        # Recuresively convert until target version is reached.
+        return convert(converted, to_version)
+    else:
+        raise Exception("Cannot convert notebook to v%d because that " \
+                        "version doesn't exist" % (to_version))

IPython/nbformat/current.py

@@ -3,6 +3,7 @@
 Authors:
 
 * Brian Granger
+* Jonathan Frederic
 """
 
 #-----------------------------------------------------------------------------
@@ -17,21 +18,21 @@
 #-----------------------------------------------------------------------------
 
 from __future__ import print_function
-import json
+
 from xml.etree import ElementTree as ET
 import re
 
-from IPython.nbformat import v3
-from IPython.nbformat import v2
-from IPython.nbformat import v1
-
 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,
 )
 
+from .reader import reads as reader_reads
+from .reader import versions
+from .convert import convert
+
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
@@ -43,20 +44,6 @@
 class NBFormatError(ValueError):
     pass
 
-class NotJSONError(ValueError):
-    pass
-
-
-def parse_json(s, **kwargs):
-    """Parse a string into a (nbformat, dict) tuple."""
-    try:
-        d = json.loads(s, **kwargs)
-    except ValueError:
-        raise NotJSONError("Notebook does not appear to be JSON: %r" % s[:16])
-    nbf = d.get('nbformat', 1)
-    nbm = d.get('nbformat_minor', 0)
-    return nbf, nbm, d
-
 
 def parse_py(s, **kwargs):
     """Parse a string into a (nbformat, string) tuple."""
@@ -76,39 +63,26 @@ def parse_py(s, **kwargs):
 
 def reads_json(s, **kwargs):
     """Read a JSON notebook from a string and return the NotebookNode object."""
-    nbf, minor, d = parse_json(s, **kwargs)
-    if nbf == 1:
-        nb = v1.to_notebook_json(d, **kwargs)
-        nb = v3.convert_to_this_nbformat(nb, orig_version=1)
-    elif nbf == 2:
-        nb = v2.to_notebook_json(d, **kwargs)
-        nb = v3.convert_to_this_nbformat(nb, orig_version=2)
-    elif nbf == 3:
-        nb = v3.to_notebook_json(d, **kwargs)
-        nb = v3.convert_to_this_nbformat(nb, orig_version=3, orig_minor=minor)
-    else:
-        raise NBFormatError('Unsupported JSON nbformat version %s (supported version: %i)' % (nbf, 3))
-    return nb
+    return convert(reader_reads(s), current_nbformat)
 
 
 def writes_json(nb, **kwargs):
-    return v3.writes_json(nb, **kwargs)
+    return versions[current_nbformat].writes_json(nb, **kwargs)
 
 
 def reads_py(s, **kwargs):
     """Read a .py notebook from a string and return the NotebookNode object."""
     nbf, nbm, s = parse_py(s, **kwargs)
-    if nbf == 2:
-        nb = v2.to_notebook_py(s, **kwargs)
-    elif nbf == 3:
-        nb = v3.to_notebook_py(s, **kwargs)
+    if nbf == 2 or nbf == 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):
-    return v3.writes_py(nb, **kwargs)
+    # nbformat 3 is the latest format that supports py
+    return versions[3].writes_py(nb, **kwargs)
 
 
 # High level API

IPython/nbformat/reader.py

@@ -0,0 +1,106 @@
+"""API for reading notebooks.
+
+Authors:
+
+* Jonathan Frederic
+"""
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2013  The IPython Development Team
+#
+#  Distributed under the terms of the BSD License.  The full license is in
+#  the file COPYING, distributed as part of this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+import json
+
+import v1
+import v2
+import v3
+
+versions = {
+    1: v1,
+    2: v2,
+    3: v3,
+    }
+
+#-----------------------------------------------------------------------------
+# Code
+#-----------------------------------------------------------------------------
+
+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:
+        raise NotJSONError("Notebook does not appear to be JSON: %r" % s[:16])
+    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, format='ipynb', **kwargs):
+    """Read a notebook from a 'ipynb' (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.
+    """
+    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(), format, **kwargs)

IPython/nbformat/v1/__init__.py

@@ -20,5 +20,4 @@
 from .nbjson import reads as read_json, writes as write_json
 from .nbjson import to_notebook as to_notebook_json
 
-from .convert import convert_to_this_nbformat
-
+from .convert import upgrade

IPython/nbformat/v1/convert.py

@@ -11,6 +11,6 @@
 # Code
 #-----------------------------------------------------------------------------
 
-def convert_to_this_nbformat(nb, orig_version=None):
+def upgrade(nb, orig_version=None):
     raise ValueError('Cannot convert to v1 notebook format')
 

IPython/nbformat/v2/__init__.py

@@ -34,7 +34,7 @@
 from .nbpy import reads as read_py, writes as write_py
 from .nbpy import to_notebook as to_notebook_py
 
-from .convert import convert_to_this_nbformat
+from .convert import downgrade, upgrade
 
 #-----------------------------------------------------------------------------
 # Code

IPython/nbformat/v2/convert.py

@@ -3,6 +3,7 @@
 Authors:
 
 * Brian Granger
+* Jonathan Frederic
 """
 
 #-----------------------------------------------------------------------------
@@ -24,7 +25,7 @@
 # Code
 #-----------------------------------------------------------------------------
 
-def convert_to_this_nbformat(nb, orig_version=1):
+def upgrade(nb, from_version=1):
     """Convert a notebook to the v2 format.
 
     Parameters
@@ -48,3 +49,13 @@ def convert_to_this_nbformat(nb, orig_version=1):
     else:
         raise ValueError('Cannot convert a notebook from v%s to v2' % orig_version)
 
+
+def downgrade(nb):
+    """Convert a v2 notebook to v1.
+
+    Parameters
+    ----------
+    nb : NotebookNode
+        The Python representation of the notebook to convert.
+    """
+    raise Exception("Downgrade from notebook v2 to v1 is not supported.")

IPython/nbformat/v3/__init__.py

@@ -30,7 +30,7 @@
 from .nbpy import reads as read_py, writes as write_py
 from .nbpy import to_notebook as to_notebook_py
 
-from .convert import convert_to_this_nbformat
+from .convert import downgrade, upgrade
 
 #-----------------------------------------------------------------------------
 # Code