support downgrading notebooks with nbconvert

Use:

    ipython nbconvert --to notebook --nbformat 3 notebook.ipynb

to write `notebook.v3.ipynb`

Adds `output_suffix` resource, inserted before file ext.
Suffix is used if `--output` is not specified.

Default is `.nbconvert`, to prevent `--to notebook` from clobbering existing notebooks by default.

IPython/nbconvert/exporters/__init__.py

@@ -1,10 +1,11 b''
 from .export import *
 from .html import HTMLExporter
 from .slides import SlidesExporter
 from .templateexporter import TemplateExporter
 from .latex import LatexExporter
 from .markdown import MarkdownExporter
+from .notebook import NotebookExporter
 from .pdf import PDFExporter
 from .python import PythonExporter
 from .rst import RSTExporter
 from .exporter import Exporter

IPython/nbconvert/exporters/notebook.py

@@ -1,21 +1,32 b''
 """NotebookExporter class"""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from .exporter import Exporter
 from IPython.nbformat import current as nbformat
+from IPython.utils.traitlets import Enum
 
 class NotebookExporter(Exporter):
-    """
-    Exports an IPython notebook.
-    """
+    """Exports to an IPython notebook."""
+
+    nbformat_version = Enum(list(range(2, nbformat.current_nbformat + 1)),
+        default_value=nbformat.current_nbformat,
+        config=True,
+        help="""The nbformat version to write.
+        Use this to downgrade notebooks.
+        """
+    )
     def _file_extension_default(self):
         return 'ipynb'
 
     output_mimetype = 'application/json'
 
     def from_notebook_node(self, nb, resources=None, **kw):
         nb_copy, resources = super(NotebookExporter, self).from_notebook_node(nb, resources, **kw)
-        output = nbformat.writes_json(nb_copy)
+        if self.nbformat_version != nbformat.current_nbformat:
+            resources['output_suffix'] = '.v%i' % self.nbformat_version
+        else:
+            resources['output_suffix'] = '.nbconvert'
+        output = nbformat.writes(nb_copy, version=self.nbformat_version)
         return output, resources

IPython/nbconvert/exporters/tests/test_notebook.py

@@ -1,22 +1,36 b''
 """Tests for notebook.py"""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
+import json
+
 from .base import ExportersTestsBase
 from ..notebook import NotebookExporter
 
 class TestNotebookExporter(ExportersTestsBase):
     """Contains test functions for notebook.py"""
 
     exporter_class = NotebookExporter
 
     def test_export(self):
         """
         Does the NotebookExporter return the file unchanged?
         """
         with open(self._get_notebook()) as f:
             file_contents = f.read()
-        (output, resources) = NotebookExporter().from_filename(self._get_notebook())
+        (output, resources) = self.exporter_class().from_filename(self._get_notebook())
         assert len(output) > 0
-        assert output == file_contents
+        self.assertEqual(output, file_contents)
+
+    def test_downgrade_3(self):
+        exporter = self.exporter_class(nbformat_version=3)
+        (output, resources) = exporter.from_filename(self._get_notebook())
+        nb = json.loads(output)
+        self.assertEqual(nb['nbformat'], 3)
+
+    def test_downgrade_2(self):
+        exporter = self.exporter_class(nbformat_version=2)
+        (output, resources) = exporter.from_filename(self._get_notebook())
+        nb = json.loads(output)
+        self.assertEqual(nb['nbformat'], 2)

IPython/nbconvert/nbconvertapp.py

