Comment & Refactor, utils and nbconvert main.

nbconvert/utils/console.py

@@ -0,0 +1,121 b''
+"""Utility functions for interacting with the console"""
+#-----------------------------------------------------------------------------
+# 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
+#-----------------------------------------------------------------------------
+
+# Used to determine python version
+import sys
+
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
+            
+def input(self, prompt_text):
+    """
+    Prompt the user for input.
+    
+    The input command will change depending on the version of python
+    installed.  To maintain support for 2 and earlier, we must use
+    raw_input in that case.  Else use input.
+    
+    Parameters
+    ----------
+    prompt_text : str
+        Prompt to display to the user.
+    """
+    
+    # Try to get the python version.  This command is only available in
+    # python 2 and later, so it's important that we catch the exception
+    # if the command isn't found.
+    try:
+        majorversion = sys.version_info[0]
+    except:
+        majorversion = 1
+        
+    # Use the correct function to prompt the user for input depending on 
+    # what python version the code is running in.
+    if majorversion >= 3:
+        return input(prompt_text) 
+    else:
+        return raw_input(prompt_text)
+
+    
+def prompt_boolean(self, prompt, default=False):
+    """
+    Prompt the user for a boolean response.
+    
+    Parameters
+    ----------
+    prompt : str
+        prompt to display to the user
+    default : bool, optional
+        response to return if none is given by the user
+    """
+    
+    response = self._input(prompt)
+    response = response.strip().lower()
+    
+    #Catch 1, true, yes as True
+    if len(response) > 0 and (response == "1" or response[0] == "t" or response[0] == "y"):
+        return True
+    
+    #Catch 0, false, no as False
+    elif len(response) > 0 and (response == "0" or response[0] == "f" or response[0] == "n"):
+        return False
+        
+    else:
+        return default
+
+
+def prompt_dictionary(self, choices, default_style=1, menu_comments={}):
+    """
+    Prompt the user to chose one of many selections from a menu.
+    
+    Parameters
+    ----------
+    choices : dictionary
+        Keys - choice numbers (int)
+        Values - choice value (str), this is what the function will return
+    default_style : int, optional
+        Choice to select if the user doesn't respond
+    menu_comments : dictionary, optional
+        Additional comments to append to the menu as it is displayed
+        in the console.
+        Keys - choice numbers (int)
+        Values - comment (str), what will be appended to the 
+        corresponding choice
+    """
+            
+    # Build the menu that will be displayed to the user with
+    # all of the options available. 
+    prompt = ""
+    for key, value in choices.iteritems():
+        prompt += "%d %s " % (key, value)
+        if key in menu_comments:
+            prompt += menu_comments[key]
+        prompt += "\n"
+    
+    # Continue to ask the user for a style until an appropriate
+    # one is specified.
+    response = -1
+    while (not response in choices):
+        try:
+            text_response = self._input(prompt)
+            
+            # Use default option if no input.
+            if len(text_response.strip()) == 0:
+                response = default_style
+            else:
+                response = int(text_response)
+        except:
+            print("Error: Value is not an available option.  0 selects the default.\n")
+    return choices[response]
+    
  No newline at end of file

nbconvert.py

@@ -1,155 +1,190 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.
 #
 #Distributed under the terms of the Modified BSD License.
 #
 #The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 #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.config.application import Application
+from IPython.utils.traitlets import (Bool)
 
 #Local imports
 from nbconvert.api.convert import export_by_name
 from nbconvert.api.exporter import Exporter
+from nbconvert.transformers import extractfigure
 
 #-----------------------------------------------------------------------------
 #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
 #-----------------------------------------------------------------------------
-class NbconvertApp(Application):
-    """A basic application to convert ipynb files"""
-
-    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"""
+
+class NbConvertApp(Application):
+    """Application used to convert to and from notebook file type (*.ipynb)"""
+
+    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."""
+        )
+
+
     def __init__(self, **kwargs):
         """Public constructor"""
 
         #Call base class
-        super(NbconvertApp, self).__init__(**kwargs)
+        super(NbConvertApp, self).__init__(**kwargs)
 
         #Register class here to have help with help all
         self.classes.insert(0, Exporter)
 
 
     def start(self, argv=None):
-        """Convert a notebook in one step"""
-
+        """Entrypoint of NbConvert application.
+        
+        Parameters
+        ----------
+        argv : list
+            Commandline arguments
+        """
+        
         #Parse the commandline options.
         self.parse_command_line(argv)
 
         #Call base
-        super(NbconvertApp, self).start()
+        super(NbConvertApp, self).start()
 
-        #The last arguments in chain of arguments will be used as conversion type
-        ipynb_file = (self.extra_args)[2]
+        #The last arguments in list will be used by nbconvert
         export_type = (self.extra_args)[1]
+        ipynb_file = (self.extra_args)[2]
 
         #Export
         output, resources, exporter = export_by_name(ipynb_file, export_type)
         
+        #TODO: Allow user to set output directory and file. 
         destination_filename = None
         destination_directory = None
-        if exporter.write:
+        if self.write:
                 
             #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(' ', '_')
             destination_filename = os.path.join(out_root+'.'+exporter.fileext)
             
             destination_directory = out_root+'_files'
             if not os.path.exists(destination_directory):
                 os.mkdir(destination_directory)
                 
         #Write the results
