Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/nbformat/v3/nbbase.py: 12%

1"""The basic dict based notebook format. 

2 

3The Python representation of a notebook is a nested structure of 

4dictionary subclasses that support attribute access. 

5The functions in this module are merely 

6helpers to build the structs in the right form. 

7""" 

8 

9# Copyright (c) IPython Development Team. 

10# Distributed under the terms of the Modified BSD License. 

11 

12import warnings 

13 

14from nbformat._struct import Struct 

15 

16# ----------------------------------------------------------------------------- 

17# Code 

18# ----------------------------------------------------------------------------- 

19 

20# Change this when incrementing the nbformat version 

21nbformat = 3 

22nbformat_minor = 0 

23nbformat_schema = {(3, 0): "nbformat.v3.schema.json"} 

24 

25 

26class NotebookNode(Struct): 

27 """A notebook node object.""" 

28 

29 pass 

30 

31 

32def from_dict(d): 

33 """Create notebook node(s) from an object.""" 

34 if isinstance(d, dict): 

35 newd = NotebookNode() 

36 for k, v in d.items(): 

37 newd[k] = from_dict(v) 

38 return newd 

39 elif isinstance(d, (tuple, list)): 

40 return [from_dict(i) for i in d] 

41 else: 

42 return d 

43 

44 

45def str_passthrough(obj): 

46 """ 

47 Used to be cast_unicode, add this temporarily to make sure no further breakage. 

48 """ 

49 if not isinstance(obj, str): 

50 raise AssertionError 

51 return obj 

52 

53 

54def cast_str(obj): 

55 """Cast an object as a string.""" 

56 if isinstance(obj, bytes): 

57 # really this should never happend, it should 

58 # have been base64 encoded before. 

59 warnings.warn( 

60 "A notebook got bytes instead of likely base64 encoded values." 

61 "The content will likely be corrupted.", 

62 UserWarning, 

63 stacklevel=3, 

64 ) 

65 return obj.decode("ascii", "replace") 

66 else: 

67 if not isinstance(obj, str): 

68 raise AssertionError 

69 return obj 

70 

71 

72def new_output( # noqa 

73 output_type, 

74 output_text=None, 

75 output_png=None, 

76 output_html=None, 

77 output_svg=None, 

78 output_latex=None, 

79 output_json=None, 

80 output_javascript=None, 

81 output_jpeg=None, 

82 prompt_number=None, 

83 ename=None, 

84 evalue=None, 

85 traceback=None, 

86 stream=None, 

87 metadata=None, 

88): 

89 """Create a new output, to go in the ``cell.outputs`` list of a code cell.""" 

90 output = NotebookNode() 

91 output.output_type = str(output_type) 

92 

93 if metadata is None: 

94 metadata = {} 

95 if not isinstance(metadata, dict): 

96 msg = "metadata must be dict" 

97 raise TypeError(msg) 

98 

99 if output_type in {"pyout", "display_data"}: 

100 output.metadata = metadata 

101 

102 if output_type != "pyerr": 

103 if output_text is not None: 

104 output.text = str_passthrough(output_text) 

105 if output_png is not None: 

106 output.png = cast_str(output_png) 

107 if output_jpeg is not None: 

108 output.jpeg = cast_str(output_jpeg) 

109 if output_html is not None: 

110 output.html = str_passthrough(output_html) 

111 if output_svg is not None: 

112 output.svg = str_passthrough(output_svg) 

113 if output_latex is not None: 

114 output.latex = str_passthrough(output_latex) 

115 if output_json is not None: 

116 output.json = str_passthrough(output_json) 

117 if output_javascript is not None: 

118 output.javascript = str_passthrough(output_javascript) 

119 

120 if output_type == "pyout" and prompt_number is not None: 

121 output.prompt_number = int(prompt_number) 

122 

123 if output_type == "pyerr": 

124 if ename is not None: 

125 output.ename = str_passthrough(ename) 

126 if evalue is not None: 

127 output.evalue = str_passthrough(evalue) 

128 if traceback is not None: 

129 output.traceback = [str_passthrough(frame) for frame in list(traceback)] 

