Docstring decorator

nbconvert.py

@@ -1,195 +1,195
 #!/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.export import export_by_name
 from nbconvert.exporters.exporter import Exporter
 from nbconvert.transformers import extractfigure
 
 #-----------------------------------------------------------------------------
 #Globals and constants
 #-----------------------------------------------------------------------------
 
 #'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.
 ===========================================================================
 """
 
 #-----------------------------------------------------------------------------
 #Classes and functions
 #-----------------------------------------------------------------------------
 
 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)
 
         #Register class here to have help with help all
         self.classes.insert(0, Exporter)
 
 
     def start(self, argv=None):
         """Entrypoint of NbConvert application.
         
         Parameters
         ----------
         argv : list
             Commandline arguments
         """
         
         #Parse the commandline options.
         self.parse_command_line(argv)
 
         #Call base
         super(NbConvertApp, self).start()
 
         #The last arguments in list will be used by nbconvert
         export_type = (self.extra_args)[1]
         ipynb_file = (self.extra_args)[2]
 
         #Export
-        return_value = export_by_name(ipynb_file, export_type)
+        return_value = export_by_name(export_type, ipynb_file)
         if return_value is None:
             print("Error: '%s' template not found." % export_type)
             return
         else:
             (output, resources, exporter) = return_value 
         
         #TODO: Allow user to set output directory and file. 
         destination_filename = None
         destination_directory = None
         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.file_extension)
             
             destination_directory = out_root+'_files'
             if not os.path.exists(destination_directory):
                 os.mkdir(destination_directory)
                 
         #Write the results
         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, 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_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_key][binary_key][key])
                 for key in textkeys:
                     with io.open(os.path.join(destination_directory, key), 'w') as f:
                         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_key].keys())
                 print(KEYS_PROMPT_BODY)
 
 #-----------------------------------------------------------------------------
 #Script main
 #-----------------------------------------------------------------------------
 
 def main():
     """Application entry point"""
 
     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/export.py

@@ -1,483 +1,212
 """
 Module containing single call export functions.
 """
 #-----------------------------------------------------------------------------
 # 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
 #-----------------------------------------------------------------------------
 
 import sys
 import inspect
+from functools import wraps
 
 from IPython.nbformat.v3.nbbase import NotebookNode
 
 from .exporters.exporter import Exporter
 from .exporters.basichtml import BasicHtmlExporter
 from .exporters.fullhtml import FullHtmlExporter
 from .exporters.latex import LatexExporter
 from .exporters.markdown import MarkdownExporter
 from .exporters.python import PythonExporter
 from .exporters.python_armor import PythonArmorExporter
 from .exporters.reveal import RevealExporter
 from .exporters.rst import RstExporter
 from .exporters.sphinx_howto import SphinxHowtoExporter
 from .exporters.sphinx_manual import SphinxManualExporter
 
-
 #-----------------------------------------------------------------------------
-# Functions
+# Classes
 #-----------------------------------------------------------------------------
 
-def export(nb, config=None, transformers=None, filters=None, exporter_type=Exporter):
-    """
-    Export a notebook object using specific exporter class.
+def DocDecorator(f):    
     
