rename call methods to transform and postprocess

- The `call` methods for nbconvert transformers has been renamed to
  `transform`.
- The `call` methods of nbconvert post-processsors have been renamed to
  `postprocess`.

  pinging @Carreau and @jdrefer, who probably knows who'd be affected by
  this change...  maybe @damianavila, @jakevdp

IPython/nbconvert/exporters/tests/cheese.py

@@ -1,48 +1,48 b''
 """
 Contains CheeseTransformer
 """
 #-----------------------------------------------------------------------------
 # 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 ...transformers.base import Transformer
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class CheeseTransformer(Transformer):
     """
     Adds a cheese tag to the resources object
     """
 
 
     def __init__(self, **kw):
         """
         Public constructor
         """
         super(CheeseTransformer, self).__init__(**kw)
 
 
-    def call(self, nb, resources):
+    def transform(self, nb, resources):
         """
         Sphinx transformation to apply on each notebook.
         
         Parameters
         ----------
         nb : NotebookNode
             Notebook being converted
         resources : dictionary
             Additional resources used in the conversion process.  Allows
             transformers to pass variables into the Jinja engine.
         """
         resources['cheese'] = 'real'
         return nb, resources

IPython/nbconvert/post_processors/base.py

@@ -1,35 +1,35 b''
 """
 Basic post processor
 """
 #-----------------------------------------------------------------------------
 #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 ..utils.base import NbConvertBase
 
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 class PostProcessorBase(NbConvertBase):
 
     def __call__(self, input):
         """
-        See def call() ...
+        See def postprocess() ...
         """
-        self.call(input)
+        self.postprocess(input)
 
 
-    def call(self, input):
+    def postprocess(self, input):
         """
         Post-process output from a writer.
         """
-        raise NotImplementedError('call')
+        raise NotImplementedError('postprocess')

IPython/nbconvert/post_processors/pdf.py

@@ -1,60 +1,60 b''
 """
 Contains writer for writing nbconvert output to PDF.
 """
 #-----------------------------------------------------------------------------
 #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 subprocess
 import os
 
 from IPython.utils.traitlets import Integer, List, Bool
 
 from .base import PostProcessorBase
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 class PDFPostProcessor(PostProcessorBase):
     """Writer designed to write to PDF files"""
 
     iteration_count = Integer(3, config=True, help="""
         How many times pdflatex will be called.
         """)
 
     command = List(["pdflatex", "{filename}"], config=True, help="""
         Shell command used to compile PDF.""")
 
     verbose = Bool(False, config=True, help="""
         Whether or not to display the output of the compile call.
         """)
 
-    def call(self, input):
+    def postprocess(self, input):
             """
             Consume and write Jinja output a PDF.  
             See files.py for more...
             """        
             command = [c.format(filename=input) for c in self.command]
             self.log.info("Building PDF: %s", command)
             with open(os.devnull, 'rb') as null:
                 stdout = subprocess.PIPE if not self.verbose else None
                 for index in range(self.iteration_count):
                     p = subprocess.Popen(command, stdout=stdout, stdin=null)
                     out, err = p.communicate()
                     if p.returncode:
                         if self.verbose:
                             # verbose means I didn't capture stdout with PIPE,
                             # so it's already been displayed and `out` is None.
                             out = u''
                         else:
                             out = out.decode('utf-8', 'replace')
                         self.log.critical(u"PDF conversion failed: %s\n%s", command, out)
                         return

IPython/nbconvert/post_processors/serve.py

@@ -1,55 +1,55 b''
 """
 Contains postprocessor for serving nbconvert output.
 """
 #-----------------------------------------------------------------------------
 #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 os
 import webbrowser
 
 from BaseHTTPServer import HTTPServer
 from SimpleHTTPServer import SimpleHTTPRequestHandler
 
 from IPython.utils.traitlets import Bool
 
 from .base import PostProcessorBase
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 class ServePostProcessor(PostProcessorBase):
     """Post processor designed to serve files"""
 
 
     open_in_browser = Bool(True, config=True,
                            help="""Set to False to deactivate
                            the opening of the browser""")
 
