nbconvertapp.py
321 lines
| 11.8 KiB
| text/x-python
|
PythonLexer
Brian E. Granger
|
r11087 | #!/usr/bin/env python | ||
MinRK
|
r11448 | """NBConvert is a utility for conversion of .ipynb files. | ||
Brian E. Granger
|
r11087 | |||
MinRK
|
r11448 | Command-line interface for the NbConvert conversion utility. | ||
Brian E. Granger
|
r11087 | """ | ||
#----------------------------------------------------------------------------- | ||||
#Copyright (c) 2013, the IPython Development Team. | ||||
# | ||||
#Distributed under the terms of the Modified BSD License. | ||||
# | ||||
#The full license is in the file COPYING.txt, distributed with this software. | ||||
#----------------------------------------------------------------------------- | ||||
#----------------------------------------------------------------------------- | ||||
#Imports | ||||
#----------------------------------------------------------------------------- | ||||
Jonathan Frederic
|
r11632 | # Stdlib imports | ||
Brian E. Granger
|
r11087 | from __future__ import print_function | ||
import sys | ||||
import os | ||||
Jonathan Frederic
|
r11367 | import glob | ||
Brian E. Granger
|
r11087 | |||
Jonathan Frederic
|
r11632 | # From IPython | ||
MinRK
|
r11448 | from IPython.core.application import BaseIPythonApplication, base_aliases, base_flags | ||
MinRK
|
r11453 | from IPython.config import catch_config_error, Configurable | ||
MinRK
|
r11454 | from IPython.utils.traitlets import ( | ||
Unicode, List, Instance, DottedObjectName, Type, CaselessStrEnum, | ||||
) | ||||
Jonathan Frederic
|
r11367 | from IPython.utils.importstring import import_item | ||
Matthias BUSSONNIER
|
r11801 | from IPython.utils.text import dedent | ||
Brian E. Granger
|
r11087 | |||
MinRK
|
r11453 | from .exporters.export import export_by_name, get_export_names, ExporterNameError | ||
Jonathan Frederic
|
r11747 | from IPython.nbconvert import exporters, transformers, writers, post_processors | ||
Jonathan Frederic
|
r11420 | from .utils.base import NbConvertBase | ||
David Wolever
|
r11703 | from .utils.exceptions import ConversionException | ||
Brian E. Granger
|
r11087 | |||
#----------------------------------------------------------------------------- | ||||
Jonathan Frederic
|
r11367 | #Classes and functions | ||
Brian E. Granger
|
r11087 | #----------------------------------------------------------------------------- | ||
Jonathan Frederic
|
r11747 | class DottedOrNone(DottedObjectName): | ||
""" | ||||
A string holding a valid dotted object name in Python, such as A.b3._c | ||||
Also allows for None type.""" | ||||
default_value = u'' | ||||
def validate(self, obj, value): | ||||
if value is not None and len(value) > 0: | ||||
return super(DottedOrNone, self).validate(obj, value) | ||||
else: | ||||
return value | ||||
MinRK
|
r11448 | nbconvert_aliases = {} | ||
nbconvert_aliases.update(base_aliases) | ||||
nbconvert_aliases.update({ | ||||
Jonathan Frederic
|
r11735 | 'to' : 'NbConvertApp.export_format', | ||
'template' : 'Exporter.template_file', | ||||
MinRK
|
r11448 | 'notebooks' : 'NbConvertApp.notebooks', | ||
'writer' : 'NbConvertApp.writer_class', | ||||
Matthias BUSSONNIER
|
r11801 | 'post': 'NbConvertApp.post_processor_class', | ||
'output': 'NbConvertApp.output_base' | ||||
MinRK
|
r11448 | }) | ||
nbconvert_flags = {} | ||||
nbconvert_flags.update(base_flags) | ||||
nbconvert_flags.update({ | ||||
'stdout' : ( | ||||
{'NbConvertApp' : {'writer_class' : "StdoutWriter"}}, | ||||
"Write notebook output to stdout instead of files." | ||||
) | ||||
}) | ||||
Jonathan Frederic
|
r11367 | class NbConvertApp(BaseIPythonApplication): | ||
"""Application used to convert to and from notebook file type (*.ipynb)""" | ||||
Brian E. Granger
|
r11087 | |||
Jonathan Frederic
|
r11406 | name = 'ipython-nbconvert' | ||
MinRK
|
r11448 | aliases = nbconvert_aliases | ||
flags = nbconvert_flags | ||||
def _classes_default(self): | ||||
MinRK
|
r11453 | classes = [NbConvertBase] | ||
for pkg in (exporters, transformers, writers): | ||||
for name in dir(pkg): | ||||
cls = getattr(pkg, name) | ||||
if isinstance(cls, type) and issubclass(cls, Configurable): | ||||
classes.append(cls) | ||||
return classes | ||||
Paul Ivanov
|
r11248 | |||
Jonathan Frederic
|
r11367 | description = Unicode( | ||
MinRK
|
r11454 | u"""This application is used to convert notebook files (*.ipynb) | ||
Jonathan Frederic
|
r11755 | to various other formats. | ||
WARNING: THE COMMANDLINE INTERFACE MAY CHANGE IN FUTURE RELEASES.""") | ||||
Paul Ivanov
|
r11251 | |||
Matthias BUSSONNIER
|
r11801 | output_base = Unicode('', config=True, help='''overwrite base name use for output files. | ||
can only be use when converting one notebook at a time. | ||||
''') | ||||
Jonathan Frederic
|
r11367 | examples = Unicode(u""" | ||
MinRK
|
r11454 | The simplest way to use nbconvert is | ||
> ipython nbconvert mynotebook.ipynb | ||||
which will convert mynotebook.ipynb to the default format (probably HTML). | ||||
Jonathan Frederic
|
r11741 | You can specify the export format with `--to`. | ||
MinRK
|
r11454 | Options include {0} | ||
Jonathan Frederic
|
r11741 | > ipython nbconvert --to latex mynotebook.ipnynb | ||
Jonathan Frederic
|
r11745 | Both HTML and LaTeX support multiple output templates. LaTeX includes | ||
Jonathan Frederic
|
r11744 | 'basic', 'book', and 'article'. HTML includes 'basic' and 'full'. You | ||
can specify the flavor of the format used. | ||||
Jonathan Frederic
|
r11741 | |||
Jonathan Frederic
|
r11761 | > ipython nbconvert --to html --template basic mynotebook.ipynb | ||
MinRK
|
r11454 | |||
You can also pipe the output to stdout, rather than a file | ||||
> ipython nbconvert mynotebook.ipynb --stdout | ||||
Jonathan Frederic
|
r11742 | |||
Jonathan Frederic
|
r11748 | A post-processor can be used to compile a PDF | ||
Jonathan Frederic
|
r11742 | |||
Jonathan Frederic
|
r11748 | > ipython nbconvert mynotebook.ipynb --to latex --post PDF | ||
MinRK
|
r11454 | |||
damianavila
|
r11776 | You can get (and serve) a Reveal.js-powered slideshow | ||
> ipython nbconvert myslides.ipynb --to slides --post serve | ||||
Jonathan Frederic
|
r11367 | Multiple notebooks can be given at the command line in a couple of | ||
different ways: | ||||
> ipython nbconvert notebook*.ipynb | ||||
> ipython nbconvert notebook1.ipynb notebook2.ipynb | ||||
MinRK
|
r11469 | |||
or you can specify the notebooks list in a config file, containing:: | ||||
c.NbConvertApp.notebooks = ["my_notebook.ipynb"] | ||||
> ipython nbconvert --config mycfg.py | ||||
MinRK
|
r11454 | """.format(get_export_names())) | ||
Jonathan Frederic
|
r11747 | |||
Jonathan Frederic
|
r11632 | # Writer specific variables | ||
Jonathan Frederic
|
r11367 | writer = Instance('IPython.nbconvert.writers.base.WriterBase', | ||
help="""Instance of the writer class used to write the | ||||
results of the conversion.""") | ||||
writer_class = DottedObjectName('FilesWriter', config=True, | ||||
help="""Writer class used to write the | ||||
results of the conversion""") | ||||
writer_aliases = {'FilesWriter': 'IPython.nbconvert.writers.files.FilesWriter', | ||||
'DebugWriter': 'IPython.nbconvert.writers.debug.DebugWriter', | ||||
damianavila
|
r11774 | 'StdoutWriter': 'IPython.nbconvert.writers.stdout.StdoutWriter'} | ||
Jonathan Frederic
|
r11367 | writer_factory = Type() | ||
Paul Ivanov
|
r11251 | |||
Jonathan Frederic
|
r11367 | def _writer_class_changed(self, name, old, new): | ||
if new in self.writer_aliases: | ||||
new = self.writer_aliases[new] | ||||
self.writer_factory = import_item(new) | ||||
Paul Ivanov
|
r11248 | |||
Jonathan Frederic
|
r11747 | # Post-processor specific variables | ||
post_processor = Instance('IPython.nbconvert.post_processors.base.PostProcessorBase', | ||||
help="""Instance of the PostProcessor class used to write the | ||||
results of the conversion.""") | ||||
post_processor_class = DottedOrNone(config=True, | ||||
help="""PostProcessor class used to write the | ||||
results of the conversion""") | ||||
damianavila
|
r11773 | post_processor_aliases = {'PDF': 'IPython.nbconvert.post_processors.pdf.PDFPostProcessor', | ||
'serve': 'IPython.nbconvert.post_processors.serve.ServePostProcessor'} | ||||
Jonathan Frederic
|
r11747 | post_processor_factory = Type() | ||
def _post_processor_class_changed(self, name, old, new): | ||||
if new in self.post_processor_aliases: | ||||
new = self.post_processor_aliases[new] | ||||
if new: | ||||
self.post_processor_factory = import_item(new) | ||||
Brian E. Granger
|
r11087 | |||
Jonathan Frederic
|
r11632 | # Other configurable variables | ||
MinRK
|
r11454 | export_format = CaselessStrEnum(get_export_names(), | ||
Jonathan Frederic
|
r11735 | default_value="html", | ||
MinRK
|
r11454 | config=True, | ||
help="""The export format to be used.""" | ||||
) | ||||
Brian E. Granger
|
r11087 | |||
Jonathan Frederic
|
r11367 | notebooks = List([], config=True, help="""List of notebooks to convert. | ||
MinRK
|
r11454 | Wildcards are supported. | ||
Filenames passed positionally will be added to the list. | ||||
""") | ||||
Brian E. Granger
|
r11087 | |||
Jonathan Frederic
|
r11367 | @catch_config_error | ||
def initialize(self, argv=None): | ||||
super(NbConvertApp, self).initialize(argv) | ||||
Jonathan Frederic
|
r11652 | self.init_syspath() | ||
MinRK
|
r11448 | self.init_notebooks() | ||
Jonathan Frederic
|
r11367 | self.init_writer() | ||
Jonathan Frederic
|
r11747 | self.init_post_processor() | ||
Brian E. Granger
|
r11087 | |||
Jonathan Frederic
|
r11651 | |||
Jonathan Frederic
|
r11652 | def init_syspath(self): | ||
Jonathan Frederic
|
r11651 | """ | ||
Add the cwd to the sys.path ($PYTHONPATH) | ||||
""" | ||||
Jonathan Frederic
|
r11688 | sys.path.insert(0, os.getcwd()) | ||
Jonathan Frederic
|
r11651 | |||
MinRK
|
r11448 | def init_notebooks(self): | ||
MinRK
|
r11468 | """Construct the list of notebooks. | ||
If notebooks are passed on the command-line, | ||||
they override notebooks specified in config files. | ||||
Glob each notebook to replace notebook patterns with filenames. | ||||
Jonathan Frederic
|
r11367 | """ | ||
Brian E. Granger
|
r11087 | |||
MinRK
|
r11468 | # Specifying notebooks on the command-line overrides (rather than adds) | ||
# the notebook list | ||||
if self.extra_args: | ||||
patterns = self.extra_args | ||||
else: | ||||
patterns = self.notebooks | ||||
Jonathan Frederic
|
r11367 | |||
Jonathan Frederic
|
r11632 | # Use glob to replace all the notebook patterns with filenames. | ||
Jonathan Frederic
|
r11367 | filenames = [] | ||
MinRK
|
r11448 | for pattern in patterns: | ||
Jonathan Frederic
|
r11660 | |||
# Use glob to find matching filenames. Allow the user to convert | ||||
# notebooks without having to type the extension. | ||||
globbed_files = glob.glob(pattern) | ||||
globbed_files.extend(glob.glob(pattern + '.ipynb')) | ||||
for filename in globbed_files: | ||||
Jonathan Frederic
|
r11367 | if not filename in filenames: | ||
filenames.append(filename) | ||||
self.notebooks = filenames | ||||
def init_writer(self): | ||||
""" | ||||
Initialize the writer (which is stateless) | ||||
""" | ||||
self._writer_class_changed(None, self.writer_class, self.writer_class) | ||||
self.writer = self.writer_factory(parent=self) | ||||
Brian E. Granger
|
r11087 | |||
Jonathan Frederic
|
r11747 | def init_post_processor(self): | ||
""" | ||||
Initialize the post_processor (which is stateless) | ||||
""" | ||||
self._post_processor_class_changed(None, self.post_processor_class, | ||||
self.post_processor_class) | ||||
if self.post_processor_factory: | ||||
self.post_processor = self.post_processor_factory(parent=self) | ||||
MinRK
|
r11448 | def start(self): | ||
Brian E. Granger
|
r11087 | """ | ||
MinRK
|
r11448 | Ran after initialization completed | ||
Jonathan Frederic
|
r11367 | """ | ||
Brian E. Granger
|
r11087 | super(NbConvertApp, self).start() | ||
Jonathan Frederic
|
r11400 | self.convert_notebooks() | ||
def convert_notebooks(self): | ||||
""" | ||||
Convert the notebooks in the self.notebook traitlet | ||||
""" | ||||
Jonathan Frederic
|
r11632 | # Export each notebook | ||
Jonathan Frederic
|
r11400 | conversion_success = 0 | ||
Matthias BUSSONNIER
|
r11801 | |||
if self.output_base != '' and len(self.notebooks) > 1: | ||||
print(dedent( | ||||
"""UsageError: --output flag or `NbConvertApp.output_base` config option | ||||
cannot be used when converting multiple notebooks. | ||||
""")) | ||||
self.exit(1) | ||||
Jonathan Frederic
|
r11367 | for notebook_filename in self.notebooks: | ||
Jonathan Frederic
|
r11632 | # Get a unique key for the notebook and set it in the resources object. | ||
Jonathan Frederic
|
r11367 | basename = os.path.basename(notebook_filename) | ||
notebook_name = basename[:basename.rfind('.')] | ||||
Matthias BUSSONNIER
|
r11801 | if self.output_base: | ||
notebook_name = self.output_base | ||||
Jonathan Frederic
|
r11367 | resources = {} | ||
resources['unique_key'] = notebook_name | ||||
Jonathan Frederic
|
r11631 | resources['output_files_dir'] = '%s_files' % notebook_name | ||
Jonathan Frederic
|
r11367 | |||
Jonathan Frederic
|
r11632 | # Try to export | ||
Jonathan Frederic
|
r11368 | try: | ||
Jonathan Frederic
|
r11379 | output, resources = export_by_name(self.export_format, | ||
Jonathan Frederic
|
r11368 | notebook_filename, | ||
resources=resources, | ||||
config=self.config) | ||||
Jonathan Frederic
|
r11372 | except ExporterNameError as e: | ||
David Wolever
|
r11703 | print("Error while converting '%s': '%s' exporter not found." | ||
%(notebook_filename, self.export_format), | ||||
Jonathan Frederic
|
r11368 | file=sys.stderr) | ||
print("Known exporters are:", | ||||
"\n\t" + "\n\t".join(get_export_names()), | ||||
file=sys.stderr) | ||||
David Wolever
|
r11705 | self.exit(1) | ||
David Wolever
|
r11703 | except ConversionException as e: | ||
print("Error while converting '%s': %s" %(notebook_filename, e), | ||||
file=sys.stderr) | ||||
David Wolever
|
r11705 | self.exit(1) | ||
Jonathan Frederic
|
r11400 | else: | ||
Jonathan Frederic
|
r11747 | write_resultes = self.writer.write(output, resources, notebook_name=notebook_name) | ||
#Post-process if post processor has been defined. | ||||
if hasattr(self, 'post_processor') and self.post_processor: | ||||
self.post_processor(write_resultes) | ||||
Jonathan Frederic
|
r11400 | conversion_success += 1 | ||
Jonathan Frederic
|
r11632 | # If nothing was converted successfully, help the user. | ||
Jonathan Frederic
|
r11400 | if conversion_success == 0: | ||
Jonathan Frederic
|
r11666 | self.print_help() | ||
Jonathan Frederic
|
r11667 | sys.exit(-1) | ||
damianavila
|
r11772 | |||
Brian E. Granger
|
r11087 | #----------------------------------------------------------------------------- | ||
Brian E. Granger
|
r11092 | # Main entry point | ||
Brian E. Granger
|
r11087 | #----------------------------------------------------------------------------- | ||
MinRK
|
r11176 | launch_new_instance = NbConvertApp.launch_instance | ||