Notebook version conversions done right?

IPython/nbformat/reader.py

@@ -0,0 +1,100 b''
+"""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
+
+versions = {}
+for i in range(3):
+    versions[i+1] = __import__('v{0}'.format(i+1))
+
+#-----------------------------------------------------------------------------
+# 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, 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/__init__.py

@@ -1,3 +0,0 b''
-import v1
-import v2
-import v3

IPython/nbformat/convert.py

@@ -6,7 +6,7 b' Authors:'
 """
 
 #-----------------------------------------------------------------------------
-#  Copyright (C) 2008-2013  The IPython Development Team
+#  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.
@@ -18,51 +18,56 b' Authors:'
 
 import re
 
-import IPython.nbformat as nbformat
-
-#-----------------------------------------------------------------------------
-# Constants
-#-----------------------------------------------------------------------------
-
-# Get the convert modules for each major revision.
-VERSION_REGEX = re.compile("v[0-9]+")
-version_modules = {}
-for module in dir(nbformat):
-    if VERSION_REGEX.match(module):
-        version_modules[int(module[1:])] = eval('nbformat.' + module + '.convert')
-
-# Get the number of minor versions in each major version and create an ordered
-# list.
-versions = []
-for major in version_modules.keys().sort():
-    current_minor = 0
-    if hasattr(version_modules[major], 'nbformat_minor'):
-        current_minor = version_modules[major].nbformat_minor
-
-    for minor in range(0, current_minor + 1):
-        versions.append((major, minor))
+from .reader import get_version, versions
 
 #-----------------------------------------------------------------------------
 # Functions
 #-----------------------------------------------------------------------------
 
-def convert(nb, to_major, to_minor=0):
-    """Convert a notebook node object to a specific 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.
-    major = nb.get('nbformat', 1)
-    minor = nb.get('nbformat_minor', 0) # v3+
+    (version, version_minor) = get_version(nb)
+    version_numbers = versions.keys()
 
     # Check if destination is current version, if so return contents
-    if to_major == major and to_minor == minor:
+    if version == to_version:
         return nb
-    elif (to_major, to_minor) in versions:
-        index = versions.indexof((major, minor))
 
-        if to_major > major or (to_major == major and to_minor > minor):
-            to_index = index + 1
+    # 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:
-            to_index = index - 1
+            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.%d because that version doesn't exist" % (to_major, to_minor))
  No newline at end of file
+        raise Exception("Cannot convert notebook to v%d because that " \
+                        "version doesn't exist" % (to_version))

IPython/nbformat/current.py

@@ -3,6 +3,7 b''
 Authors:
 
 * Brian Granger
+* Jonathan Frederic
 """
 
 #-----------------------------------------------------------------------------
@@ -17,14 +18,10 b' Authors:'
 #-----------------------------------------------------------------------------
 
 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,
@@ -32,6 +29,9 b' from IPython.nbformat.v3 import ('
     nbformat_minor,
 )
 
+import reader
+from .convert import convert
+
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
@@ -43,20 +43,6 b' current_nbformat_minor = nbformat_minor'
 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 +62,26 b' 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(nb), current_nbformat)
 
 
 def writes_json(nb, **kwargs):
-    return v3.writes_json(nb, **kwargs)
+    return reader.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 = reader.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 reader.versions[3].writes_py(nb, **kwargs)
 
 
 # High level API

IPython/nbformat/v1/__init__.py

@@ -20,5 +20,4 b' from .nbjson import reads as reads_json, writes as writes_json'
 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 downgrade, upgrade

IPython/nbformat/v1/convert.py

@@ -11,6 +11,6 b''
 # 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 b' from .nbpy import reads as reads_py, writes as writes_py'
 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 b''
 Authors:
 
 * Brian Granger
+* Jonathan Frederic
 """
 
 #-----------------------------------------------------------------------------
@@ -24,7 +25,7 b' from .nbbase import ('
 # 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 b' 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 b' from .nbpy import reads as reads_py, writes as writes_py'
 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/v3/convert.py

@@ -3,6 +3,8 b''
 Authors:
 
 * Brian Granger
+* Min RK
+* Jonathan Frederic
 """
 
 #-----------------------------------------------------------------------------
@@ -27,33 +29,62 b' from IPython.nbformat import v2'
 # Code
 #-----------------------------------------------------------------------------
 
-def convert_to_this_nbformat(nb, orig_version=2, orig_minor=0):
-    """Convert a notebook to the v3 format.
+def upgrade(nb, from_version=2, from_minor=0):
+    """Convert a notebook to v3.
 
     Parameters
     ----------
     nb : NotebookNode
         The Python representation of the notebook to convert.
-    orig_version : int
+    from_version : int
         The original version of the notebook to convert.
-    orig_minor : int
+    from_minor : int
         The original minor version of the notebook to convert (only relevant for v >= 3).
     """
-    if orig_version == 1:
-        nb = v2.convert_to_this_nbformat(nb)
-        orig_version = 2
-    if orig_version == 2:
+    if from_version == 2:
         # Mark the original nbformat so consumers know it has been converted.
         nb.nbformat = nbformat
         nb.nbformat_minor = nbformat_minor
         
         nb.orig_nbformat = 2
         return nb
-    elif orig_version == 3:
-        if orig_minor != nbformat_minor:
-            nb.orig_nbformat_minor = orig_minor
+    elif from_version == 3:
+        if from_minor != nbformat_minor:
+            nb.orig_nbformat_minor = from_minor
         nb.nbformat_minor = nbformat_minor
         return nb
     else:
-        raise ValueError('Cannot convert a notebook from v%s to v3' % orig_version)
+        raise ValueError('Cannot convert a notebook directly from v%s to v3.  ' \
+                'Try using the IPython.nbformat.convert module.' % from_version)
+ 
 
+def heading_to_md(cell):
+    """turn heading cell into corresponding markdown"""
+    cell.cell_type = "markdown"
+    level = cell.pop('level', 1)
+    cell.source = '#'*level + ' ' + cell.source
+ 
+ 
+def raw_to_md(cell):
+    """let raw passthrough as markdown"""
+    cell.cell_type = "markdown"
+ 
+
+def downgrade(nb):
+    """Convert a v3 notebook to v2.
+
+    Parameters
+    ----------
+    nb : NotebookNode
+        The Python representation of the notebook to convert.
+    """
+    if nb.nbformat != 3:
+        return nb
+    nb.nbformat = 2
+    for ws in nb.worksheets:
+        for cell in ws.cells:
+            if cell.cell_type == 'heading':
+                heading_to_md(cell)
+            elif cell.cell_type == 'raw':
+                raw_to_md(cell)
+    return nb
  No newline at end of file