Refactoring for the rename of ConverterTemplate to Exporter.

api/exporter.py

@@ -1,255 +1,249 b''
-"""Base classes for the notebook conversion pipeline.
+"""Exporter for the notebook conversion pipeline.
 
-This module defines ConverterTemplate, a highly configurable converter
-that uses Jinja2 to convert notebook files into different format.
+This module defines Exporter, a highly configurable converter
+that uses Jinja2 to export notebook files into different format.
 
 You can register both pre-transformers that will act on the notebook format
 befor conversion and jinja filter that would then be availlable in the templates
 """
 
-from __future__ import absolute_import
-
 #-----------------------------------------------------------------------------
 # 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
-from __future__ import absolute_import
+from __future__ import print_function, absolute_import
 
 # Stdlib imports
 import io
 import os
 
 # IPython imports
-from IPython.utils.traitlets import MetaHasTraits
-from IPython.utils.traitlets import (Unicode, List, Bool)
 from IPython.config.configurable import Configurable
 from IPython.nbformat import current as nbformat
-
+from IPython.utils.traitlets import MetaHasTraits, Unicode, List, Bool
 
 # other libs/dependencies
 from jinja2 import Environment, FileSystemLoader
 
-
 # local import (pre-transformers)
-from  . import transformers as trans
+from . import transformers as trans #TODO
+
 try:
-    from .sphinx_transformer import (SphinxTransformer)
+    from .sphinx_transformer import (SphinxTransformer) #TODO
 except ImportError:
     SphinxTransformer = None
 
-from .latex_transformer import (LatexTransformer)
+from .latex_transformer import (LatexTransformer) #TODO
 
 # some jinja filters
 from .jinja_filters import (python_comment, indent,
         rm_fake, remove_ansi, markdown, highlight, highlight2latex,
         ansi2html, markdown2latex, get_lines, escape_tex, FilterDataType,
         rm_dollars, rm_math_space
         )
 
-from .utils import  markdown2rst
+from .utils import  markdown2rst #TODO
 
-import textwrap
+import textwrap #TODO
 
 def wrap(text, width=100):
     """ try to detect and wrap paragraph"""
     splitt = text.split('\n')
     wrp = map(lambda x:textwrap.wrap(x,width),splitt)
     wrpd = map('\n'.join, wrp)
     return '\n'.join(wrpd)
 
 
 
 # define differents environemnt with different
 # delimiters not to conflict with languages inside
 
 env = Environment(
         loader=FileSystemLoader([
             os.path.dirname(os.path.realpath(__file__))+'/../templates/',
             os.path.dirname(os.path.realpath(__file__))+'/../templates/skeleton/',
             ]),
         extensions=['jinja2.ext.loopcontrols']
         )
 
 
 texenv = Environment(
         loader=FileSystemLoader([
             os.path.dirname(os.path.realpath(__file__))+'/../templates/tex/',
             os.path.dirname(os.path.realpath(__file__))+'/../templates/skeleton/tex/',
             ]),
         extensions=['jinja2.ext.loopcontrols']
         )
 
 
 texenv.block_start_string = '((*'
 texenv.block_end_string = '*))'
 
 texenv.variable_start_string = '((('
 texenv.variable_end_string = ')))'
 
 texenv.comment_start_string = '((='
 texenv.comment_end_string = '=))'
 
 texenv.filters['escape_tex'] = escape_tex
 
 #-----------------------------------------------------------------------------
 # Class declarations
 #-----------------------------------------------------------------------------
 class ConversionException(Exception):
     pass
 
-class ConverterTemplate(Configurable):
+class Exporter(Configurable):
     """ A Jinja2 base converter templates
 
     Preprocess the ipynb files, feed it throug jinja templates,
     and spit an converted files and a data object with other data
 
     should be mostly configurable
     """
 
     pre_transformer_order = List(['haspyout_transformer'],
             config=True,
               help= """
                     An ordered list of pre transformer to apply to the ipynb
                     file before running through templates
                     """
             )
 
     tex_environement = Bool(False,
             config=True,
             help=""" is this a tex environment or not """)
 
     template_file = Unicode('',
             config=True,
             help=""" Name of the template file to use """ )
     #-------------------------------------------------------------------------
     # Instance-level attributes that are set in the constructor for this
     # class.
     #-------------------------------------------------------------------------
 
 
     preprocessors = []
 
     def __init__(self, preprocessors={}, jinja_filters={}, config=None, **kw):
         """ Init a new converter.
 
         config: the Configurable config object to pass around.
 
         preprocessors: dict of **availlable** key/value function to run on
                        ipynb json data before conversion to extract/inline file.
                        See `transformer.py` and `ConfigurableTransformers`
 
                        set the order in which the transformers should apply
                        with the `pre_transformer_order` trait of this class
 
                        transformers registerd by this key will take precedence on
                        default one.
 
 
         jinja_filters: dict of supplementary jinja filter that should be made
                        availlable in template. If those are of Configurable Class type,
                        they will be instanciated with the config object as argument.
 
                        user defined filter will overwrite the one availlable by default.
         """
         super(ConverterTemplate, self).__init__(config=config, **kw)
 
         # variable parameters depending on the pype of jinja environement
         self.env = texenv  if self.tex_environement else env
         self.ext = '.tplx' if self.tex_environement else '.tpl'
 
         for name in self.pre_transformer_order:
             # get the user-defined transformer first
             transformer = preprocessors.get(name, getattr(trans, name, None))
             if isinstance(transformer, MetaHasTraits):
                 transformer = transformer(config=config)
             self.preprocessors.append(transformer)
 
         ## for compat, remove later
         self.preprocessors.append(trans.coalesce_streams)
         self.preprocessors.append(trans.ExtractFigureTransformer(config=config))
         self.preprocessors.append(trans.RevealHelpTransformer(config=config))
         self.preprocessors.append(trans.CSSHtmlHeaderTransformer(config=config))
         if SphinxTransformer:
             self.preprocessors.append(SphinxTransformer(config=config))
         self.preprocessors.append(LatexTransformer(config=config))
 
         ##
         self.env.filters['filter_data_type'] = FilterDataType(config=config)
         self.env.filters['pycomment'] = python_comment
         self.env.filters['indent'] = indent
         self.env.filters['rm_fake'] = rm_fake
         self.env.filters['rm_ansi'] = remove_ansi
         self.env.filters['markdown'] = markdown
         self.env.filters['highlight'] = highlight2latex if self.tex_environement else highlight 
         self.env.filters['highlight2html'] = highlight 
         self.env.filters['highlight2latex'] = highlight2latex
         self.env.filters['ansi2html'] = ansi2html
         self.env.filters['markdown2latex'] = markdown2latex
         self.env.filters['markdown2rst'] = markdown2rst
         self.env.filters['get_lines'] = get_lines
         self.env.filters['wrap'] = wrap
         self.env.filters['rm_dollars'] = rm_dollars
         self.env.filters['rm_math_space'] = rm_math_space
 
         ## user  filter will overwrite
         for key, filtr in jinja_filters.iteritems():
             if isinstance(filtr, MetaHasTraits):
                 self.env.filters[key] = filtr(config=config)
             else :
                 self.env.filters[key] = filtr
 
         self.template = self.env.get_template(self.template_file+self.ext)
 
 
     def process(self, nb):
         """
         preprocess the notebook json for easier use with the templates.
         will call all the `preprocessor`s in order before returning it.
         """
 
         # dict of 'resources' that could be made by the preprocessors
         # like key/value data to extract files from ipynb like in latex conversion
         resources = {}
 
         for preprocessor in self.preprocessors:
             nb, resources = preprocessor(nb, resources)
 
         return nb, resources
 
     def convert(self, nb):
         """ convert the ipynb file
 
         return both the converted ipynb file and a dict containing potential
         other resources
         """
         nb, resources = self.process(nb)
         return self.template.render(nb=nb, resources=resources), resources
 
 
     def from_filename(self, filename):
         """read and convert a notebook from a file name"""
         with io.open(filename) as f:
             return self.convert(nbformat.read(f, 'json'))
 
     def from_file(self, filelike):
         """read and convert a notebook from a filelike object
 
         filelike object will just be "read" and should be json format..
         """
         return self.convert(nbformat.read(filelike, 'json'))
 
     def from_json(self, json):
         """ not implemented
 
         Should convert from a json object
         """
         raise NotImplementedError('not implemented (yet?)')

nbconvert.py

@@ -1,183 +1,201 b''
 #!/usr/bin/env python
 
 """NBConvert is a utility for conversion of IPYNB files.
 
 Commandline interface for the NBConvert conversion utility.  Read the
 readme.rst for usage information
 """
 #-----------------------------------------------------------------------------
-# Copyright (c) 2013, the IPython Development Team.
+#Copyright (c) 2013, the IPython Development Team.
 #
-# Distributed under the terms of the Modified BSD License.
+#Distributed under the terms of the Modified BSD License.
 #
-# The full license is in the file COPYING.txt, distributed with this software.
+#The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
-# Imports
+#Imports
 #-----------------------------------------------------------------------------
 
-# Stdlib imports
+#Stdlib imports
 from __future__ import print_function
 import sys
 import io
 import os
 
-# From IPython
-# All the stuff needed for the configurable things
+#From IPython
+#All the stuff needed for the configurable things
 from IPython.config.application import Application
 from IPython.config.loader import ConfigFileNotFound
 from IPython.utils.traitlets import Unicode, Bool
 
-# Local imports
-from converters.template import ConverterTemplate #TODO
+#Local imports
+from api.exporter import Exporter
 from converters.config import GlobalConfigurable #TODO
 from converters.transformers import (ExtractFigureTransformer) #TODO
 
 #-----------------------------------------------------------------------------
-# Globals and constants
+#Globals and constants
 #-----------------------------------------------------------------------------
 NBCONVERT_DIR = os.path.abspath(os.path.realpath(os.path.dirname(__file__)))
+
+#'Keys in resources' user prompt.
+KEYS_PROMPT_HEAD = "====================== Keys in Resources =================================="
+KEYS_PROMPT_BODY = """
+===========================================================================
+You are responsible for writting these files into the appropriate 
+directorie(s) if need be.  If you do not want to see this message, enable
+the 'write' (boolean) flag of the converter.
+===========================================================================
+"""
+
+#Error Messages
 ERROR_CONFIG_NOT_FOUND = "Config file for profile '%s' not found, giving up."
+
 #-----------------------------------------------------------------------------
-# Classes and functions
+#Classes and functions
 #-----------------------------------------------------------------------------
 class NbconvertApp(Application):
     """A basic application to convert ipynb files"""
 
     stdout = Bool(
         True, config=True,
         help="""Whether to print the converted ipynb file to stdout
         "use full do diff files without actually writing a new file"""
         )
 
     write = Bool(
         False, config=True,
         help="""Should the converted notebook file be written to disk
         along with potential extracted resources."""
         )
 
     fileext = Unicode(
         'txt', config=True, 
         help="Extension of the file that should be written to disk"
         )
 
     aliases = {
         'stdout':'NbconvertApp.stdout',
         'write':'NbconvertApp.write'
         }
 
     flags = {}
     flags['no-stdout'] = (
         {'NbconvertApp' : {'stdout' : False}}, 
         """Do not print converted file to stdout, equivalent to 
         --stdout=False"""
         )
 
     def __init__(self, **kwargs):
         """Public constructor"""
 
         #Call base class
         super(NbconvertApp, self).__init__(**kwargs)
 
         #Register class here to have help with help all
         self.classes.insert(0, ConverterTemplate)
         self.classes.insert(0, ExtractFigureTransformer)
         self.classes.insert(0, GlobalConfigurable)
 
 
     def load_config_file(self, profile_name):
         """Load a config file from the config file dir
 
         profile_name : {string} name of the profile file to load without file 
         extension.
         """
 
         #Try to load the config file.  If the file isn't found, catch the 
         #exception.
         try:
             Application.load_config_file(
                 self,
                 profile_name + '.py',
                 path=[os.path.join(NBCONVERT_DIR, 'profile')]
                 )
             return True
 
         except ConfigFileNotFound:
             self.log.warn(ERROR_CONFIG_NOT_FOUND, profile_name)
             return False
 
 
     def start(self, argv=None):
         """Convert a notebook in one step"""
 
         #Parse the commandline options.
         self.parse_command_line(argv)
 
         #Load an addition config file if specified by the user via the 
         #commandline.
         cl_config = self.config
         profile_file = argv[1]
         if not self.load_config_file(profile_file):
             exit(1)
         self.update_config(cl_config)
 
         #Call base
         super(NbconvertApp, self).start()
 
         #The last arguments in chain of arguments will be used as conversion
         ipynb_file = (self.extra_args or [None])[2]
 
