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