API docs gardening

IPython/nbformat/__init__.py

@@ -1,146 +1,150 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
 
+__all__ = ['versions', 'validate', 'ValidationError', 'convert', 'from_dict',
+           'NotebookNode', 'current_nbformat', 'current_nbformat_minor',
+           'NBFormatError', 'NO_CONVERT', 'reads', 'read', 'writes', 'write']
+
 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=NO_CONVERT, **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, optional
         The nbformat version to write.
         If unspecified, or specified as nbformat.NO_CONVERT,
         the notebook's own version will be used and no conversion performed.
 
     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(nb, fp, version=NO_CONVERT, **kwargs):
     """Write a notebook to a file in a given nbformat version.
     
     The file-like object must accept unicode input.
     
     Parameters
     ----------
     nb : NotebookNode
         The notebook to write.
     fp : file
         Any file-like object with a write method that accepts unicode.
     version : int, optional
         The nbformat version to write.
         If nb is not this version, it will be converted.
         If unspecified, or specified as nbformat.NO_CONVERT,
         the notebook's own version will be used and no conversion performed.
     """
     s = writes(nb, version, **kwargs)
     if isinstance(s, bytes):
         s = s.decode('utf8')
     return fp.write(s)

IPython/nbformat/v3/__init__.py

@@ -1,77 +1,70 b''
 """The main API for the v3 notebook format.
-
-Authors:
-
-* Brian Granger
 """
 
-#-----------------------------------------------------------------------------
-#  Copyright (C) 2008-2011  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.
-#-----------------------------------------------------------------------------
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
 
-#-----------------------------------------------------------------------------
-# Imports
-#-----------------------------------------------------------------------------
+__all__ = ['NotebookNode', 'new_code_cell', 'new_text_cell', 'new_notebook',
+           'new_output', 'new_worksheet', 'new_metadata', 'new_author',
+           'new_heading_cell', 'nbformat', 'nbformat_minor', 'nbformat_schema',
+           'reads_json', 'writes_json', 'read_json', 'write_json',
+           'to_notebook_json', 'reads_py', 'writes_py', 'read_py', 'write_py',
+           'to_notebook_py', 'downgrade', 'upgrade', 'parse_filename'
+        ]
 
 import os
 
 from .nbbase import (
     NotebookNode,
     new_code_cell, new_text_cell, new_notebook, new_output, new_worksheet,
     new_metadata, new_author, new_heading_cell, nbformat, nbformat_minor,
     nbformat_schema
 )
 
 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 .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 downgrade, upgrade
 
-#-----------------------------------------------------------------------------
-# Code
-#-----------------------------------------------------------------------------
 
 def parse_filename(fname):
     """Parse a notebook filename.
 
     This function takes a notebook filename and returns the notebook
     format (json/py) and the notebook name. This logic can be
     summarized as follows:
 
     * notebook.ipynb -> (notebook.ipynb, notebook, json)
     * notebook.json  -> (notebook.json, notebook, json)
     * notebook.py    -> (notebook.py, notebook, py)
     * notebook       -> (notebook.ipynb, notebook, json)
 
     Parameters
     ----------
     fname : unicode
         The notebook filename. The filename can use a specific filename
         extention (.ipynb, .json, .py) or none, in which case .ipynb will
         be assumed.
 
     Returns
     -------
     (fname, name, format) : (unicode, unicode, unicode)
         The filename, notebook name and format.
     """
     basename, ext = os.path.splitext(fname)
     if ext == u'.ipynb':
         format = u'json'
     elif ext == u'.json':
         format = u'json'
     elif ext == u'.py':
         format = u'py'
     else:
         basename = fname
         fname = fname + u'.ipynb'
         format = u'json'
     return fname, basename, format

IPython/nbformat/v4/__init__.py

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

docs/autogen_api.py

@@ -1,70 +1,79 b''
 #!/usr/bin/env python
 """Script to auto-generate our API docs.
 """
 # stdlib imports
 import os
 import sys
 
 # local imports
 sys.path.append(os.path.abspath('sphinxext'))
 from apigen import ApiDocWriter
 
 #*****************************************************************************
 if __name__ == '__main__':
     pjoin = os.path.join
     package = 'IPython'
     outdir = pjoin('source','api','generated')
     docwriter = ApiDocWriter(package,rst_extension='.rst')
     # You have to escape the . here because . is a special char for regexps.
     # You must do make clean if you change this!
     docwriter.package_skip_patterns += [r'\.external$',
                                         # Extensions are documented elsewhere.
                                         r'\.extensions',
                                         r'\.config\.profile',
-                                        # These should be accessed via nbformat.current
-                                        r'\.nbformat\.v\d+',
+                                        # Old nbformat versions
+                                        r'\.nbformat\.v[1-2]',
                                         # Public API for this is in kernel.zmq.eventloops
                                         r'\.kernel\.zmq\.gui',
                                         # Magics are documented separately
                                         r'\.core\.magics',
                                         ]
 
     # The inputhook* modules often cause problems on import, such as trying to
     # load incompatible Qt bindings. It's easiest to leave them all out. The
     # main API is in the inputhook module, which is documented.
     docwriter.module_skip_patterns += [ r'\.lib\.inputhook.+',
                                         r'\.ipdoctest',
                                         r'\.testing\.plugin',
                                         # This just prints a deprecation msg:
                                         r'\.frontend$',
                                         # Deprecated:
                                         r'\.core\.magics\.deprecated',
                                         # We document this manually.
                                         r'\.utils\.py3compat',
-                                        # These are exposed by nbformat.current
+                                        # These are exposed by nbformat
                                         r'\.nbformat\.convert',
                                         r'\.nbformat\.validator',
+                                        r'\.nbformat\.notebooknode',
+                                        # Deprecated
+                                        r'\.nbformat\.current',
+                                        # Exposed by nbformat.vN
+                                        r'\.nbformat\.v[3-4]\.nbbase',
                                         # These are exposed in display
                                         r'\.core\.display',
                                         r'\.lib\.display',
                                         # This isn't actually a module
                                         r'\.html\.tasks',
+                                        # This is private
+                                        r'\.html\.allow76'
                                         ]
 
     # These modules import functions and classes from other places to expose
     # them as part of the public API. They must have __all__ defined. The
     # non-API modules they import from should be excluded by the skip patterns
     # above.
     docwriter.names_from__all__.update({
-        'IPython.nbformat.current',
+        'IPython.nbformat',
+        'IPython.nbformat.v3',
+        'IPython.nbformat.v4',
         'IPython.display',
     })
     
     # Now, generate the outputs
     docwriter.write_api_docs(outdir)
     # Write index with .txt extension - we can include it, but Sphinx won't try
     # to compile it
     docwriter.write_index(outdir, 'gen.txt',
                           relative_to = pjoin('source','api')
                           )
     print ('%d files written' % len(docwriter.written_modules))