-        # If you are writting a custom transformer, append it to the dictionary
-        # below.
+        #If you are writting a custom transformer, append it to the dictionary
+        #below.
         userpreprocessors = {}
 
-        # Create the Jinja template converter TODO, refactor this
-        C = ConverterTemplate(config=self.config, preprocessors=userpreprocessors)
+        #Create the Jinja template exporter.  TODO: Add ability to 
+        #import in IPYNB aswell
+        exporter = Exporter(config=self.config, preprocessors=userpreprocessors)
 
-        output, resources = C.from_filename(ipynb_file)
+        #Export
+        output, resources = exporter.from_filename(ipynb_file)
         if self.stdout :
             print(output.encode('utf-8'))
 
+        #Get the file name without the '.ipynb' (6 chars) extension and then
+        #remove any addition periods and spaces. The resulting name will
+        #be used to create the directory that the files will be exported
+        #into.
         out_root = ipynb_file[:-6].replace('.', '_').replace(' ', '_')
 
+        #Write file output from conversion.
         if self.write :
             with io.open(os.path.join(out_root+'.'+self.fileext), 'w') as f:
                 f.write(output)
 
+        #Output any associate figures into the same "root" directory.
         binkeys = resources.get('figures', {}).get('binary',{}).keys()
         textkeys = resources.get('figures', {}).get('text',{}).keys()
         if binkeys or textkeys :
             if self.write:
                 files_dir = out_root+'_files'
                 if not os.path.exists(out_root+'_files'):
                     os.mkdir(files_dir)
                 for key in binkeys:
                     with io.open(os.path.join(files_dir, key), 'wb') as f:
                         f.write(resources['figures']['binary'][key])
                 for key in textkeys:
                     with io.open(os.path.join(files_dir, key), 'w') as f:
                         f.write(resources['figures']['text'][key])
 
+            #Figures that weren't exported which will need to be created by the
+            #user.  Tell the user what figures these are.
             elif self.stdout:
-                print('''====================== Keys in Resources ==================================''')
+                print(KEYS_PROMPT_HEAD)
                 print(resources['figures'].keys())
-                print("""
-===========================================================================
-you are responsible from writing those data do a file in the right place if
-they need to be.
-===========================================================================
-                  """)
+                print(KEYS_PROMPT_BODY)
 
 #-----------------------------------------------------------------------------
-# Script main
+#Script main
 #-----------------------------------------------------------------------------
 def main():
     """Convert a notebook in one step"""
-    
+
     app = NbconvertApp.instance()
     app.description = __doc__
     app.run(argv=sys.argv)
 
 if __name__ == '__main__':
     main()
  No newline at end of file