-    def call(self, input):
+    def postprocess(self, input):
         """
         Simple implementation to serve the build directory.
         """
 
         try:
             dirname, filename = os.path.split(input)
             if dirname:
                 os.chdir(dirname)
             httpd = HTTPServer(('127.0.0.1', 8000), SimpleHTTPRequestHandler)
             sa = httpd.socket.getsockname()
             url = "http://" + sa[0] + ":" + str(sa[1]) + "/" + filename
             if self.open_in_browser:
                 webbrowser.open(url, new=2)
             print("Serving your slides on " + url)
             print("Use Control-C to stop this server.")
             httpd.serve_forever()
         except KeyboardInterrupt:
             print("The server is shut down.")

IPython/nbconvert/transformers/base.py

@@ -1,110 +1,110 b''
 """
 Module that re-groups transformer that would be applied to ipynb files
 before going through the templating machinery.
 
 It exposes a convenient class to inherit from to access configurability.
 """
 #-----------------------------------------------------------------------------
 # 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 ..utils.base import NbConvertBase
 from IPython.utils.traitlets import Bool
 
 #-----------------------------------------------------------------------------
 # Classes and Functions
 #-----------------------------------------------------------------------------
 
 class Transformer(NbConvertBase):
     """ A configurable transformer
 
     Inherit from this class if you wish to have configurability for your
     transformer.
 
     Any configurable traitlets this class exposed will be configurable in profiles
     using c.SubClassName.atribute=value
 
     you can overwrite :meth:`transform_cell` to apply a transformation independently on each cell
-    or :meth:`call` if you prefer your own logic. See corresponding docstring for informations.
+    or :meth:`transform` if you prefer your own logic. See corresponding docstring for informations.
 
     Disabled by default and can be enabled via the config by
         'c.YourTransformerName.enabled = True'
     """
     
     enabled = Bool(False, config=True)
 
     def __init__(self, **kw):
         """
         Public constructor
         
         Parameters
         ----------
         config : Config
             Configuration file structure
         **kw : misc
             Additional arguments
         """
         
         super(Transformer, self).__init__(**kw)
 
        
     def __call__(self, nb, resources):
         if self.enabled:
-            return self.call(nb,resources)
+            return self.transform(nb,resources)
         else:
             return nb, resources
 
 
-    def call(self, nb, resources):
+    def transform(self, nb, resources):
         """
         Transformation to apply on each notebook.
         
         You should return modified nb, resources.
         If you wish to apply your transform on each cell, you might want to 
         overwrite transform_cell method instead.
         
         Parameters
         ----------
         nb : NotebookNode
             Notebook being converted
         resources : dictionary
             Additional resources used in the conversion process.  Allows
             transformers to pass variables into the Jinja engine.
         """
         self.log.debug("Applying transform: %s", self.__class__.__name__)
         try :
             for worksheet in nb.worksheets:
                 for index, cell in enumerate(worksheet.cells):
                     worksheet.cells[index], resources = self.transform_cell(cell, resources, index)
             return nb, resources
         except NotImplementedError:
             raise NotImplementedError('should be implemented by subclass')
 
 
     def transform_cell(self, cell, resources, index):
         """
         Overwrite if you want to apply a transformation on each cell.  You 
         should return modified cell and resource dictionary.
         
         Parameters
         ----------
         cell : NotebookNode cell
             Notebook cell being processed
         resources : dictionary
             Additional resources used in the conversion process.  Allows
             transformers to pass variables into the Jinja engine.
         index : int
             Index of the cell being processed
         """
 
         raise NotImplementedError('should be implemented by subclass')
         return cell, resources
 

IPython/nbconvert/transformers/csshtmlheader.py

@@ -1,106 +1,106 b''
 """Module that pre-processes the notebook for export to HTML.
 """
 #-----------------------------------------------------------------------------
 # 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 os
 import io
 
 from pygments.formatters import HtmlFormatter
 
 from IPython.utils import path
 
 from .base import Transformer
 
 from IPython.utils.traitlets import Unicode
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 class CSSHTMLHeaderTransformer(Transformer):
     """
     Transformer used to pre-process notebook for HTML output.  Adds IPython notebook
     front-end CSS and Pygments CSS to HTML output.
     """
 
     header = []
 
     highlight_class = Unicode('.highlight', config=True,
                               help="CSS highlight class identifier")
 
     def __init__(self, config=None, **kw):
         """
         Public constructor
         
         Parameters
         ----------
         config : Config
             Configuration file structure
         **kw : misc
             Additional arguments
         """
         
         super(CSSHTMLHeaderTransformer, self).__init__(config=config, **kw)
 
         if self.enabled :
             self._regen_header()
 
 