-    Parameters
-    ----------
+    #Set docstring of function
+    f.__doc__ = f.__doc__ + """
+    nb : Notebook node
     config : config
         User configuration instance.
     transformers : list[of transformer]
         Custom transformers to apply to the notebook prior to engaging
         the Jinja template engine.  Any transformers specified here 
         will override existing transformers if a naming conflict
         occurs.
     filters : list[of filter]
         Custom filters to make accessible to the Jinja templates.  Any
         filters specified here will override existing filters if a
         naming conflict occurs.
-    exporter_type:
-        Class type of the exporter that should be used.  This method
-        will initialize it's own instance of the class.  It is
-        ASSUMED that the class type provided exposes a
-        constructor (__init__) with the same signature as the
-        base Exporter class.
         
     Returns
     ----------
     tuple- output, resources, exporter_instance
     output : str
         Jinja 2 output.  This is the resulting converted notebook.
     resources : dictionary
         Dictionary of resources used prior to and during the conversion 
         process.
     exporter_instance : Exporter
         Instance of the Exporter class used to export the document.  Useful
         to caller because it provides a 'file_extension' property which
-        specifies what extension the output should be saved as.
+        specifies what extension the output should be saved as."""
+            
+    @wraps(f)
+    def decorator(*args, **kwargs):
+        return f(*args, **kwargs)
+    
+    return decorator
+
+
+#-----------------------------------------------------------------------------
+# Functions
+#-----------------------------------------------------------------------------
+
+@DocDecorator
+def export(exporter_type, nb, config=None, transformers=None, filters=None):
+    """
+    Export a notebook object using specific exporter class.
+    
+    exporter_type : Exporter class type
+        Class type of the exporter that should be used.  This method
+        will initialize it's own instance of the class.  It is
+        ASSUMED that the class type provided exposes a
+        constructor (__init__) with the same signature as the
+        base Exporter class.}
     """
     
     #Check arguments
     if exporter_type is None:
         raise TypeError("Exporter is None")
     elif not issubclass(exporter_type, Exporter):
         raise TypeError("Exporter type does not inherit from Exporter (base)")
     
     if nb is None:
         raise TypeError("nb is None")
     
     #Create the exporter
     exporter_instance = exporter_type(preprocessors=transformers, 
                                       jinja_filters=filters, config=config)
 
     #Try to convert the notebook using the appropriate conversion function.
     if isinstance(nb, NotebookNode):
         output, resources = exporter_instance.from_notebook_node(nb)
     elif isinstance(nb, basestring):
         output, resources = exporter_instance.from_filename(nb)
     else:
         output, resources = exporter_instance.from_file(nb)
     return output, resources, exporter_instance
 
 
