"""This module defines Exporter, a highly configurable converter that uses Jinja2 to export notebook files into different formats. """ #----------------------------------------------------------------------------- # 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 #----------------------------------------------------------------------------- from __future__ import print_function, absolute_import # Stdlib imports import io import os import inspect import copy import collections import datetime # other libs/dependencies from jinja2 import Environment, FileSystemLoader, ChoiceLoader, TemplateNotFound # IPython imports from IPython.config.configurable import LoggingConfigurable from IPython.config import Config from IPython.nbformat import current as nbformat from IPython.utils.traitlets import MetaHasTraits, DottedObjectName, Unicode, List, Dict, Any from IPython.utils.importstring import import_item from IPython.utils.text import indent, format_date from IPython.utils import py3compat from IPython.nbconvert import preprocessors as nbpreprocessors from IPython.nbconvert import filters #----------------------------------------------------------------------------- # Globals and constants #----------------------------------------------------------------------------- #Jinja2 extensions to load. JINJA_EXTENSIONS = ['jinja2.ext.loopcontrols'] default_filters = { 'indent': indent, 'markdown2html': filters.markdown2html, 'ansi2html': filters.ansi2html, 'filter_data_type': filters.DataTypeFilter, 'get_lines': filters.get_lines, 'highlight2html': filters.highlight2html, 'highlight2latex': filters.highlight2latex, 'ipython2python': filters.ipython2python, 'posix_path': filters.posix_path, 'markdown2latex': filters.markdown2latex, 'markdown2rst': filters.markdown2rst, 'comment_lines': filters.comment_lines, 'strip_ansi': filters.strip_ansi, 'strip_dollars': filters.strip_dollars, 'strip_files_prefix': filters.strip_files_prefix, 'html2text' : filters.html2text, 'add_anchor': filters.add_anchor, 'ansi2latex': filters.ansi2latex, 'strip_math_space': filters.strip_math_space, 'wrap_text': filters.wrap_text, 'escape_latex': filters.escape_latex, } #----------------------------------------------------------------------------- # Class #----------------------------------------------------------------------------- class ResourcesDict(collections.defaultdict): def __missing__(self, key): return '' class Exporter(LoggingConfigurable): """ Exports notebooks into other file formats. Uses Jinja 2 templating engine to output new formats. Inherit from this class if you are creating a new template type along with new filters/preprocessors. If the filters/ preprocessors provided by default suffice, there is no need to inherit from this class. Instead, override the template_file and file_extension traits via a config file. {filters} """ # finish the docstring __doc__ = __doc__.format(filters = '- '+'\n - '.join(default_filters.keys())) template_file = Unicode(u'default', config=True, help="Name of the template file to use") def _template_file_changed(self, name, old, new): if new=='default': self.template_file = self.default_template else: self.template_file = new self.template = None self._load_template() default_template = Unicode(u'') template = Any() environment = Any() file_extension = Unicode( 'txt', config=True, help="Extension of the file that should be written to disk" ) template_path = List(['.'], config=True) def _template_path_changed(self, name, old, new): self._load_template() default_template_path = Unicode( os.path.join("..", "templates"), help="Path where the template files are located.") template_skeleton_path = Unicode( os.path.join("..", "templates", "skeleton"), help="Path where the template skeleton files are located.") #Jinja block definitions jinja_comment_block_start = Unicode("", config=True) jinja_comment_block_end = Unicode("", config=True) jinja_variable_block_start = Unicode("", config=True) jinja_variable_block_end = Unicode("", config=True) jinja_logic_block_start = Unicode("", config=True) jinja_logic_block_end = Unicode("", config=True) #Extension that the template files use. template_extension = Unicode(".tpl", config=True) #Configurability, allows the user to easily add filters and preprocessors. preprocessors = List(config=True, help="""List of preprocessors, by name or namespace, to enable.""") filters = Dict(config=True, help="""Dictionary of filters, by name and namespace, to add to the Jinja environment.""") default_preprocessors = List([nbpreprocessors.coalesce_streams, nbpreprocessors.SVG2PDFPreprocessor, nbpreprocessors.ExtractOutputPreprocessor, nbpreprocessors.CSSHTMLHeaderPreprocessor, nbpreprocessors.RevealHelpPreprocessor, nbpreprocessors.LatexPreprocessor, nbpreprocessors.SphinxPreprocessor], config=True, help="""List of preprocessors available by default, by name, namespace, instance, or type.""") def __init__(self, config=None, extra_loaders=None, **kw): """ Public constructor Parameters ---------- config : config User configuration instance. extra_loaders : list[of Jinja Loaders] ordered list of Jinja loader to find templates. Will be tried in order before the default FileSystem ones. template : str (optional, kw arg) Template to use when exporting. """ if not config: config = self.default_config super(Exporter, self).__init__(config=config, **kw) #Init self._init_template() self._init_environment(extra_loaders=extra_loaders) self._init_preprocessors() self._init_filters() @property def default_config(self): return Config() def _config_changed(self, name, old, new): """When setting config, make sure to start with our default_config""" c = self.default_config if new: c.merge(new) if c != old: self.config = c super(Exporter, self)._config_changed(name, old, c) def _load_template(self): """Load the Jinja template object from the template file This is a no-op if the template attribute is already defined, or the Jinja environment is not setup yet. This is triggered by various trait changes that would change the template. """ if self.template is not None: return # called too early, do nothing if self.environment is None: return # Try different template names during conversion. First try to load the # template by name with extension added, then try loading the template # as if the name is explicitly specified, then try the name as a # 'flavor', and lastly just try to load the template by module name. module_name = self.__module__.rsplit('.', 1)[-1] try_names = [] if self.template_file: try_names.extend([ self.template_file + self.template_extension, self.template_file, module_name + '_' + self.template_file + self.template_extension, ]) try_names.append(module_name + self.template_extension) for try_name in try_names: self.log.debug("Attempting to load template %s", try_name) try: self.template = self.environment.get_template(try_name) except (TemplateNotFound, IOError): pass except Exception as e: self.log.warn("Unexpected exception loading template: %s", try_name, exc_info=True) else: self.log.info("Loaded template %s", try_name) break def from_notebook_node(self, nb, resources=None, **kw): """ Convert a notebook from a notebook node instance. Parameters ---------- nb : Notebook node resources : dict (**kw) of additional resources that can be accessed read/write by preprocessors and filters. """ nb_copy = copy.deepcopy(nb) resources = self._init_resources(resources) # Preprocess nb_copy, resources = self._preprocess(nb_copy, resources) self._load_template() if self.template is not None: output = self.template.render(nb=nb_copy, resources=resources) else: raise IOError('template file "%s" could not be found' % self.template_file) return output, resources def from_filename(self, filename, resources=None, **kw): """ Convert a notebook from a notebook file. Parameters ---------- filename : str Full filename of the notebook file to open and convert. """ #Pull the metadata from the filesystem. if resources is None: resources = ResourcesDict() if not 'metadata' in resources or resources['metadata'] == '': resources['metadata'] = ResourcesDict() basename = os.path.basename(filename) notebook_name = basename[:basename.rfind('.')] resources['metadata']['name'] = notebook_name modified_date = datetime.datetime.fromtimestamp(os.path.getmtime(filename)) resources['metadata']['modified_date'] = format_date(modified_date) with io.open(filename) as f: return self.from_notebook_node(nbformat.read(f, 'json'), resources=resources,**kw) def from_file(self, file_stream, resources=None, **kw): """ Convert a notebook from a notebook file. Parameters ---------- file_stream : file-like object Notebook file-like object to convert. """ return self.from_notebook_node(nbformat.read(file_stream, 'json'), resources=resources, **kw) def register_preprocessor(self, preprocessor, enabled=False): """ Register a preprocessor. Preprocessors are classes that act upon the notebook before it is passed into the Jinja templating engine. Preprocessors are also capable of passing additional information to the Jinja templating engine. Parameters ---------- preprocessor : preprocessor """ if preprocessor is None: raise TypeError('preprocessor') isclass = isinstance(preprocessor, type) constructed = not isclass #Handle preprocessor's registration based on it's type if constructed and isinstance(preprocessor, py3compat.string_types): #Preprocessor is a string, import the namespace and recursively call #this register_preprocessor method preprocessor_cls = import_item(preprocessor) return self.register_preprocessor(preprocessor_cls, enabled) if constructed and hasattr(preprocessor, '__call__'): #Preprocessor is a function, no need to construct it. #Register and return the preprocessor. if enabled: preprocessor.enabled = True self._preprocessors.append(preprocessor) return preprocessor elif isclass and isinstance(preprocessor, MetaHasTraits): #Preprocessor is configurable. Make sure to pass in new default for #the enabled flag if one was specified. self.register_preprocessor(preprocessor(parent=self), enabled) elif isclass: #Preprocessor is not configurable, construct it self.register_preprocessor(preprocessor(), enabled) else: #Preprocessor is an instance of something without a __call__ #attribute. raise TypeError('preprocessor') def register_filter(self, name, jinja_filter): """ Register a filter. A filter is a function that accepts and acts on one string. The filters are accesible within the Jinja templating engine. Parameters ---------- name : str name to give the filter in the Jinja engine filter : filter """ if jinja_filter is None: raise TypeError('filter') isclass = isinstance(jinja_filter, type) constructed = not isclass #Handle filter's registration based on it's type if constructed and isinstance(jinja_filter, py3compat.string_types): #filter is a string, import the namespace and recursively call #this register_filter method filter_cls = import_item(jinja_filter) return self.register_filter(name, filter_cls) if constructed and hasattr(jinja_filter, '__call__'): #filter is a function, no need to construct it. self.environment.filters[name] = jinja_filter return jinja_filter elif isclass and isinstance(jinja_filter, MetaHasTraits): #filter is configurable. Make sure to pass in new default for #the enabled flag if one was specified. filter_instance = jinja_filter(parent=self) self.register_filter(name, filter_instance ) elif isclass: #filter is not configurable, construct it filter_instance = jinja_filter() self.register_filter(name, filter_instance) else: #filter is an instance of something without a __call__ #attribute. raise TypeError('filter') def _init_template(self): """ Make sure a template name is specified. If one isn't specified, try to build one from the information we know. """ self._template_file_changed('template_file', self.template_file, self.template_file) def _init_environment(self, extra_loaders=None): """ Create the Jinja templating environment. """ here = os.path.dirname(os.path.realpath(__file__)) loaders = [] if extra_loaders: loaders.extend(extra_loaders) paths = self.template_path paths.extend([os.path.join(here, self.default_template_path), os.path.join(here, self.template_skeleton_path)]) loaders.append(FileSystemLoader(paths)) self.environment = Environment( loader= ChoiceLoader(loaders), extensions=JINJA_EXTENSIONS ) #Set special Jinja2 syntax that will not conflict with latex. if self.jinja_logic_block_start: self.environment.block_start_string = self.jinja_logic_block_start if self.jinja_logic_block_end: self.environment.block_end_string = self.jinja_logic_block_end if self.jinja_variable_block_start: self.environment.variable_start_string = self.jinja_variable_block_start if self.jinja_variable_block_end: self.environment.variable_end_string = self.jinja_variable_block_end if self.jinja_comment_block_start: self.environment.comment_start_string = self.jinja_comment_block_start if self.jinja_comment_block_end: self.environment.comment_end_string = self.jinja_comment_block_end def _init_preprocessors(self): """ Register all of the preprocessors needed for this exporter, disabled unless specified explicitly. """ self._preprocessors = [] #Load default preprocessors (not necessarly enabled by default). if self.default_preprocessors: for preprocessor in self.default_preprocessors: self.register_preprocessor(preprocessor) #Load user preprocessors. Enable by default. if self.preprocessors: for preprocessor in self.preprocessors: self.register_preprocessor(preprocessor, enabled=True) def _init_filters(self): """ Register all of the filters required for the exporter. """ #Add default filters to the Jinja2 environment for key, value in default_filters.items(): self.register_filter(key, value) #Load user filters. Overwrite existing filters if need be. if self.filters: for key, user_filter in self.filters.items(): self.register_filter(key, user_filter) def _init_resources(self, resources): #Make sure the resources dict is of ResourcesDict type. if resources is None: resources = ResourcesDict() if not isinstance(resources, ResourcesDict): new_resources = ResourcesDict() new_resources.update(resources) resources = new_resources #Make sure the metadata extension exists in resources if 'metadata' in resources: if not isinstance(resources['metadata'], ResourcesDict): resources['metadata'] = ResourcesDict(resources['metadata']) else: resources['metadata'] = ResourcesDict() if not resources['metadata']['name']: resources['metadata']['name'] = 'Notebook' #Set the output extension resources['output_extension'] = self.file_extension return resources def _preprocess(self, nb, resources): """ Preprocess the notebook before passing it into the Jinja engine. To preprocess the notebook is to apply all of the Parameters ---------- nb : notebook node notebook that is being exported. resources : a dict of additional resources that can be accessed read/write by preprocessors and filters. """ # Do a copy.deepcopy first, # we are never safe enough with what the preprocessors could do. nbc = copy.deepcopy(nb) resc = copy.deepcopy(resources) #Run each preprocessor on the notebook. Carry the output along #to each preprocessor for preprocessor in self._preprocessors: nbc, resc = preprocessor(nbc, resc) return nbc, resc