##// END OF EJS Templates
Simplify
Jonathan Frederic -
Show More
@@ -1,321 +1,323 b''
1 #!/usr/bin/env python
1 #!/usr/bin/env python
2 """NBConvert is a utility for conversion of .ipynb files.
2 """NBConvert is a utility for conversion of .ipynb files.
3
3
4 Command-line interface for the NbConvert conversion utility.
4 Command-line interface for the NbConvert conversion utility.
5 """
5 """
6 #-----------------------------------------------------------------------------
6 #-----------------------------------------------------------------------------
7 #Copyright (c) 2013, the IPython Development Team.
7 #Copyright (c) 2013, the IPython Development Team.
8 #
8 #
9 #Distributed under the terms of the Modified BSD License.
9 #Distributed under the terms of the Modified BSD License.
10 #
10 #
11 #The full license is in the file COPYING.txt, distributed with this software.
11 #The full license is in the file COPYING.txt, distributed with this software.
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13
13
14 #-----------------------------------------------------------------------------
14 #-----------------------------------------------------------------------------
15 #Imports
15 #Imports
16 #-----------------------------------------------------------------------------
16 #-----------------------------------------------------------------------------
17
17
18 # Stdlib imports
18 # Stdlib imports
19 from __future__ import print_function
19 from __future__ import print_function
20
20
21 import logging
21 import logging
22 import sys
22 import sys
23 import os
23 import os
24 import glob
24 import glob
25
25
26 # From IPython
26 # From IPython
27 from IPython.core.application import BaseIPythonApplication, base_aliases, base_flags
27 from IPython.core.application import BaseIPythonApplication, base_aliases, base_flags
28 from IPython.config import catch_config_error, Configurable
28 from IPython.config import catch_config_error, Configurable
29 from IPython.utils.traitlets import (
29 from IPython.utils.traitlets import (
30 Unicode, List, Instance, DottedObjectName, Type, CaselessStrEnum,
30 Unicode, List, Instance, DottedObjectName, Type, CaselessStrEnum,
31 )
31 )
32 from IPython.utils.importstring import import_item
32 from IPython.utils.importstring import import_item
33 from IPython.utils.text import dedent
33 from IPython.utils.text import dedent
34
34
35 from .exporters.export import get_export_names, exporter_map
35 from .exporters.export import get_export_names, exporter_map
36 from IPython.nbconvert import exporters, transformers, writers, post_processors
36 from IPython.nbconvert import exporters, transformers, writers, post_processors
37 from .utils.base import NbConvertBase
37 from .utils.base import NbConvertBase
38 from .utils.exceptions import ConversionException
38 from .utils.exceptions import ConversionException
39
39
40 #-----------------------------------------------------------------------------
40 #-----------------------------------------------------------------------------
41 #Classes and functions
41 #Classes and functions
42 #-----------------------------------------------------------------------------
42 #-----------------------------------------------------------------------------
43
43
44 class DottedOrNone(DottedObjectName):
44 class DottedOrNone(DottedObjectName):
45 """
45 """
46 A string holding a valid dotted object name in Python, such as A.b3._c
46 A string holding a valid dotted object name in Python, such as A.b3._c
47 Also allows for None type."""
47 Also allows for None type."""
48
48
49 default_value = u''
49 default_value = u''
50
50
51 def validate(self, obj, value):
51 def validate(self, obj, value):
52 if value is not None and len(value) > 0:
52 if value is not None and len(value) > 0:
53 return super(DottedOrNone, self).validate(obj, value)
53 return super(DottedOrNone, self).validate(obj, value)
54 else:
54 else:
55 return value
55 return value
56
56
57 nbconvert_aliases = {}
57 nbconvert_aliases = {}
58 nbconvert_aliases.update(base_aliases)
58 nbconvert_aliases.update(base_aliases)
59 nbconvert_aliases.update({
59 nbconvert_aliases.update({
60 'to' : 'NbConvertApp.export_format',
60 'to' : 'NbConvertApp.export_format',
61 'template' : 'Exporter.template_file',
61 'template' : 'Exporter.template_file',
62 'notebooks' : 'NbConvertApp.notebooks',
62 'notebooks' : 'NbConvertApp.notebooks',
63 'writer' : 'NbConvertApp.writer_class',
63 'writer' : 'NbConvertApp.writer_class',
64 'post': 'NbConvertApp.post_processor_class',
64 'post': 'NbConvertApp.post_processor_class',
65 'output': 'NbConvertApp.output_base'
65 'output': 'NbConvertApp.output_base'
66 })
66 })
67
67
68 nbconvert_flags = {}
68 nbconvert_flags = {}
69 nbconvert_flags.update(base_flags)
69 nbconvert_flags.update(base_flags)
70 nbconvert_flags.update({
70 nbconvert_flags.update({
71 'stdout' : (
71 'stdout' : (
72 {'NbConvertApp' : {'writer_class' : "StdoutWriter"}},
72 {'NbConvertApp' : {'writer_class' : "StdoutWriter"}},
73 "Write notebook output to stdout instead of files."
73 "Write notebook output to stdout instead of files."
74 )
74 )
75 })
75 })
76
76
77
77
78 class NbConvertApp(BaseIPythonApplication):
78 class NbConvertApp(BaseIPythonApplication):
79 """Application used to convert to and from notebook file type (*.ipynb)"""
79 """Application used to convert to and from notebook file type (*.ipynb)"""
80
80
81 name = 'ipython-nbconvert'
81 name = 'ipython-nbconvert'
82 aliases = nbconvert_aliases
82 aliases = nbconvert_aliases
83 flags = nbconvert_flags
83 flags = nbconvert_flags
84
84
85 def _log_level_default(self):
85 def _log_level_default(self):
86 return logging.INFO
86 return logging.INFO
87
87
88 def _classes_default(self):
88 def _classes_default(self):
89 classes = [NbConvertBase]
89 classes = [NbConvertBase]
90 for pkg in (exporters, transformers, writers):
90 for pkg in (exporters, transformers, writers):
91 for name in dir(pkg):
91 for name in dir(pkg):
92 cls = getattr(pkg, name)
92 cls = getattr(pkg, name)
93 if isinstance(cls, type) and issubclass(cls, Configurable):
93 if isinstance(cls, type) and issubclass(cls, Configurable):
94 classes.append(cls)
94 classes.append(cls)
95 return classes
95 return classes
96
96
97 description = Unicode(
97 description = Unicode(
98 u"""This application is used to convert notebook files (*.ipynb)
98 u"""This application is used to convert notebook files (*.ipynb)
99 to various other formats.
99 to various other formats.
100
100
101 WARNING: THE COMMANDLINE INTERFACE MAY CHANGE IN FUTURE RELEASES.""")
101 WARNING: THE COMMANDLINE INTERFACE MAY CHANGE IN FUTURE RELEASES.""")
102
102
103 output_base = Unicode('', config=True, help='''overwrite base name use for output files.
103 output_base = Unicode('', config=True, help='''overwrite base name use for output files.
104 can only be use when converting one notebook at a time.
104 can only be use when converting one notebook at a time.
105 ''')
105 ''')
106
106
107 examples = Unicode(u"""
107 examples = Unicode(u"""
108 The simplest way to use nbconvert is
108 The simplest way to use nbconvert is
109
109
110 > ipython nbconvert mynotebook.ipynb
110 > ipython nbconvert mynotebook.ipynb
111
111
112 which will convert mynotebook.ipynb to the default format (probably HTML).
112 which will convert mynotebook.ipynb to the default format (probably HTML).
113
113
114 You can specify the export format with `--to`.
114 You can specify the export format with `--to`.
115 Options include {0}
115 Options include {0}
116
116
117 > ipython nbconvert --to latex mynotebook.ipnynb
117 > ipython nbconvert --to latex mynotebook.ipnynb
118
118
119 Both HTML and LaTeX support multiple output templates. LaTeX includes
119 Both HTML and LaTeX support multiple output templates. LaTeX includes
120 'basic', 'book', and 'article'. HTML includes 'basic' and 'full'. You
120 'basic', 'book', and 'article'. HTML includes 'basic' and 'full'. You
121 can specify the flavor of the format used.
121 can specify the flavor of the format used.
122
122
123 > ipython nbconvert --to html --template basic mynotebook.ipynb
123 > ipython nbconvert --to html --template basic mynotebook.ipynb
124
124
125 You can also pipe the output to stdout, rather than a file
125 You can also pipe the output to stdout, rather than a file
126
126
127 > ipython nbconvert mynotebook.ipynb --stdout
127 > ipython nbconvert mynotebook.ipynb --stdout
128
128
129 A post-processor can be used to compile a PDF
129 A post-processor can be used to compile a PDF
130
130
131 > ipython nbconvert mynotebook.ipynb --to latex --post PDF
131 > ipython nbconvert mynotebook.ipynb --to latex --post PDF
132
132
133 You can get (and serve) a Reveal.js-powered slideshow
133 You can get (and serve) a Reveal.js-powered slideshow
134
134
135 > ipython nbconvert myslides.ipynb --to slides --post serve
135 > ipython nbconvert myslides.ipynb --to slides --post serve
136
136
137 Multiple notebooks can be given at the command line in a couple of
137 Multiple notebooks can be given at the command line in a couple of
138 different ways:
138 different ways:
139
139
140 > ipython nbconvert notebook*.ipynb
140 > ipython nbconvert notebook*.ipynb
141 > ipython nbconvert notebook1.ipynb notebook2.ipynb
141 > ipython nbconvert notebook1.ipynb notebook2.ipynb
142
142
143 or you can specify the notebooks list in a config file, containing::
143 or you can specify the notebooks list in a config file, containing::
144
144
145 c.NbConvertApp.notebooks = ["my_notebook.ipynb"]
145 c.NbConvertApp.notebooks = ["my_notebook.ipynb"]
146
146
147 > ipython nbconvert --config mycfg.py
147 > ipython nbconvert --config mycfg.py
148 """.format(get_export_names()))
148 """.format(get_export_names()))
149
149
150 # Writer specific variables
150 # Writer specific variables
151 writer = Instance('IPython.nbconvert.writers.base.WriterBase',
151 writer = Instance('IPython.nbconvert.writers.base.WriterBase',
152 help="""Instance of the writer class used to write the
152 help="""Instance of the writer class used to write the
153 results of the conversion.""")
153 results of the conversion.""")
154 writer_class = DottedObjectName('FilesWriter', config=True,
154 writer_class = DottedObjectName('FilesWriter', config=True,
155 help="""Writer class used to write the
155 help="""Writer class used to write the
156 results of the conversion""")
156 results of the conversion""")
157 writer_aliases = {'fileswriter': 'IPython.nbconvert.writers.files.FilesWriter',
157 writer_aliases = {'fileswriter': 'IPython.nbconvert.writers.files.FilesWriter',
158 'debugwriter': 'IPython.nbconvert.writers.debug.DebugWriter',
158 'debugwriter': 'IPython.nbconvert.writers.debug.DebugWriter',
159 'stdoutwriter': 'IPython.nbconvert.writers.stdout.StdoutWriter'}
159 'stdoutwriter': 'IPython.nbconvert.writers.stdout.StdoutWriter'}
160 writer_factory = Type()
160 writer_factory = Type()
161
161
162 def _writer_class_changed(self, name, old, new):
162 def _writer_class_changed(self, name, old, new):
163 if new.lower() in self.writer_aliases:
163 new = new.lower()
164 new = self.writer_aliases[new.lower()]
164 if new in self.writer_aliases:
165 new = self.writer_aliases[new]
165 self.writer_factory = import_item(new)
166 self.writer_factory = import_item(new)
166
167
167 # Post-processor specific variables
168 # Post-processor specific variables
168 post_processor = Instance('IPython.nbconvert.post_processors.base.PostProcessorBase',
169 post_processor = Instance('IPython.nbconvert.post_processors.base.PostProcessorBase',
169 help="""Instance of the PostProcessor class used to write the
170 help="""Instance of the PostProcessor class used to write the
170 results of the conversion.""")
171 results of the conversion.""")
171
172
172 post_processor_class = DottedOrNone(config=True,
173 post_processor_class = DottedOrNone(config=True,
173 help="""PostProcessor class used to write the
174 help="""PostProcessor class used to write the
174 results of the conversion""")
175 results of the conversion""")
175 post_processor_aliases = {'pdf': 'IPython.nbconvert.post_processors.pdf.PDFPostProcessor',
176 post_processor_aliases = {'pdf': 'IPython.nbconvert.post_processors.pdf.PDFPostProcessor',
176 'serve': 'IPython.nbconvert.post_processors.serve.ServePostProcessor'}
177 'serve': 'IPython.nbconvert.post_processors.serve.ServePostProcessor'}
177 post_processor_factory = Type()
178 post_processor_factory = Type()
178
179
179 def _post_processor_class_changed(self, name, old, new):
180 def _post_processor_class_changed(self, name, old, new):
180 if new.lower() in self.post_processor_aliases:
181 new = new.lower()
181 new = self.post_processor_aliases[new.lower()]
182 if new in self.post_processor_aliases:
183 new = self.post_processor_aliases[new]
182 if new:
184 if new:
183 self.post_processor_factory = import_item(new)
185 self.post_processor_factory = import_item(new)
184
186
185
187
186 # Other configurable variables
188 # Other configurable variables
187 export_format = CaselessStrEnum(get_export_names(),
189 export_format = CaselessStrEnum(get_export_names(),
188 default_value="html",
190 default_value="html",
189 config=True,
191 config=True,
190 help="""The export format to be used."""
192 help="""The export format to be used."""
191 )
193 )
192
194
193 notebooks = List([], config=True, help="""List of notebooks to convert.
195 notebooks = List([], config=True, help="""List of notebooks to convert.
194 Wildcards are supported.
196 Wildcards are supported.
195 Filenames passed positionally will be added to the list.
197 Filenames passed positionally will be added to the list.
196 """)
198 """)
197
199
198 @catch_config_error
200 @catch_config_error
199 def initialize(self, argv=None):
201 def initialize(self, argv=None):
200 super(NbConvertApp, self).initialize(argv)
202 super(NbConvertApp, self).initialize(argv)
201 self.init_syspath()
203 self.init_syspath()
202 self.init_notebooks()
204 self.init_notebooks()
203 self.init_writer()
205 self.init_writer()
204 self.init_post_processor()
206 self.init_post_processor()
205
207
206
208
207
209
208 def init_syspath(self):
210 def init_syspath(self):
209 """
211 """
210 Add the cwd to the sys.path ($PYTHONPATH)
212 Add the cwd to the sys.path ($PYTHONPATH)
211 """
213 """
212 sys.path.insert(0, os.getcwd())
214 sys.path.insert(0, os.getcwd())
213
215
214
216
215 def init_notebooks(self):
217 def init_notebooks(self):
216 """Construct the list of notebooks.
218 """Construct the list of notebooks.
217 If notebooks are passed on the command-line,
219 If notebooks are passed on the command-line,
218 they override notebooks specified in config files.
220 they override notebooks specified in config files.
219 Glob each notebook to replace notebook patterns with filenames.
221 Glob each notebook to replace notebook patterns with filenames.
220 """
222 """
221
223
222 # Specifying notebooks on the command-line overrides (rather than adds)
224 # Specifying notebooks on the command-line overrides (rather than adds)
223 # the notebook list
225 # the notebook list
224 if self.extra_args:
226 if self.extra_args:
225 patterns = self.extra_args
227 patterns = self.extra_args
226 else:
228 else:
227 patterns = self.notebooks
229 patterns = self.notebooks
228
230
229 # Use glob to replace all the notebook patterns with filenames.
231 # Use glob to replace all the notebook patterns with filenames.
230 filenames = []
232 filenames = []
231 for pattern in patterns:
233 for pattern in patterns:
232
234
233 # Use glob to find matching filenames. Allow the user to convert
235 # Use glob to find matching filenames. Allow the user to convert
234 # notebooks without having to type the extension.
236 # notebooks without having to type the extension.
235 globbed_files = glob.glob(pattern)
237 globbed_files = glob.glob(pattern)
236 globbed_files.extend(glob.glob(pattern + '.ipynb'))
238 globbed_files.extend(glob.glob(pattern + '.ipynb'))
237 if not globbed_files:
239 if not globbed_files:
238 self.log.warn("pattern %r matched no files", pattern)
240 self.log.warn("pattern %r matched no files", pattern)
239
241
240 for filename in globbed_files:
242 for filename in globbed_files:
241 if not filename in filenames:
243 if not filename in filenames:
242 filenames.append(filename)
244 filenames.append(filename)
243 self.notebooks = filenames
245 self.notebooks = filenames
244
246
245 def init_writer(self):
247 def init_writer(self):
246 """
248 """
247 Initialize the writer (which is stateless)
249 Initialize the writer (which is stateless)
248 """
250 """
249 self._writer_class_changed(None, self.writer_class, self.writer_class)
251 self._writer_class_changed(None, self.writer_class, self.writer_class)
250 self.writer = self.writer_factory(parent=self)
252 self.writer = self.writer_factory(parent=self)
251
253
252 def init_post_processor(self):
254 def init_post_processor(self):
253 """
255 """
254 Initialize the post_processor (which is stateless)
256 Initialize the post_processor (which is stateless)
255 """
257 """
256 self._post_processor_class_changed(None, self.post_processor_class,
258 self._post_processor_class_changed(None, self.post_processor_class,
257 self.post_processor_class)
259 self.post_processor_class)
258 if self.post_processor_factory:
260 if self.post_processor_factory:
259 self.post_processor = self.post_processor_factory(parent=self)
261 self.post_processor = self.post_processor_factory(parent=self)
260
262
261 def start(self):
263 def start(self):
262 """
264 """
263 Ran after initialization completed
265 Ran after initialization completed
264 """
266 """
265 super(NbConvertApp, self).start()
267 super(NbConvertApp, self).start()
266 self.convert_notebooks()
268 self.convert_notebooks()
267
269
268 def convert_notebooks(self):
270 def convert_notebooks(self):
269 """
271 """
270 Convert the notebooks in the self.notebook traitlet
272 Convert the notebooks in the self.notebook traitlet
271 """
273 """
272 # Export each notebook
274 # Export each notebook
273 conversion_success = 0
275 conversion_success = 0
274
276
275 if self.output_base != '' and len(self.notebooks) > 1:
277 if self.output_base != '' and len(self.notebooks) > 1:
276 self.log.error(
278 self.log.error(
277 """UsageError: --output flag or `NbConvertApp.output_base` config option
279 """UsageError: --output flag or `NbConvertApp.output_base` config option
278 cannot be used when converting multiple notebooks.
280 cannot be used when converting multiple notebooks.
279 """)
281 """)
280 self.exit(1)
282 self.exit(1)
281
283
282 exporter = exporter_map[self.export_format](config=self.config)
284 exporter = exporter_map[self.export_format](config=self.config)
283
285
284 for notebook_filename in self.notebooks:
286 for notebook_filename in self.notebooks:
285 self.log.info("Converting notebook %s to %s", notebook_filename, self.export_format)
287 self.log.info("Converting notebook %s to %s", notebook_filename, self.export_format)
286
288
287 # Get a unique key for the notebook and set it in the resources object.
289 # Get a unique key for the notebook and set it in the resources object.
288 basename = os.path.basename(notebook_filename)
290 basename = os.path.basename(notebook_filename)
289 notebook_name = basename[:basename.rfind('.')]
291 notebook_name = basename[:basename.rfind('.')]
290 if self.output_base:
292 if self.output_base:
291 notebook_name = self.output_base
293 notebook_name = self.output_base
292 resources = {}
294 resources = {}
293 resources['unique_key'] = notebook_name
295 resources['unique_key'] = notebook_name
294 resources['output_files_dir'] = '%s_files' % notebook_name
296 resources['output_files_dir'] = '%s_files' % notebook_name
295 self.log.info("Support files will be in %s", os.path.join(resources['output_files_dir'], ''))
297 self.log.info("Support files will be in %s", os.path.join(resources['output_files_dir'], ''))
296
298
297 # Try to export
299 # Try to export
298 try:
300 try:
299 output, resources = exporter.from_filename(notebook_filename, resources=resources)
301 output, resources = exporter.from_filename(notebook_filename, resources=resources)
300 except ConversionException as e:
302 except ConversionException as e:
301 self.log.error("Error while converting '%s'", notebook_filename,
303 self.log.error("Error while converting '%s'", notebook_filename,
302 exc_info=True)
304 exc_info=True)
303 self.exit(1)
305 self.exit(1)
304 else:
306 else:
305 write_resultes = self.writer.write(output, resources, notebook_name=notebook_name)
307 write_resultes = self.writer.write(output, resources, notebook_name=notebook_name)
306
308
307 #Post-process if post processor has been defined.
309 #Post-process if post processor has been defined.
308 if hasattr(self, 'post_processor') and self.post_processor:
310 if hasattr(self, 'post_processor') and self.post_processor:
309 self.post_processor(write_resultes)
311 self.post_processor(write_resultes)
310 conversion_success += 1
312 conversion_success += 1
311
313
312 # If nothing was converted successfully, help the user.
314 # If nothing was converted successfully, help the user.
313 if conversion_success == 0:
315 if conversion_success == 0:
314 self.print_help()
316 self.print_help()
315 sys.exit(-1)
317 sys.exit(-1)
316
318
317 #-----------------------------------------------------------------------------
319 #-----------------------------------------------------------------------------
318 # Main entry point
320 # Main entry point
319 #-----------------------------------------------------------------------------
321 #-----------------------------------------------------------------------------
320
322
321 launch_new_instance = NbConvertApp.launch_instance
323 launch_new_instance = NbConvertApp.launch_instance
General Comments 0
You need to be logged in to leave comments. Login now