-    def call(self, nb, resources):
+    def transform(self, nb, resources):
         """Fetch and add CSS to the resource dictionary
 
         Fetch CSS from IPython and Pygments to add at the beginning
         of the html files.  Add this css in resources in the 
         "inlining.css" key
         
         Parameters
         ----------
         nb : NotebookNode
             Notebook being converted
         resources : dictionary
             Additional resources used in the conversion process.  Allows
             transformers to pass variables into the Jinja engine.
         """
         
         resources['inlining'] = {}
         resources['inlining']['css'] = self.header
         
         return nb, resources
 
 
     def _regen_header(self):
         """ 
         Fills self.header with lines of CSS extracted from IPython 
         and Pygments.
         """
         
         #Clear existing header.
         header = []
         
         #Construct path to IPy CSS
         sheet_filename = os.path.join(path.get_ipython_package_dir(), 
             'html', 'static', 'style', 'style.min.css')
         
         #Load style CSS file.
         with io.open(sheet_filename, encoding='utf-8') as file:
             file_text = file.read()
             header.append(file_text)
 
         #Add pygments CSS
         formatter = HtmlFormatter()
         pygments_css = formatter.get_style_defs(self.highlight_class)
         header.append(pygments_css)
 
         #Set header        
         self.header = header
 

IPython/nbconvert/transformers/revealhelp.py

@@ -1,94 +1,94 b''
 """Module that pre-processes the notebook for export via Reveal.
 """
 #-----------------------------------------------------------------------------
 # 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 os
 import urllib2
 
 from .base import Transformer
 from IPython.utils.traitlets import Unicode, Bool
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 class RevealHelpTransformer(Transformer):
 
     url_prefix = Unicode('//cdn.jsdelivr.net/reveal.js/2.4.0',
                          config=True,
                          help="""If you want to use a local reveal.js library,
                          use 'url_prefix':'reveal.js' in your config object.""")
 
     speaker_notes = Bool(False, 
                          config=True, 
                          help="""If you want to use the speaker notes 
                          set this to True.""")
 
-    def call(self, nb, resources):
+    def transform(self, nb, resources):
         """
         Called once to 'transform' contents of the notebook.
 
         Parameters
         ----------
         nb : NotebookNode
             Notebook being converted
         resources : dictionary
             Additional resources used in the conversion process.  Allows
             transformers to pass variables into the Jinja engine.
         """
 
         for worksheet in nb.worksheets :
             for index, cell in enumerate(worksheet.cells):
 
                 #Make sure the cell has slideshow metadata.
                 cell.metadata.align_type = cell.get('metadata', {}).get('slideshow', {}).get('align_type', 'Left')
                 cell.metadata.slide_type = cell.get('metadata', {}).get('slideshow', {}).get('slide_type', '-')
 
                 #Get the slide type.  If type is start of subslide or slide,
                 #end the last subslide/slide.
                 if cell.metadata.slide_type in ['slide']:
                     worksheet.cells[index - 1].metadata.slide_helper = 'slide_end'
                 if cell.metadata.slide_type in ['subslide']:
                     worksheet.cells[index - 1].metadata.slide_helper = 'subslide_end'
 
 
         if not isinstance(resources['reveal'], dict):
             resources['reveal'] = {}
         resources['reveal']['url_prefix'] = self.url_prefix
         resources['reveal']['notes_prefix'] = self.url_prefix
 
         cdn = 'http://cdn.jsdelivr.net/reveal.js/2.4.0'
         local = 'local'
         html_path = 'plugin/notes/notes.html'
         js_path = 'plugin/notes/notes.js'
 
         html_infile = os.path.join(cdn, html_path)
         js_infile = os.path.join(cdn, js_path)
         html_outfile = os.path.join(local, html_path)
         js_outfile = os.path.join(local, js_path)
 
         if self.speaker_notes:
             if 'outputs' not in resources:
                 resources['outputs'] = {}
             resources['outputs'][html_outfile] = self.notes_helper(html_infile)
             resources['outputs'][js_outfile] = self.notes_helper(js_infile)
             resources['reveal']['notes_prefix'] = local
 
         return nb, resources
 
     def notes_helper(self, infile):
         """Helper function to get the content from an url."""
 
         content = urllib2.urlopen(infile).read()
 
         return content