@@ -1,317 +1,320 b''
 #!/usr/bin/env python
 """NbConvert is a utility for conversion of .ipynb files.
 
 Command-line interface for the NbConvert conversion utility.
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from __future__ import print_function
 
 import logging
 import sys
 import os
 import glob
 
 from IPython.core.application import BaseIPythonApplication, base_aliases, base_flags
 from IPython.core.profiledir import ProfileDir
 from IPython.config import catch_config_error, Configurable
 from IPython.utils.traitlets import (
     Unicode, List, Instance, DottedObjectName, Type, CaselessStrEnum,
 )
 from IPython.utils.importstring import import_item
 
 from .exporters.export import get_export_names, exporter_map
 from IPython.nbconvert import exporters, preprocessors, writers, postprocessors
 from .utils.base import NbConvertBase
 from .utils.exceptions import ConversionException
 
 #-----------------------------------------------------------------------------
 #Classes and functions
 #-----------------------------------------------------------------------------
 
 class DottedOrNone(DottedObjectName):
     """
     A string holding a valid dotted object name in Python, such as A.b3._c
     Also allows for None type."""
     
     default_value = u''
 
     def validate(self, obj, value):
         if value is not None and len(value) > 0:
             return super(DottedOrNone, self).validate(obj, value)
         else:
             return value
             
 nbconvert_aliases = {}
 nbconvert_aliases.update(base_aliases)
 nbconvert_aliases.update({
     'to' : 'NbConvertApp.export_format',
     'template' : 'TemplateExporter.template_file',
     'writer' : 'NbConvertApp.writer_class',
     'post': 'NbConvertApp.postprocessor_class',
     'output': 'NbConvertApp.output_base',
     'reveal-prefix': 'RevealHelpPreprocessor.url_prefix',
+    'nbformat': 'NotebookExporter.nbformat_version',
 })
 
 nbconvert_flags = {}
 nbconvert_flags.update(base_flags)
 nbconvert_flags.update({
     'stdout' : (
         {'NbConvertApp' : {'writer_class' : "StdoutWriter"}},
         "Write notebook output to stdout instead of files."
         )
 })
 
 
 class NbConvertApp(BaseIPythonApplication):
     """Application used to convert from notebook file type (``*.ipynb``)"""
 
     name = 'ipython-nbconvert'
     aliases = nbconvert_aliases
     flags = nbconvert_flags
     
     def _log_level_default(self):
         return logging.INFO
     
     def _classes_default(self):
         classes = [NbConvertBase, ProfileDir]
         for pkg in (exporters, preprocessors, writers, postprocessors):
             for name in dir(pkg):
                 cls = getattr(pkg, name)
                 if isinstance(cls, type) and issubclass(cls, Configurable):
                     classes.append(cls)
         
         return classes
 
     description = Unicode(
         u"""This application is used to convert notebook files (*.ipynb)
         to various other formats.
 
         WARNING: THE COMMANDLINE INTERFACE MAY CHANGE IN FUTURE RELEASES.""")
 
     output_base = Unicode('', config=True, help='''overwrite base name use for output files.
-            can only  be use when converting one notebook at a time.
+            can only be used when converting one notebook at a time.
             ''')
 
     examples = Unicode(u"""
         The simplest way to use nbconvert is
         
         > ipython nbconvert mynotebook.ipynb
         
         which will convert mynotebook.ipynb to the default format (probably HTML).
         
         You can specify the export format with `--to`.
         Options include {0}
         
         > ipython nbconvert --to latex mynotebook.ipynb
 
         Both HTML and LaTeX support multiple output templates. LaTeX includes
         'base', 'article' and 'report'.  HTML includes 'basic' and 'full'. You
         can specify the flavor of the format used.
 
         > ipython nbconvert --to html --template basic mynotebook.ipynb
         
         You can also pipe the output to stdout, rather than a file
         
         > ipython nbconvert mynotebook.ipynb --stdout
 
         PDF is generated via latex
 
         > ipython nbconvert mynotebook.ipynb --to pdf
         
         You can get (and serve) a Reveal.js-powered slideshow
         
         > ipython nbconvert myslides.ipynb --to slides --post serve
         
         Multiple notebooks can be given at the command line in a couple of 
         different ways:
   
         > ipython nbconvert notebook*.ipynb
         > ipython nbconvert notebook1.ipynb notebook2.ipynb
         
         or you can specify the notebooks list in a config file, containing::
         
             c.NbConvertApp.notebooks = ["my_notebook.ipynb"]
         
         > ipython nbconvert --config mycfg.py
         """.format(get_export_names()))
 
     # Writer specific variables
     writer = Instance('IPython.nbconvert.writers.base.WriterBase',  
                       help="""Instance of the writer class used to write the 
                       results of the conversion.""")
     writer_class = DottedObjectName('FilesWriter', config=True, 
                                     help="""Writer class used to write the 
                                     results of the conversion""")
     writer_aliases = {'fileswriter': 'IPython.nbconvert.writers.files.FilesWriter',
                       'debugwriter': 'IPython.nbconvert.writers.debug.DebugWriter',
                       'stdoutwriter': 'IPython.nbconvert.writers.stdout.StdoutWriter'}
     writer_factory = Type()
 
     def _writer_class_changed(self, name, old, new):
         if new.lower() in self.writer_aliases:
             new = self.writer_aliases[new.lower()]
         self.writer_factory = import_item(new)
 
     # Post-processor specific variables
     postprocessor = Instance('IPython.nbconvert.postprocessors.base.PostProcessorBase',  
                       help="""Instance of the PostProcessor class used to write the 
                       results of the conversion.""")
 
     postprocessor_class = DottedOrNone(config=True, 
                                     help="""PostProcessor class used to write the 
                                     results of the conversion""")
     postprocessor_aliases = {'serve': 'IPython.nbconvert.postprocessors.serve.ServePostProcessor'}
     postprocessor_factory = Type()
 
     def _postprocessor_class_changed(self, name, old, new):
         if new.lower() in self.postprocessor_aliases:
             new = self.postprocessor_aliases[new.lower()]
         if new:
             self.postprocessor_factory = import_item(new)
 
 
     # Other configurable variables
     export_format = CaselessStrEnum(get_export_names(),
         default_value="html",
         config=True,
         help="""The export format to be used."""
     )
 
     notebooks = List([], config=True, help="""List of notebooks to convert.
                      Wildcards are supported.
                      Filenames passed positionally will be added to the list.
                      """)
 
     @catch_config_error
     def initialize(self, argv=None):
         self.init_syspath()
         super(NbConvertApp, self).initialize(argv)
         self.init_notebooks()
         self.init_writer()
         self.init_postprocessor()
 
 
 
     def init_syspath(self):
         """
         Add the cwd to the sys.path ($PYTHONPATH)
         """
         sys.path.insert(0, os.getcwd())
         
 
     def init_notebooks(self):
         """Construct the list of notebooks.
         If notebooks are passed on the command-line,
         they override notebooks specified in config files.
         Glob each notebook to replace notebook patterns with filenames.
         """
 
         # Specifying notebooks on the command-line overrides (rather than adds)
         # the notebook list
         if self.extra_args:
             patterns = self.extra_args
         else:
             patterns = self.notebooks
 
         # Use glob to replace all the notebook patterns with filenames.
         filenames = []
         for pattern in patterns:
             
             # Use glob to find matching filenames.  Allow the user to convert 
             # notebooks without having to type the extension.
             globbed_files = glob.glob(pattern)
             globbed_files.extend(glob.glob(pattern + '.ipynb'))
             if not globbed_files:
                 self.log.warn("pattern %r matched no files", pattern)
 
             for filename in globbed_files:
                 if not filename in filenames:
                     filenames.append(filename)
         self.notebooks = filenames
 
     def init_writer(self):
         """
         Initialize the writer (which is stateless)
         """
         self._writer_class_changed(None, self.writer_class, self.writer_class)
         self.writer = self.writer_factory(parent=self)
 
     def init_postprocessor(self):
         """
         Initialize the postprocessor (which is stateless)
         """
         self._postprocessor_class_changed(None, self.postprocessor_class, 
             self.postprocessor_class)
         if self.postprocessor_factory:
             self.postprocessor = self.postprocessor_factory(parent=self)
 
     def start(self):
         """
         Ran after initialization completed
         """
         super(NbConvertApp, self).start()
         self.convert_notebooks()
 
     def convert_notebooks(self):
         """
         Convert the notebooks in the self.notebook traitlet
         """
         # Export each notebook
         conversion_success = 0
 
         if self.output_base != '' and len(self.notebooks) > 1:
             self.log.error(
             """UsageError: --output flag or `NbConvertApp.output_base` config option
             cannot be used when converting multiple notebooks.
             """)
             self.exit(1)
         
         exporter = exporter_map[self.export_format](config=self.config)
 
         for notebook_filename in self.notebooks:
             self.log.info("Converting notebook %s to %s", notebook_filename, self.export_format)
 
             # Get a unique key for the notebook and set it in the resources object.
             basename = os.path.basename(notebook_filename)
             notebook_name = basename[:basename.rfind('.')]
             if self.output_base:
                 # strip duplicate extension from output_base, to avoid Basname.ext.ext
                 if getattr(exporter, 'file_extension', False):
                     base, ext = os.path.splitext(self.output_base)
                     if ext == '.' + exporter.file_extension:
                         self.output_base = base
                 notebook_name = self.output_base
             resources = {}
             resources['profile_dir'] = self.profile_dir.location
             resources['unique_key'] = notebook_name
             resources['output_files_dir'] = '%s_files' % notebook_name
             self.log.info("Support files will be in %s", os.path.join(resources['output_files_dir'], ''))
 
             # Try to export
             try:
                 output, resources = exporter.from_filename(notebook_filename, resources=resources)
             except ConversionException as e:
                 self.log.error("Error while converting '%s'", notebook_filename,
                       exc_info=True)
                 self.exit(1)
             else:
+                if 'output_suffix' in resources and not self.output_base:
+                    notebook_name += resources['output_suffix']
                 write_results = self.writer.write(output, resources, notebook_name=notebook_name)
 
                 #Post-process if post processor has been defined.
                 if hasattr(self, 'postprocessor') and self.postprocessor:
                     self.postprocessor(write_results)
                 conversion_success += 1
 
         # If nothing was converted successfully, help the user.
         if conversion_success == 0:
             self.print_help()
             sys.exit(-1)
             
 #-----------------------------------------------------------------------------
 # Main entry point
 #-----------------------------------------------------------------------------
 
 launch_new_instance = NbConvertApp.launch_instance