improve logging in nbconvert preprocessors

also cleanup spelling and grammar in a few docstrings

IPython/nbconvert/preprocessors/base.py

@@ -1,111 +1,93 b''
-"""
-Module that re-groups preprocessor 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.
-#-----------------------------------------------------------------------------
+"""Base class for preprocessors"""
 
-#-----------------------------------------------------------------------------
-# Imports
-#-----------------------------------------------------------------------------
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
 
 from ..utils.base import NbConvertBase
 from IPython.utils.traitlets import Bool
 
-#-----------------------------------------------------------------------------
-# Classes and Functions
-#-----------------------------------------------------------------------------
 
 class Preprocessor(NbConvertBase):
     """ A configurable preprocessor
 
     Inherit from this class if you wish to have configurability for your
     preprocessor.
 
     Any configurable traitlets this class exposed will be configurable in
-    profiles using c.SubClassName.atribute=value
+    profiles using c.SubClassName.attribute = value
 
     you can overwrite :meth:`preprocess_cell` to apply a transformation
     independently on each cell or :meth:`preprocess` if you prefer your own
     logic. See corresponding docstring for informations.
 
     Disabled by default and can be enabled via the config by
         'c.YourPreprocessorName.enabled = True'
     """
     
     enabled = Bool(False, config=True)
 
     def __init__(self, **kw):
         """
         Public constructor
         
         Parameters
         ----------
         config : Config
             Configuration file structure
         **kw : misc
             Additional arguments
         """
         
         super(Preprocessor, self).__init__(**kw)
 
        
     def __call__(self, nb, resources):
         if self.enabled:
+            self.log.debug("Applying preprocessor: %s", self.__class__.__name__)
             return self.preprocess(nb,resources)
         else:
             return nb, resources
 
 
     def preprocess(self, nb, resources):
         """
         Preprocessing to apply on each notebook.
         
-        You should return modified nb, resources.
+        Must return modified nb, resources.
+        
         If you wish to apply your preprocessing to each cell, you might want
-        to overwrite preprocess_cell method instead.
+        to override preprocess_cell method instead.
         
         Parameters
         ----------
         nb : NotebookNode
             Notebook being converted
         resources : dictionary
             Additional resources used in the conversion process.  Allows
             preprocessors to pass variables into the Jinja engine.
         """
-        self.log.debug("Applying preprocess: %s", self.__class__.__name__)
-        try :
-            for worksheet in nb.worksheets:
-                for index, cell in enumerate(worksheet.cells):
-                    worksheet.cells[index], resources = self.preprocess_cell(cell, resources, index)
-            return nb, resources
-        except NotImplementedError:
-            raise NotImplementedError('should be implemented by subclass')
+        for worksheet in nb.worksheets:
+            for index, cell in enumerate(worksheet.cells):
+                worksheet.cells[index], resources = self.preprocess_cell(cell, resources, index)
+        return nb, resources
 
 
     def preprocess_cell(self, cell, resources, index):
         """
-        Overwrite if you want to apply some preprocessing to each cell.  You 
-        should return modified cell and resource dictionary.
+        Override if you want to apply some preprocessing to each cell.
+        Must return modified cell and resource dictionary.
         
         Parameters
         ----------
         cell : NotebookNode cell
             Notebook cell being processed
         resources : dictionary
             Additional resources used in the conversion process.  Allows
             preprocessors 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/preprocessors/coalescestreams.py

@@ -1,85 +1,77 b''
-"""Module that allows latex output notebooks to be conditioned before
-they are converted.  Exposes a decorator (@cell_preprocessor) in
-addition to the coalesce_streams pre-proccessor.
-"""
-#-----------------------------------------------------------------------------
-# Copyright (c) 2013, the IPython Development Team.
-#
+"""Preprocessor for merging consecutive stream outputs for easier handling."""
+
+# Copyright (c) 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 re
 
-#-----------------------------------------------------------------------------
-# Functions
-#-----------------------------------------------------------------------------
 def cell_preprocessor(function):
     """
     Wrap a function to be executed on all cells of a notebook
     
     The wrapped function should have these parameters:
     
     cell : NotebookNode cell
         Notebook cell being processed
     resources : dictionary
         Additional resources used in the conversion process.  Allows
         preprocessors to pass variables into the Jinja engine.
     index : int
         Index of the cell being processed
     """
     
     def wrappedfunc(nb, resources):
-        for worksheet in nb.worksheets :
+        from IPython.config import Application
+        if Application.initialized():
+            Application.instance().log.debug(
+                "Applying preprocessor: %s", function.__name__
+            )
+        for worksheet in nb.worksheets:
             for index, cell in enumerate(worksheet.cells):
                 worksheet.cells[index], resources = function(cell, resources, index)
         return nb, resources
     return wrappedfunc
 
 cr_pat = re.compile(r'.*\r(?=[^\n])')
 
 @cell_preprocessor
 def coalesce_streams(cell, resources, index):
     """
     Merge consecutive sequences of stream output into single stream
     to prevent extra newlines inserted at flush calls
     
     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
     """
     
     outputs = cell.get('outputs', [])
     if not outputs:
         return cell, resources
     
     last = outputs[0]
     new_outputs = [last]
     for output in outputs[1:]:
         if (output.output_type == 'stream' and
             last.output_type == 'stream' and
             last.stream == output.stream
         ):
             last.text += output.text
 
         else:
             new_outputs.append(output)
             last = output
     
     # process \r characters
     for output in new_outputs:
         if output.output_type == 'stream':
             output.text = cr_pat.sub('', output.text)
 
     cell.outputs = new_outputs
     return cell, resources