forked from ipython/ipython
/
__init__.py
163 lines (131 loc) · 4.56 KB
/
__init__.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
"""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.
import io
from IPython.utils import py3compat
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 or str
Any file-like object with a read method, or a path to a file.
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.
"""
if isinstance(fp, py3compat.string_types):
with io.open(fp, encoding='utf-8') as f:
return read(f, as_version, **kwargs)
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 or str
Any file-like object with a write method that accepts unicode, or
a path to write a file.
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.
"""
if isinstance(fp, py3compat.string_types):
with io.open(fp, 'w', encoding='utf-8') as f:
return write(nb, f, version=version, **kwargs)
s = writes(nb, version, **kwargs)
if isinstance(s, bytes):
s = s.decode('utf8')
fp.write(s)
if not s.endswith(u'\n'):
fp.write(u'\n')