Split exporter in to for ipynb->ipynb

IPython/nbconvert/exporters/baseexporter.py

@@ -0,0 +1,282 b''
+"""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 copy
+import collections
+import datetime
+
+
+# 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, Unicode, List
+from IPython.utils.importstring import import_item
+from IPython.utils import py3compat
+
+from IPython.nbconvert import transformers as nbtransformers
+
+
+#-----------------------------------------------------------------------------
+# Class
+#-----------------------------------------------------------------------------
+
+class ResourcesDict(collections.defaultdict):
+    def __missing__(self, key):
+        return ''
+
+
+class BaseExporter(LoggingConfigurable):
+    """
+    Base Exporter Class that only conver notebook to notebook
+    and apply the transformers and provide basic methods for
+    reading a notebook from different sources.
+
+    """
+    
+    # finish the docstring
+
+    file_extension = Unicode(
+        'txt', config=True, 
+        help="Extension of the file that should be written to disk"
+        )
+
+    #Configurability, allows the user to easily add transformers.
+    transformers = List(config=True,
+        help="""List of transformers, by name or namespace, to enable.""")
+
+    _transformers = None
+
+    default_transformers = List([nbtransformers.coalesce_streams,
+                                 nbtransformers.SVG2PDFTransformer,
+                                 nbtransformers.ExtractOutputTransformer,
+                                 nbtransformers.CSSHTMLHeaderTransformer,
+                                 nbtransformers.RevealHelpTransformer,
+                                 nbtransformers.LatexTransformer,
+                                 nbtransformers.SphinxTransformer],
+        config=True,
+        help="""List of transformers available by default, by name, namespace, 
+        instance, or type.""")
+
+
+    def __init__(self, config=None, **kw):
+        """
+        Public constructor
+    
+        Parameters
+        ----------
+        config : config
+            User configuration instance.
+        """
+        if not config:
+            config = self.default_config
+        
+        super(BaseExporter, self).__init__(config=config, **kw)
+
+        #Init
+        self._init_transformers()
+
+
+    @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(BaseExporter, self)._config_changed(name, old, c)
+
+
+    def from_notebook_node(self, nb, resources=None):
+        """
+        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 
+            transformers.
+        """
+        nb_copy = copy.deepcopy(nb)
+        resources = self._init_resources(resources)
+
+        # Preprocess
+        nb_copy, resources = self._transform(nb_copy, resources)
+
+        return nb_copy, 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'] = modified_date.strftime("%B %d, %Y")
+        
+        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_transformer(self, transformer, enabled=False):
+        """
+        Register a transformer.
+        Transformers are classes that act upon the notebook before it is
+        passed into the Jinja templating engine.  Transformers are also
+        capable of passing additional information to the Jinja
+        templating engine.
+    
+        Parameters
+        ----------
+        transformer : transformer
+        """
+        if transformer is None:
+            raise TypeError('transformer')
+        isclass = isinstance(transformer, type)
+        constructed = not isclass
+
+        #Handle transformer's registration based on it's type
+        if constructed and isinstance(transformer, py3compat.string_types):
+            #Transformer is a string, import the namespace and recursively call
+            #this register_transformer method
+            transformer_cls = import_item(transformer)
+            return self.register_transformer(transformer_cls, enabled)
+        
+        if constructed and hasattr(transformer, '__call__'):
+            #Transformer is a function, no need to construct it.
+            #Register and return the transformer.
+            if enabled:
+                transformer.enabled = True
+            self._transformers.append(transformer)
+            return transformer
+
+        elif isclass and isinstance(transformer, MetaHasTraits):
+            #Transformer is configurable.  Make sure to pass in new default for 
+            #the enabled flag if one was specified.
+            self.register_transformer(transformer(parent=self), enabled)
+
+        elif isclass:
+            #Transformer is not configurable, construct it
+            self.register_transformer(transformer(), enabled)
+
+        else:
+            #Transformer is an instance of something without a __call__ 
+            #attribute.  
+            raise TypeError('transformer')
+
+
+    def _init_transformers(self):
+        """
+        Register all of the transformers needed for this exporter, disabled
+        unless specified explicitly.
+        """
+        if self._transformers is None:
+            self._transformers = []
+
+        #Load default transformers (not necessarly enabled by default).
+        if self.default_transformers:
+            for transformer in self.default_transformers:
+                self.register_transformer(transformer)
+
+        #Load user transformers.  Enable by default.
+        if self.transformers:
+            for transformer in self.transformers:
+                self.register_transformer(transformer, enabled=True)
+ 
+
+    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 _transform(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 transformers
+        """
+        
+        # Do a copy.deepcopy first, 
+        # we are never safe enough with what the transformers could do.
+        nbc =  copy.deepcopy(nb)
+        resc = copy.deepcopy(resources)
+
+        #Run each transformer on the notebook.  Carry the output along
+        #to each transformer
+        for transformer in self._transformers:
+            nbc, resc = transformer(nbc, resc)
+        return nbc, resc