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

@@ -5,7 +5,7 b''
 
 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
 
@@ -29,7 +29,7 b' 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.
@@ -52,7 +52,7 b' def DocDecorator(f):'
     Notes
     -----
     WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
-    """.format(nbnode_mod=NotebookNode.__module__)
+    """
             
     @wraps(f)
     def decorator(*args, **kwargs):

IPython/nbconvert/exporters/exporter.py

@@ -89,7 +89,7 b' class Exporter(LoggingConfigurable):'
 
         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

IPython/nbconvert/exporters/templateexporter.py

@@ -199,7 +199,7 b' class TemplateExporter(Exporter):'
     
         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

IPython/nbformat/__init__.py

@@ -23,6 +23,7 b' versions = {'
 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,

IPython/nbformat/v4/__init__.py

@@ -4,15 +4,15 b''
 # 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

@@ -9,7 +9,7 b' 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
@@ -23,18 +23,6 b' def validate(node, ref=None):'
     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)

IPython/nbformat/v4/nbjson.py

@@ -25,12 +25,18 b' class BytesEncoder(json.JSONEncoder):'
 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
 
@@ -38,6 +44,7 b' class JSONReader(NotebookReader):'
 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