130 

131 if output_type == "stream": 

132 output.stream = "stdout" if stream is None else str_passthrough(stream) 

133 

134 return output 

135 

136 

137def new_code_cell( 

138 input=None, # noqa 

139 prompt_number=None, 

140 outputs=None, 

141 language="python", 

142 collapsed=False, 

143 metadata=None, 

144): 

145 """Create a new code cell with input and output""" 

146 cell = NotebookNode() 

147 cell.cell_type = "code" 

148 if language is not None: 

149 cell.language = str_passthrough(language) 

150 if input is not None: 

151 cell.input = str_passthrough(input) 

152 if prompt_number is not None: 

153 cell.prompt_number = int(prompt_number) 

154 if outputs is None: 

155 cell.outputs = [] 

156 else: 

157 cell.outputs = outputs 

158 if collapsed is not None: 

159 cell.collapsed = bool(collapsed) 

160 cell.metadata = NotebookNode(metadata or {}) 

161 

162 return cell 

163 

164 

165def new_text_cell(cell_type, source=None, rendered=None, metadata=None): 

166 """Create a new text cell.""" 

167 cell = NotebookNode() 

168 # VERSIONHACK: plaintext -> raw 

169 # handle never-released plaintext name for raw cells 

170 if cell_type == "plaintext": 

171 cell_type = "raw" 

172 if source is not None: 

173 cell.source = str_passthrough(source) 

174 cell.metadata = NotebookNode(metadata or {}) 

175 cell.cell_type = cell_type 

176 return cell 

177 

178 

179def new_heading_cell(source=None, level=1, rendered=None, metadata=None): 

180 """Create a new section cell with a given integer level.""" 

181 cell = NotebookNode() 

182 cell.cell_type = "heading" 

183 if source is not None: 

184 cell.source = str_passthrough(source) 

185 cell.level = int(level) 

186 cell.metadata = NotebookNode(metadata or {}) 

187 return cell 

188 

189 

190def new_worksheet(name=None, cells=None, metadata=None): 

191 """Create a worksheet by name with with a list of cells.""" 

192 ws = NotebookNode() 

193 if cells is None: 

194 ws.cells = [] 

195 else: 

196 ws.cells = list(cells) 

197 ws.metadata = NotebookNode(metadata or {}) 

198 return ws 

199 

200 

201def new_notebook(name=None, metadata=None, worksheets=None): 

202 """Create a notebook by name, id and a list of worksheets.""" 

203 nb = NotebookNode() 

204 nb.nbformat = nbformat 

205 nb.nbformat_minor = nbformat_minor 

206 if worksheets is None: 

207 nb.worksheets = [] 

208 else: 

209 nb.worksheets = list(worksheets) 

210 if metadata is None: 

211 nb.metadata = new_metadata() 

212 else: 

213 nb.metadata = NotebookNode(metadata) 

214 if name is not None: 

215 nb.metadata.name = str_passthrough(name) 

216 return nb 

217 

218 

219def new_metadata( 

220 name=None, authors=None, license=None, created=None, modified=None, gistid=None # noqa 

221): 

222 """Create a new metadata node.""" 

223 metadata = NotebookNode() 

224 if name is not None: 

225 metadata.name = str_passthrough(name) 

226 if authors is not None: 

227 metadata.authors = list(authors) 

228 if created is not None: 

229 metadata.created = str_passthrough(created) 

230 if modified is not None: 

231 metadata.modified = str_passthrough(modified) 

232 if license is not None: 

233 metadata.license = str_passthrough(license) 

234 if gistid is not None: 

235 metadata.gistid = str_passthrough(gistid) 

236 return metadata 

237 

238 

239def new_author(name=None, email=None, affiliation=None, url=None): 

240 """Create a new author.""" 

241 author = NotebookNode() 

242 if name is not None: 

243 author.name = str_passthrough(name) 

244 if email is not None: 

245 author.email = str_passthrough(email) 

246 if affiliation is not None: 

247 author.affiliation = str_passthrough(affiliation) 

248 if url is not None: 

249 author.url = str_passthrough(url) 

250 return author