+@DocDecorator
 def export_sphinx_manual(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Sphinx Manual LaTeX
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    Returns
-    ----------
-    tuple- output, resources, exporter_instance
-    output : str
-        Jinja 2 output.  This is the resulting converted notebook.
-    resources : dictionary
-        Dictionary of resources used prior to and during the conversion 
-        process.
-    exporter_instance : Exporter
-        Instance of the Exporter class used to export the document.  Useful
-        to caller because it provides a 'file_extension' property which
-        specifies what extension the output should be saved as.
     """
-    return export(nb, config, transformers, filters, SphinxManualExporter)
+    return export(SphinxManualExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_sphinx_howto(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Sphinx HowTo LaTeX
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    Returns
-    ----------
-    tuple- output, resources, exporter_instance
-    output : str
-        Jinja 2 output.  This is the resulting converted notebook.
-    resources : dictionary
-        Dictionary of resources used prior to and during the conversion 
-        process.
-    exporter_instance : Exporter
-        Instance of the Exporter class used to export the document.  Useful
-        to caller because it provides a 'file_extension' property which
-        specifies what extension the output should be saved as.
     """
-    return export(nb, config, transformers, filters, SphinxHowtoExporter)
+    return export(SphinxHowtoExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_basic_html(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Basic HTML
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    Returns
-    ----------
-    tuple- output, resources, exporter_instance
-    output : str
-        Jinja 2 output.  This is the resulting converted notebook.
-    resources : dictionary
-        Dictionary of resources used prior to and during the conversion 
-        process.
-    exporter_instance : Exporter
-        Instance of the Exporter class used to export the document.  Useful
-        to caller because it provides a 'file_extension' property which
-        specifies what extension the output should be saved as.
     """
-    return export(nb, config, transformers, filters, BasicHtmlExporter)
+    return export(BasicHtmlExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_full_html(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Full HTML
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    Returns
-    ----------
-    tuple- output, resources, exporter_instance
-    output : str
-        Jinja 2 output.  This is the resulting converted notebook.
-    resources : dictionary
-        Dictionary of resources used prior to and during the conversion 
-        process.
-    exporter_instance : Exporter
-        Instance of the Exporter class used to export the document.  Useful
-        to caller because it provides a 'file_extension' property which
-        specifies what extension the output should be saved as.
     """
-    return export(nb, config, transformers, filters, FullHtmlExporter)
+    return export(FullHtmlExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_latex(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to LaTeX
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    Returns
-    ----------
-    tuple- output, resources, exporter_instance
-    output : str
-        Jinja 2 output.  This is the resulting converted notebook.
-    resources : dictionary
-        Dictionary of resources used prior to and during the conversion 
-        process.
-    exporter_instance : Exporter
-        Instance of the Exporter class used to export the document.  Useful
-        to caller because it provides a 'file_extension' property which
-        specifies what extension the output should be saved as.
     """
-    return export(nb, config, transformers, filters, LatexExporter)
+    return export(LatexExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_markdown(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Markdown
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    Returns
-    ----------
-    tuple- output, resources, exporter_instance
-    output : str
-        Jinja 2 output.  This is the resulting converted notebook.
-    resources : dictionary
-        Dictionary of resources used prior to and during the conversion 
-        process.
-    exporter_instance : Exporter
-        Instance of the Exporter class used to export the document.  Useful
-        to caller because it provides a 'file_extension' property which
-        specifies what extension the output should be saved as.
     """
-    return export(nb, config, transformers, filters, MarkdownExporter)
+    return export(MarkdownExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_python(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Python
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    Returns
-    ----------
-    tuple- output, resources, exporter_instance
-    output : str
-        Jinja 2 output.  This is the resulting converted notebook.
-    resources : dictionary
-        Dictionary of resources used prior to and during the conversion 
-        process.
-    exporter_instance : Exporter
-        Instance of the Exporter class used to export the document.  Useful
-        to caller because it provides a 'file_extension' property which
-        specifies what extension the output should be saved as.
     """
-    return export(nb, config, transformers, filters, PythonExporter)
+    return export(PythonExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_python_armor(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Python (Armor)
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    Returns
-    ----------
-    tuple- output, resources, exporter_instance
-    output : str
-        Jinja 2 output.  This is the resulting converted notebook.
-    resources : dictionary
-        Dictionary of resources used prior to and during the conversion 
-        process.
-    exporter_instance : Exporter
-        Instance of the Exporter class used to export the document.  Useful
-        to caller because it provides a 'file_extension' property which
-        specifies what extension the output should be saved as.
     """
-    return export(nb, config, transformers, filters, PythonArmorExporter)
+    return export(PythonArmorExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_reveal(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Reveal
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    Returns
-    ----------
-    tuple- output, resources, exporter_instance
-    output : str
-        Jinja 2 output.  This is the resulting converted notebook.
-    resources : dictionary
-        Dictionary of resources used prior to and during the conversion 
-        process.
-    exporter_instance : Exporter
-        Instance of the Exporter class used to export the document.  Useful
-        to caller because it provides a 'file_extension' property which
-        specifies what extension the output should be saved as.
     """
-    return export(nb, config, transformers, filters, RevealExporter)
+    return export(RevealExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_rst(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to RST
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    Returns
-    ----------
-    tuple- output, resources, exporter_instance
-    output : str
-        Jinja 2 output.  This is the resulting converted notebook.
-    resources : dictionary
-        Dictionary of resources used prior to and during the conversion 
-        process.
-    exporter_instance : Exporter
-        Instance of the Exporter class used to export the document.  Useful
-        to caller because it provides a 'file_extension' property which
-        specifies what extension the output should be saved as.
     """
-    return export(nb, config, transformers, filters, RstExporter)
+    return export(RstExporter, nb, config, transformers, filters)
 
 
-def export_by_name(nb, template_name, config=None, transformers=None, filters=None):
+@DocDecorator
+def export_by_name(template_name, nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to a template type by its name.  Reflection
     (Inspect) is used to find the template's corresponding explicit export
     method defined in this module.  That method is then called directly.
     
-    Parameters
-    ----------
     template_name : str
         Name of the template style to export to.
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    Returns
-    ----------
-    tuple- (output, resources, exporter_instance)
-    None- if template not found
-    
-    output : str
-        Jinja 2 output.  This is the resulting converted notebook.
-    resources : dictionary
-        Dictionary of resources used prior to and during the conversion 
-        process.
-    exporter_instance : Exporter
-        Instance of the Exporter class used to export the document.  Useful
-        to caller because it provides a 'file_extension' property which
-        specifies what extension the output should be saved as.
     """
     
     function_name = "export_" + template_name.lower()
     
     if function_name in globals():
         return globals()[function_name](nb, config, transformers, filters)
     else:
         return None
             
  No newline at end of file