move NotebookNode to top-level

should common to all nbformats

(I didn't change the old nbformats to  use it, just in case)

IPython/nbformat/notebooknode.py

@@ -0,0 +1,21 b''
+"""NotebookNode - adding attribute access to dicts"""
+
+from IPython.utils.ipstruct import Struct
+
+class NotebookNode(Struct):
+    """A dict-like node with attribute-access"""
+    pass
+
+def from_dict(d):
+    """Convert dict to dict-like NotebookNode
+    
+    Recursively converts any dict in the container to a NotebookNode
+    """
+    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
+
+

IPython/nbconvert/exporters/export.py

@@ -1,174 +1,174 b''
 """Module containing single call export functions."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from functools import wraps
 
-from IPython.nbformat.v4 import NotebookNode
+from IPython.nbformat import NotebookNode
 from IPython.utils.decorators import undoc
 from IPython.utils.py3compat import string_types
 
 from .exporter import Exporter
 from .templateexporter import TemplateExporter
 from .html import HTMLExporter
 from .slides import SlidesExporter
 from .latex import LatexExporter
 from .pdf import PDFExporter
 from .markdown import MarkdownExporter
 from .python import PythonExporter
 from .rst import RSTExporter
 from .notebook import NotebookExporter
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 @undoc
 def DocDecorator(f):
     
     #Set docstring of function
     f.__doc__ = f.__doc__ + """
-    nb : :class:`~{nbnode_mod}.NotebookNode`
+    nb : :class:`~IPython.nbformat.NotebookNode`
       The notebook to export.
     config : config (optional, keyword arg)
         User configuration instance.
     resources : dict (optional, keyword arg)
         Resources used in the conversion process.
         
     Returns
     -------
     tuple- output, resources, exporter_instance
     output : str
         Jinja 2 output.  This is the resulting converted notebook.
     resources : dictionary
         Dictionary of resources used prior to and during the conversion 
         process.
     exporter_instance : Exporter
         Instance of the Exporter class used to export the document.  Useful
         to caller because it provides a 'file_extension' property which
         specifies what extension the output should be saved as.
 
     Notes
     -----
     WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
-    """.format(nbnode_mod=NotebookNode.__module__)
+    """
             
     @wraps(f)
     def decorator(*args, **kwargs):
         return f(*args, **kwargs)
     
     return decorator
 
 
 #-----------------------------------------------------------------------------
 # Functions
 #-----------------------------------------------------------------------------
 
 __all__ = [
     'export',
     'export_html',
     'export_custom',
     'export_slides',
     'export_latex',
     'export_pdf',
     'export_markdown',
     'export_python',
     'export_rst',
     'export_by_name',
     'get_export_names',
     'ExporterNameError'
 ]
 
 
 class ExporterNameError(NameError):
     pass
 
 @DocDecorator
 def export(exporter, nb, **kw):
     """
     Export a notebook object using specific exporter class.
     
     Parameters
     ----------
     exporter : class:`~IPython.nbconvert.exporters.exporter.Exporter` class or instance
       Class type or instance of the exporter that should be used.  If the
       method initializes it's own instance of the class, it is ASSUMED that
       the class type provided exposes a constructor (``__init__``) with the same
       signature as the base Exporter class.
     """
     
     #Check arguments
     if exporter is None:
         raise TypeError("Exporter is None")
     elif not isinstance(exporter, Exporter) and not issubclass(exporter, Exporter):
         raise TypeError("exporter does not inherit from Exporter (base)")
     if nb is None:
         raise TypeError("nb is None")
     
     #Create the exporter
     resources = kw.pop('resources', None)
     if isinstance(exporter, Exporter):
         exporter_instance = exporter
     else:
         exporter_instance = exporter(**kw)
     
     #Try to convert the notebook using the appropriate conversion function.
     if isinstance(nb, NotebookNode):
         output, resources = exporter_instance.from_notebook_node(nb, resources)
     elif isinstance(nb, string_types):
         output, resources = exporter_instance.from_filename(nb, resources)
     else:
         output, resources = exporter_instance.from_file(nb, resources)
     return output, resources
 
 exporter_map = dict(
     custom=TemplateExporter,
     html=HTMLExporter,
     slides=SlidesExporter,
     latex=LatexExporter,
     pdf=PDFExporter,
     markdown=MarkdownExporter,
     python=PythonExporter,
     rst=RSTExporter,
     notebook=NotebookExporter,
 )
 
 def _make_exporter(name, E):
     """make an export_foo function from a short key and Exporter class E"""
     def _export(nb, **kw):
         return export(E, nb, **kw)
     _export.__doc__ = """Export a notebook object to {0} format""".format(name)
     return _export
     
 g = globals()
 
 for name, E in exporter_map.items():
     g['export_%s' % name] = DocDecorator(_make_exporter(name, E))
 
 @DocDecorator
 def export_by_name(format_name, nb, **kw):
     """
     Export a notebook object to a template type by its name.  Reflection
     (Inspect) is used to find the template's corresponding explicit export
     method defined in this module.  That method is then called directly.
     
     Parameters
     ----------
     format_name : str
         Name of the template style to export to.
     """
     
     function_name = "export_" + format_name.lower()
     
     if function_name in globals():
         return globals()[function_name](nb, **kw)
     else:
         raise ExporterNameError("template for `%s` not found" % function_name)
 
 
 def get_export_names():
     """Return a list of the currently supported export targets
 
     WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT"""
     return sorted(exporter_map.keys())

IPython/nbconvert/exporters/exporter.py

@@ -1,259 +1,259 b''
 """This module defines a base Exporter class. For Jinja template-based export,
 see templateexporter.py.
 """
 
 
 from __future__ import print_function, absolute_import
 
 import io
 import os
 import copy
 import collections
 import datetime
 
 from IPython.config.configurable import LoggingConfigurable
 from IPython.config import Config
 from IPython import nbformat
 from IPython.utils.traitlets import MetaHasTraits, Unicode, List
 from IPython.utils.importstring import import_item
 from IPython.utils import text, py3compat
 
 
 class ResourcesDict(collections.defaultdict):
     def __missing__(self, key):
         return ''
 
 
 class Exporter(LoggingConfigurable):
     """
     Class containing methods that sequentially run a list of preprocessors on a 
     NotebookNode object and then return the modified NotebookNode object and 
     accompanying resources dict.
     """
 
     file_extension = Unicode(
         'txt', config=True,
         help="Extension of the file that should be written to disk"
         )
 
     # MIME type of the result file, for HTTP response headers.
     # This is *not* a traitlet, because we want to be able to access it from
     # the class, not just on instances.
     output_mimetype = ''
 
     #Configurability, allows the user to easily add filters and preprocessors.
     preprocessors = List(config=True,
         help="""List of preprocessors, by name or namespace, to enable.""")
 
     _preprocessors = List()
 
     default_preprocessors = List(['IPython.nbconvert.preprocessors.coalesce_streams',
                                   'IPython.nbconvert.preprocessors.SVG2PDFPreprocessor',
                                   'IPython.nbconvert.preprocessors.ExtractOutputPreprocessor',
                                   'IPython.nbconvert.preprocessors.CSSHTMLHeaderPreprocessor',
                                   'IPython.nbconvert.preprocessors.RevealHelpPreprocessor',
                                   'IPython.nbconvert.preprocessors.LatexPreprocessor',
                                   'IPython.nbconvert.preprocessors.ClearOutputPreprocessor',
                                   'IPython.nbconvert.preprocessors.ExecutePreprocessor',
                                   'IPython.nbconvert.preprocessors.HighlightMagicsPreprocessor'],
         config=True,
         help="""List of preprocessors available by default, by name, namespace, 
         instance, or type.""")
 
 
     def __init__(self, config=None, **kw):
         """
         Public constructor
 
         Parameters
         ----------
         config : config
             User configuration instance.
         """
         with_default_config = self.default_config
         if config:
             with_default_config.merge(config)
         
         super(Exporter, self).__init__(config=with_default_config, **kw)
 
         self._init_preprocessors()
 
 
     @property
     def default_config(self):
         return Config()
 
     def from_notebook_node(self, nb, resources=None, **kw):
         """
         Convert a notebook from a notebook node instance.
 
         Parameters
         ----------
-        nb : :class:`~IPython.nbformat.current.NotebookNode`
+        nb : :class:`~IPython.nbformat.NotebookNode`
           Notebook node (dict-like with attr-access)
         resources : dict
           Additional resources that can be accessed read/write by
           preprocessors and filters.
         **kw
           Ignored (?)
         """
         nb_copy = copy.deepcopy(nb)
         resources = self._init_resources(resources)
         
         if 'language' in nb['metadata']:
             resources['language'] = nb['metadata']['language'].lower()
 
         # Preprocess
         nb_copy, resources = self._preprocess(nb_copy, resources)
 
         return nb_copy, resources
 
 
     def from_filename(self, filename, resources=None, **kw):
         """
         Convert a notebook from a notebook file.
 
         Parameters
         ----------
         filename : str
             Full filename of the notebook file to open and convert.
         """
 
         # Pull the metadata from the filesystem.
         if resources is None:
             resources = ResourcesDict()
         if not 'metadata' in resources or resources['metadata'] == '':
             resources['metadata'] = ResourcesDict()
         basename = os.path.basename(filename)
         notebook_name = basename[:basename.rfind('.')]
         resources['metadata']['name'] = notebook_name
 
         modified_date = datetime.datetime.fromtimestamp(os.path.getmtime(filename))
         resources['metadata']['modified_date'] = modified_date.strftime(text.date_format)
 
         with io.open(filename, encoding='utf-8') as f:
             return self.from_notebook_node(nbformat.read(f, as_version=4), resources=resources, **kw)
 
 
     def from_file(self, file_stream, resources=None, **kw):
         """
         Convert a notebook from a notebook file.
 
         Parameters
         ----------
         file_stream : file-like object
             Notebook file-like object to convert.
         """
         return self.from_notebook_node(nbformat.read(file_stream, as_version=4), resources=resources, **kw)
 
 
     def register_preprocessor(self, preprocessor, enabled=False):
         """
         Register a preprocessor.
         Preprocessors are classes that act upon the notebook before it is
         passed into the Jinja templating engine.  preprocessors are also
         capable of passing additional information to the Jinja
         templating engine.
 
         Parameters
         ----------
         preprocessor : preprocessor
         """
         if preprocessor is None:
             raise TypeError('preprocessor')
         isclass = isinstance(preprocessor, type)
         constructed = not isclass
 
         # Handle preprocessor's registration based on it's type
         if constructed and isinstance(preprocessor, py3compat.string_types):
             # Preprocessor is a string, import the namespace and recursively call
             # this register_preprocessor method
             preprocessor_cls = import_item(preprocessor)
             return self.register_preprocessor(preprocessor_cls, enabled)
 
         if constructed and hasattr(preprocessor, '__call__'):
             # Preprocessor is a function, no need to construct it.
             # Register and return the preprocessor.
             if enabled:
                 preprocessor.enabled = True
             self._preprocessors.append(preprocessor)
             return preprocessor
 
         elif isclass and isinstance(preprocessor, MetaHasTraits):
             # Preprocessor is configurable.  Make sure to pass in new default for 
             # the enabled flag if one was specified.
             self.register_preprocessor(preprocessor(parent=self), enabled)
 
         elif isclass:
             # Preprocessor is not configurable, construct it
             self.register_preprocessor(preprocessor(), enabled)
 
         else:
             # Preprocessor is an instance of something without a __call__ 
             # attribute.  
             raise TypeError('preprocessor')
 
 
     def _init_preprocessors(self):
         """
         Register all of the preprocessors needed for this exporter, disabled
         unless specified explicitly.
         """
         self._preprocessors = []
 
         # Load default preprocessors (not necessarly enabled by default).
         for preprocessor in self.default_preprocessors:
             self.register_preprocessor(preprocessor)
 
         # Load user-specified preprocessors.  Enable by default.
         for preprocessor in self.preprocessors:
             self.register_preprocessor(preprocessor, enabled=True)
 
 
     def _init_resources(self, resources):
 
         #Make sure the resources dict is of ResourcesDict type.
         if resources is None:
             resources = ResourcesDict()
         if not isinstance(resources, ResourcesDict):
             new_resources = ResourcesDict()
             new_resources.update(resources)
             resources = new_resources
 
         #Make sure the metadata extension exists in resources
         if 'metadata' in resources:
             if not isinstance(resources['metadata'], ResourcesDict):
                 resources['metadata'] = ResourcesDict(resources['metadata'])
         else:
             resources['metadata'] = ResourcesDict()
             if not resources['metadata']['name']:
                 resources['metadata']['name'] = 'Notebook'
 
         #Set the output extension
         resources['output_extension'] = self.file_extension
         return resources
 
 
     def _preprocess(self, nb, resources):
         """
         Preprocess the notebook before passing it into the Jinja engine.
         To preprocess the notebook is to apply all of the
 
         Parameters
         ----------
         nb : notebook node
             notebook that is being exported.
         resources : a dict of additional resources that
             can be accessed read/write by preprocessors
         """
 
         # Do a copy.deepcopy first,
         # we are never safe enough with what the preprocessors could do.
         nbc =  copy.deepcopy(nb)
         resc = copy.deepcopy(resources)
 
         #Run each preprocessor on the notebook.  Carry the output along
         #to each preprocessor
         for preprocessor in self._preprocessors:
             nbc, resc = preprocessor(nbc, resc)
         return nbc, resc

IPython/nbconvert/exporters/templateexporter.py

@@ -1,321 +1,321 b''
 """This module defines TemplateExporter, a highly configurable converter
 that uses Jinja2 to export notebook files into different formats.
 """
 
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 from __future__ import print_function, absolute_import
 
 # Stdlib imports
 import os
 
 # other libs/dependencies are imported at runtime
 # to move ImportErrors to runtime when the requirement is actually needed
 
 # IPython imports
 from IPython.utils.traitlets import MetaHasTraits, Unicode, List, Dict, Any
 from IPython.utils.importstring import import_item
 from IPython.utils import py3compat, text
 
 from IPython.nbconvert import filters
 from .exporter import Exporter
 
 #-----------------------------------------------------------------------------
 # Globals and constants
 #-----------------------------------------------------------------------------
 
 #Jinja2 extensions to load.
 JINJA_EXTENSIONS = ['jinja2.ext.loopcontrols']
 
 default_filters = {
         'indent': text.indent,
         'markdown2html': filters.markdown2html,
         'ansi2html': filters.ansi2html,
         'filter_data_type': filters.DataTypeFilter,
         'get_lines': filters.get_lines,
         'highlight2html': filters.Highlight2HTML,
         'highlight2latex': filters.Highlight2Latex,
         'ipython2python': filters.ipython2python,
         'posix_path': filters.posix_path,
         'markdown2latex': filters.markdown2latex,
         'markdown2rst': filters.markdown2rst,
         'comment_lines': filters.comment_lines,
         'strip_ansi': filters.strip_ansi,
         'strip_dollars': filters.strip_dollars,
         'strip_files_prefix': filters.strip_files_prefix,
         'html2text' : filters.html2text,
         'add_anchor': filters.add_anchor,
         'ansi2latex': filters.ansi2latex,
         'wrap_text': filters.wrap_text,
         'escape_latex': filters.escape_latex,
         'citation2latex': filters.citation2latex,
         'path2url': filters.path2url,
         'add_prompts': filters.add_prompts,
         'ascii_only': filters.ascii_only,
         'prevent_list_blocks': filters.prevent_list_blocks,
 }
 
 #-----------------------------------------------------------------------------
 # Class
 #-----------------------------------------------------------------------------
 
 class TemplateExporter(Exporter):
     """
     Exports notebooks into other file formats.  Uses Jinja 2 templating engine
     to output new formats.  Inherit from this class if you are creating a new
     template type along with new filters/preprocessors.  If the filters/
     preprocessors provided by default suffice, there is no need to inherit from
     this class.  Instead, override the template_file and file_extension
     traits via a config file.
 
     {filters}
     """
     
     # finish the docstring
     __doc__ = __doc__.format(filters = '- '+'\n    - '.join(default_filters.keys()))
 
 
     template_file = Unicode(u'default',
             config=True,
             help="Name of the template file to use")
     def _template_file_changed(self, name, old, new):
         if new == 'default':
             self.template_file = self.default_template
         else:
             self.template_file = new
         self.template = None
         self._load_template()
     
     default_template = Unicode(u'')
     template = Any()
     environment = Any()
 
     template_path = List(['.'], config=True)
     def _template_path_changed(self, name, old, new):
         self._load_template()
 
     default_template_path = Unicode(
         os.path.join("..", "templates"), 
         help="Path where the template files are located.")
 
     template_skeleton_path = Unicode(
         os.path.join("..", "templates", "skeleton"), 
         help="Path where the template skeleton files are located.") 
 
     #Jinja block definitions
     jinja_comment_block_start = Unicode("", config=True)
     jinja_comment_block_end = Unicode("", config=True)
     jinja_variable_block_start = Unicode("", config=True)
     jinja_variable_block_end = Unicode("", config=True)
     jinja_logic_block_start = Unicode("", config=True)
     jinja_logic_block_end = Unicode("", config=True)
     
     #Extension that the template files use.    
     template_extension = Unicode(".tpl", config=True)
 
     filters = Dict(config=True,
         help="""Dictionary of filters, by name and namespace, to add to the Jinja
         environment.""")
 
     raw_mimetypes = List(config=True,
         help="""formats of raw cells to be included in this Exporter's output."""
     )
     def _raw_mimetypes_default(self):
         return [self.output_mimetype, '']
 
 
     def __init__(self, config=None, extra_loaders=None, **kw):
         """
         Public constructor
     
         Parameters
         ----------
         config : config
             User configuration instance.
         extra_loaders : list[of Jinja Loaders]
             ordered list of Jinja loader to find templates. Will be tried in order
             before the default FileSystem ones.
         template : str (optional, kw arg)
             Template to use when exporting.
         """
         super(TemplateExporter, self).__init__(config=config, **kw)
 
         #Init
         self._init_template()
         self._init_environment(extra_loaders=extra_loaders)
         self._init_filters()
 
 
     def _load_template(self):
         """Load the Jinja template object from the template file
         
         This is a no-op if the template attribute is already defined,
         or the Jinja environment is not setup yet.
         
         This is triggered by various trait changes that would change the template.
         """
         from jinja2 import TemplateNotFound
         
         if self.template is not None:
             return
         # called too early, do nothing
         if self.environment is None:
             return
         # Try different template names during conversion.  First try to load the
         # template by name with extension added, then try loading the template
         # as if the name is explicitly specified, then try the name as a 
         # 'flavor', and lastly just try to load the template by module name.
         try_names = []
         if self.template_file:
             try_names.extend([
                 self.template_file + self.template_extension,
                 self.template_file,
             ])
         for try_name in try_names:
             self.log.debug("Attempting to load template %s", try_name)
             try:
                 self.template = self.environment.get_template(try_name)
             except (TemplateNotFound, IOError):
                 pass
             except Exception as e:
                 self.log.warn("Unexpected exception loading template: %s", try_name, exc_info=True)
             else:
                 self.log.info("Loaded template %s", try_name)
                 break
 
     def from_notebook_node(self, nb, resources=None, **kw):
         """
         Convert a notebook from a notebook node instance.
     
         Parameters
         ----------
-        nb : :class:`~IPython.nbformat.current.NotebookNode`
+        nb : :class:`~IPython.nbformat.NotebookNode`
           Notebook node
         resources : dict
           Additional resources that can be accessed read/write by
           preprocessors and filters.
         """
         nb_copy, resources = super(TemplateExporter, self).from_notebook_node(nb, resources, **kw)
         resources.setdefault('raw_mimetypes', self.raw_mimetypes)
 
         self._load_template()
 
         if self.template is not None:
             output = self.template.render(nb=nb_copy, resources=resources)
         else:
             raise IOError('template file "%s" could not be found' % self.template_file)
         return output, resources
 
 
     def register_filter(self, name, jinja_filter):
         """
         Register a filter.
         A filter is a function that accepts and acts on one string.  
         The filters are accesible within the Jinja templating engine.
     
         Parameters
         ----------
         name : str
             name to give the filter in the Jinja engine
         filter : filter
         """
         if jinja_filter is None:
             raise TypeError('filter')
         isclass = isinstance(jinja_filter, type)
         constructed = not isclass
 
         #Handle filter's registration based on it's type
         if constructed and isinstance(jinja_filter, py3compat.string_types):
             #filter is a string, import the namespace and recursively call
             #this register_filter method
             filter_cls = import_item(jinja_filter)
             return self.register_filter(name, filter_cls)
         
         if constructed and hasattr(jinja_filter, '__call__'):
             #filter is a function, no need to construct it.
             self.environment.filters[name] = jinja_filter
             return jinja_filter
 
         elif isclass and isinstance(jinja_filter, MetaHasTraits):
             #filter is configurable.  Make sure to pass in new default for 
             #the enabled flag if one was specified.
             filter_instance = jinja_filter(parent=self)
             self.register_filter(name, filter_instance )
 
         elif isclass:
             #filter is not configurable, construct it
             filter_instance = jinja_filter()
             self.register_filter(name, filter_instance)
 
         else:
             #filter is an instance of something without a __call__ 
             #attribute.  
             raise TypeError('filter')
 
         
     def _init_template(self):
         """
         Make sure a template name is specified.  If one isn't specified, try to
         build one from the information we know.
         """
         self._template_file_changed('template_file', self.template_file, self.template_file)
         
 
     def _init_environment(self, extra_loaders=None):
         """
         Create the Jinja templating environment.
         """
         from jinja2 import Environment, ChoiceLoader, FileSystemLoader
         here = os.path.dirname(os.path.realpath(__file__))
         loaders = []
         if extra_loaders:
             loaders.extend(extra_loaders)
 
         paths = self.template_path
         paths.extend([os.path.join(here, self.default_template_path),
                       os.path.join(here, self.template_skeleton_path)])
         loaders.append(FileSystemLoader(paths))
 
         self.environment = Environment(
             loader= ChoiceLoader(loaders),
             extensions=JINJA_EXTENSIONS
             )
         
         #Set special Jinja2 syntax that will not conflict with latex.
         if self.jinja_logic_block_start:
             self.environment.block_start_string = self.jinja_logic_block_start
         if self.jinja_logic_block_end:
             self.environment.block_end_string = self.jinja_logic_block_end
         if self.jinja_variable_block_start:
             self.environment.variable_start_string = self.jinja_variable_block_start
         if self.jinja_variable_block_end:
             self.environment.variable_end_string = self.jinja_variable_block_end
         if self.jinja_comment_block_start:
             self.environment.comment_start_string = self.jinja_comment_block_start
         if self.jinja_comment_block_end:
             self.environment.comment_end_string = self.jinja_comment_block_end
 
     
     def _init_filters(self):
         """
         Register all of the filters required for the exporter.
         """
         
         #Add default filters to the Jinja2 environment
         for key, value in default_filters.items():
             self.register_filter(key, value)
 
         #Load user filters.  Overwrite existing filters if need be.
         if self.filters:
             for key, user_filter in self.filters.items():
                 self.register_filter(key, user_filter)

IPython/nbformat/__init__.py

@@ -1,143 +1,144 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 .notebooknode import from_dict, NotebookNode
 
 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/v4/__init__.py

@@ -1,19 +1,19 b''
 """The main API for the v4 notebook format."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from .nbbase import (
-    NotebookNode, from_dict,
     nbformat, nbformat_minor, nbformat_schema,
     new_code_cell, new_markdown_cell, new_notebook,
     new_output, output_from_msg,
 )
 
-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 .nbjson import reads, writes, to_notebook
+reads_json = reads
+writes_json = writes
+to_notebook_json = to_notebook
 
 from .convert import downgrade, upgrade
 
 

IPython/nbformat/v4/nbbase.py

@@ -1,149 +1,137 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
+from ..notebooknode import from_dict, NotebookNode
 
 # 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 .. 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/nbjson.py

@@ -1,60 +1,67 b''
 """Read and write notebooks in JSON format."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import copy
 import json
 
 from IPython.utils import py3compat
 
 from .nbbase import from_dict
 from .rwbase import (
     NotebookReader, NotebookWriter, rejoin_lines, split_lines, strip_transient
 )
 
 
 class BytesEncoder(json.JSONEncoder):
     """A JSON encoder that accepts b64 (and other *ascii*) bytestrings."""
     def default(self, obj):
         if isinstance(obj, bytes):
             return obj.decode('ascii')
         return json.JSONEncoder.default(self, obj)
 
 
 class JSONReader(NotebookReader):
 
     def reads(self, s, **kwargs):
+        """Read a JSON string into a Notebook object"""
         nb = json.loads(s, **kwargs)
         nb = self.to_notebook(nb, **kwargs)
         return nb
 
     def to_notebook(self, d, **kwargs):
-        nb = rejoin_lines(from_dict(d))
+        """Convert a disk-format notebook dict to in-memory NotebookNode
+        
+        handles multi-line values as strings, scrubbing of transient values, etc.
+        """
+        nb = from_dict(d)
+        nb = rejoin_lines(nb)
         nb = strip_transient(nb)
         return nb
 
 
 class JSONWriter(NotebookWriter):
 
     def writes(self, nb, **kwargs):
+        """Serialize a NotebookNode object as a JSON string"""
         kwargs['cls'] = BytesEncoder
         kwargs['indent'] = 1
         kwargs['sort_keys'] = True
         kwargs['separators'] = (',',': ')
         # don't modify in-memory dict
         nb = copy.deepcopy(nb)
         if kwargs.pop('split_lines', True):
             nb = split_lines(nb)
         nb = strip_transient(nb)
         return py3compat.str_to_unicode(json.dumps(nb, **kwargs), 'utf-8')
 
 
 _reader = JSONReader()
 _writer = JSONWriter()
 
 reads = _reader.reads
 read = _reader.read
 to_notebook = _reader.to_notebook
 write = _writer.write
 writes = _writer.writes