IPython/nbconvert/transformers/sphinx.py

@@ -1,264 +1,264 b''
 """Module that allows custom Sphinx parameters to be set on the notebook and
 on the 'other' object passed into Jinja.  Called prior to Jinja conversion
 process.
 """
 #-----------------------------------------------------------------------------
 # 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 os.path
 
 # Used to set the default date to today's date 
 from datetime import date 
 
 # Third-party imports
 # Needed for Pygments latex definitions.
 from pygments.formatters import LatexFormatter
 
 # Our own imports
 # Configurable traitlets
 from IPython.utils.traitlets import Unicode, Bool
 
 # Needed to override transformer
 from .base import (Transformer)
 
 from IPython.nbconvert.utils import console  
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 class SphinxTransformer(Transformer):
     """
     Sphinx utility transformer.
 
     This transformer is used to set variables needed by the latex to build
     Sphinx stylized templates.
     """
     
     interactive = Bool(False, config=True, help="""
         Allows you to define whether or not the Sphinx exporter will prompt
         you for input during the conversion process.  If this is set to false,
         the author, version, release, date, and chapter_style traits should
         be set.
         """)
     
     author = Unicode("Unknown Author", config=True, help="Author name")
     
     version = Unicode("", config=True, help="""
         Version number
         You can leave this blank if you do not want to render a version number.
         Example: "1.0.0"
         """)
     
     release = Unicode("", config=True, help="""
         Release name
         You can leave this blank if you do not want to render a release name.
         Example: "Rough Draft"
         """)
     
     publish_date = Unicode("", config=True, help="""
         Publish date
         This is the date to render on the document as the publish date.
         Leave this blank to default to todays date.  
         Example: "June 12, 1990"
         """)
     
     chapter_style = Unicode("Bjarne", config=True, help="""
         Sphinx chapter style
         This is the style to use for the chapter headers in the document.
         You may choose one of the following:
             "Bjarne"    (default)
             "Lenny"
             "Glenn"
             "Conny"
             "Rejne"
             "Sonny"    (used for international documents)
         """)
     
     output_style = Unicode("notebook", config=True, help="""
         Nbconvert Ipython
         notebook input/output formatting style.
         You may choose one of the following:
             "simple     (recommended for long code segments)"
             "notebook"  (default)
         """)
     
     center_output = Bool(False, config=True, help="""
         Optional attempt to center all output.  If this is false, no additional
         formatting is applied.
         """)
     
     use_headers = Bool(True, config=True, help="""
         Whether not a header should be added to the document.
         """)
     
     #Allow the user to override the title of the notebook (useful for
     #fancy document titles that the file system doesn't support.)
     overridetitle = Unicode("", config=True, help="")
 
     