-        if exporter.stdout or exporter.write:
-            self._write_results(exporter.stdout, destination_filename, destination_directory, output, resources)
+        if self.stdout or not (destination_filename is None and destination_directory is None):
+            self._write_results(output, resources, self.stdout, destination_filename, destination_directory)
 
 
-    def _write_results(self, stdout, destination_filename, destination_directory, output, resources):
+    def _write_results(self, output, resources, stdout=False, destination_filename=None, destination_directory=None):
+        """Output the conversion results to the console and/or filesystem
+        
+        Parameters
+        ----------
+        output : str
+            Output of conversion
+        resources : dictionary
+            Additional input/output used by the transformers.  For
+            example, the ExtractFigure transformer outputs the
+            figures it extracts into this dictionary.  This method
+            relies on the figures being in this dictionary when
+            attempting to write the figures to the file system.
+        stdout : bool, Optional
+            Whether or not to echo output to console
+        destination_filename : str, Optional
+            Filename to write output into.  If None, output is not 
+            written to a file.
+        destination_directory : str, Optional 
+            Directory to write notebook data (i.e. figures) to.  If
+            None, figures are not written to the file system.
+        """
+        
         if stdout:
             print(output.encode('utf-8'))
 
         #Write file output from conversion.
         if not destination_filename is None:
             with io.open(destination_filename, 'w') as f:
                 f.write(output)
 
+        #Get the key names used by the extract figure transformer
+        figures_key = extractfigure.FIGURES_KEY
+        binary_key = extractfigure.BINARY_KEY
+        text_key = extractfigure.TEXT_KEY
+        
         #Output any associate figures into the same "root" directory.
-        binkeys = resources.get('figures', {}).get('binary',{}).keys()
-        textkeys = resources.get('figures', {}).get('text',{}).keys()
+        binkeys = resources.get(figures_key, {}).get(binary_key,{}).keys()
+        textkeys = resources.get(figures_key, {}).get(text_key,{}).keys()
         if binkeys or textkeys :
             if not destination_directory is None:
                 for key in binkeys:
                     with io.open(os.path.join(destination_directory, key), 'wb') as f:
-                        f.write(resources['figures']['binary'][key])
+                        f.write(resources[figures_key][binary_key][key])
                 for key in textkeys:
                     with io.open(os.path.join(destination_directory, key), 'w') as f:
-                        f.write(resources['figures']['text'][key])
+                        f.write(resources[figures_key][text_key][key])
 
             #Figures that weren't exported which will need to be created by the
             #user.  Tell the user what figures these are.
             if stdout:
                 print(KEYS_PROMPT_HEAD)
-                print(resources['figures'].keys())
+                print(resources[figures_key].keys())
                 print(KEYS_PROMPT_BODY)
 
 #-----------------------------------------------------------------------------
 #Script main
 #-----------------------------------------------------------------------------
+
 def main():
-    """Convert a notebook in one step"""
+    """Application entry point"""
 
-    app = NbconvertApp.instance()
+    app = NbConvertApp.instance()
     app.description = __doc__
     app.start(argv=sys.argv)
 
+#Check to see if python is calling this file directly.
 if __name__ == '__main__':
     main()
  No newline at end of file

nbconvert/utils/exceptions.py

@@ -1,21 +1,17 b''
-"""Contains all of the exceptions used in NBConvert explicitly"""
+"""NbConvert specific exceptions"""
 #-----------------------------------------------------------------------------
 # 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
-
-#-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
+
 class ConversionException(Exception):
     """An exception raised by the conversion process."""
 
     pass
  No newline at end of file

nbconvert/utils/lexers.py

@@ -1,38 +1,46 b''
 """A custom pygments lexer for IPython code cells.
 
 Informs The pygments highlighting library of the quirks of IPython's superset
 of Python -- magic commands, !shell commands, etc.
 """
 #-----------------------------------------------------------------------------
-# Copyright (c) 2012, the IPython Development Team.
+# 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
 #-----------------------------------------------------------------------------
 
 # Third-party imports
 from pygments.lexers import PythonLexer, BashLexer
 from pygments.lexer import bygroups, using
 from pygments.token import Keyword, Operator, Text
 
-
 #-----------------------------------------------------------------------------
 # Class declarations
 #-----------------------------------------------------------------------------
 
 class IPythonLexer(PythonLexer):
+    """
+    Pygments Lexer for use with IPython code.  Inherits from 
+    PythonLexer and adds information about IPython specific
+    keywords (i.e. magic commands, shell commands, etc.)
+    """
+    
+    #Basic properties
     name = 'IPython'
     aliases = ['ip', 'ipython']
     filenames = ['*.ipy']
+    
+    #Highlighting information
     tokens = PythonLexer.tokens.copy()
     tokens['root'] = [
         (r'(\%+)(\w+)\s+(\.*)(\n)', bygroups(Operator, Keyword,
                                              using(BashLexer), Text)),
         (r'(\%+)(\w+)\b', bygroups(Operator, Keyword)),
         (r'^(!)(.+)(\n)', bygroups(Operator, using(BashLexer), Text)),
-    ] + tokens['root']
+        ] + tokens['root']