##// END OF EJS Templates
add 'upload' arg to release script...
add 'upload' arg to release script so it can be used as a dry-run

File last commit:

r19272:09d89eea
r19848:da1fb354
Show More
__init__.py
161 lines | 4.5 KiB | text/x-python | PythonLexer
MinRK
Add top-level IPython.nbformat API...
r18603 """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.
Thomas Kluyver
Make nbformat.(read|write) accept file-like object or path
r19270 import io
from IPython.utils import py3compat
MinRK
Add top-level IPython.nbformat API...
r18603
from IPython.utils.log import get_logger
from . import v1
from . import v2
from . import v3
from . import v4
Thomas Kluyver
API docs gardening
r19043 __all__ = ['versions', 'validate', 'ValidationError', 'convert', 'from_dict',
'NotebookNode', 'current_nbformat', 'current_nbformat_minor',
'NBFormatError', 'NO_CONVERT', 'reads', 'read', 'writes', 'write']
MinRK
Add top-level IPython.nbformat API...
r18603 versions = {
1: v1,
2: v2,
3: v3,
4: v4,
}
from .validator import validate, ValidationError
from .converter import convert
from . import reader
MinRK
move NotebookNode to top-level...
r18606 from .notebooknode import from_dict, NotebookNode
MinRK
Add top-level IPython.nbformat API...
r18603
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
MinRK
default to NO_CONVERT in nbformat.writes
r18611 def writes(nb, version=NO_CONVERT, **kwargs):
MinRK
Add top-level IPython.nbformat API...
r18603 """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.
MinRK
default to NO_CONVERT in nbformat.writes
r18611 version : int, optional
MinRK
Add top-level IPython.nbformat API...
r18603 The nbformat version to write.
MinRK
default to NO_CONVERT in nbformat.writes
r18611 If unspecified, or specified as nbformat.NO_CONVERT,
the notebook's own version will be used and no conversion performed.
MinRK
Add top-level IPython.nbformat API...
r18603
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
----------
Thomas Kluyver
Make nbformat.(read|write) accept file-like object or path
r19270 fp : file or str
Any file-like object with a read method, or a path to a file.
MinRK
Add top-level IPython.nbformat API...
r18603 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.
"""
Thomas Kluyver
Make nbformat.(read|write) accept file-like object or path
r19270 if isinstance(fp, py3compat.string_types):
with io.open(fp, encoding='utf-8') as f:
return read(f, as_version, **kwargs)
MinRK
Add top-level IPython.nbformat API...
r18603 return reads(fp.read(), as_version, **kwargs)
Min RK
fix backward `f, nb` args for nbformat.write
r18613 def write(nb, fp, version=NO_CONVERT, **kwargs):
MinRK
Add top-level IPython.nbformat API...
r18603 """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.
Thomas Kluyver
Make nbformat.(read|write) accept file-like object or path
r19270 fp : file or str
Any file-like object with a write method that accepts unicode, or
a path to write a file.
MinRK
default to NO_CONVERT in nbformat.writes
r18611 version : int, optional
MinRK
Add top-level IPython.nbformat API...
r18603 The nbformat version to write.
If nb is not this version, it will be converted.
MinRK
default to NO_CONVERT in nbformat.writes
r18611 If unspecified, or specified as nbformat.NO_CONVERT,
the notebook's own version will be used and no conversion performed.
MinRK
Add top-level IPython.nbformat API...
r18603 """
Thomas Kluyver
Make nbformat.(read|write) accept file-like object or path
r19270 if isinstance(fp, py3compat.string_types):
Thomas Kluyver
Fix opening file on Python 2
r19272 with io.open(fp, 'w', encoding='utf-8') as f:
Thomas Kluyver
Make nbformat.(read|write) accept file-like object or path
r19270 return write(nb, f, version=version, **kwargs)
MinRK
Add top-level IPython.nbformat API...
r18603 s = writes(nb, version, **kwargs)
if isinstance(s, bytes):
s = s.decode('utf8')
return fp.write(s)