-    def call(self, nb, resources):
+    def transform(self, nb, resources):
         """
         Sphinx transformation to apply on each notebook.
         
         Parameters
         ----------
         nb : NotebookNode
             Notebook being converted
         resources : dictionary
             Additional resources used in the conversion process.  Allows
             transformers to pass variables into the Jinja engine.
         """
         # import sphinx here, so that sphinx is not a dependency when it's not used
         import sphinx
          
         # TODO: Add versatile method of additional notebook metadata.  Include
         #       handling of multiple files.  For now use a temporay namespace,
         #       '_draft' to signify that this needs to change.
         if not isinstance(resources["sphinx"], dict):
             resources["sphinx"] = {}
 
         if self.interactive:
             
             # Prompt the user for additional meta data that doesn't exist currently
             # but would be usefull for Sphinx.
             resources["sphinx"]["author"] = self._prompt_author()
             resources["sphinx"]["version"] = self._prompt_version()
             resources["sphinx"]["release"] = self._prompt_release()
             resources["sphinx"]["date"] = self._prompt_date()
             
             # Prompt the user for the document style.
             resources["sphinx"]["chapterstyle"] = self._prompt_chapter_title_style()
             resources["sphinx"]["outputstyle"] = self._prompt_output_style()
             
             # Small options
             resources["sphinx"]["centeroutput"] = console.prompt_boolean("Do you want to center the output? (false)", False)
             resources["sphinx"]["header"] = console.prompt_boolean("Should a Sphinx document header be used? (true)", True)
         else:
             
             # Try to use the traitlets.
             resources["sphinx"]["author"] = self.author
             resources["sphinx"]["version"] = self.version
             resources["sphinx"]["release"] = self.release
             
             # Use todays date if none is provided.
             if self.publish_date:
                 resources["sphinx"]["date"] = self.publish_date
             elif len(resources['metadata']['modified_date'].strip()) == 0:
                 resources["sphinx"]["date"] = date.today().strftime("%B %-d, %Y")
             else:
                 resources["sphinx"]["date"] = resources['metadata']['modified_date']
             
             # Sphinx traitlets.
             resources["sphinx"]["chapterstyle"] = self.chapter_style
             resources["sphinx"]["outputstyle"] = self.output_style
             resources["sphinx"]["centeroutput"] = self.center_output
             resources["sphinx"]["header"] = self.use_headers
             
         # Find and pass in the path to the Sphinx dependencies.
         resources["sphinx"]["texinputs"] = os.path.realpath(os.path.join(sphinx.package_dir, "texinputs"))
         
         # Generate Pygments definitions for Latex 
         resources["sphinx"]["pygment_definitions"] = self._generate_pygments_latex_def()
         
         if not (self.overridetitle == None or len(self.overridetitle.strip()) == 0):
             resources['metadata']['name'] = self.overridetitle
         
         # End
         return nb, resources 
     
     
     def _generate_pygments_latex_def(self):
         """
         Generate the pygments latex definitions that allows pygments
         to work in latex.
         """
         
         return LatexFormatter().get_style_defs()       
     
     
     def _prompt_author(self):
         """
         Prompt the user to input an Author name
         """
         return  console.input("Author name: ")
     
     
     def _prompt_version(self):
         """
         prompt the user to enter a version number
         """
         return  console.input("Version (ie ""1.0.0""): ")
     
     
     def _prompt_release(self):
         """
         Prompt the user to input a release name
         """
         
         return  console.input("Release Name (ie ""Rough draft""): ")
     
     
     def _prompt_date(self, resources):
         """
         Prompt the user to enter a date
         """
         
         if resources['metadata']['modified_date']:
             default_date = resources['metadata']['modified_date']
         else:
             default_date = date.today().strftime("%B %-d, %Y")
             
         user_date = console.input("Date (deafults to \"" + default_date + "\"): ")
         if len(user_date.strip()) == 0:
             user_date = default_date
         return user_date
     
     
     def _prompt_output_style(self):
         """
         Prompts the user to pick an IPython output style.
         """
         
         # Dictionary of available output styles
         styles = {1: "simple",
                   2: "notebook"}
         
         #Append comments to the menu when displaying it to the user.
         comments = {1: "(recommended for long code segments)",
                     2: "(default)"}
         
         return console.prompt_dictionary(styles, default_style=2, menu_comments=comments)
     
     
     def _prompt_chapter_title_style(self):
         """
         Prompts the user to pick a Sphinx chapter style
         """
         
         # Dictionary of available Sphinx styles
         styles = {1: "Bjarne",
                   2: "Lenny",
                   3: "Glenn",
                   4: "Conny",
                   5: "Rejne",
                   6: "Sonny"}
         
         #Append comments to the menu when displaying it to the user.
         comments = {1: "(default)",
                     6: "(for international documents)"}
         
         return console.prompt_dictionary(styles, menu_comments=comments)
 

docs/source/whatsnew/development.rst

@@ -1,12 +1,16 b''
 =====================
  Development version
 =====================
 
 This document describes in-flight development work.
 
 
 Backwards incompatible changes
 ------------------------------
 
 * Python 2.6 and 3.2 are no longer supported: the minimum required
   Python versions are now 2.7 and 3.3.
+* The `call` methods for nbconvert transformers has been renamed to
+  `transform`.
+* The `call` methods of nbconvert post-processsors have been renamed to
+  `postprocess`.