Allow the execute preprocessor to make use of an existing kernel

nbconvert/preprocessors/execute.py

@@ -157,7 +157,7 @@ class ExecutePreprocessor(Preprocessor):
             """
         )
     ).tag(config=True)
-    
+
     @default('kernel_name')
     def _kernel_name_default(self):
         try:
@@ -167,7 +167,6 @@ def _kernel_name_default(self):
                                  'the ExecutePreprocessor and you have not set '
                                  'self.nb to be able to use that to infer the '
                                  'kernel_name.')
-
 
     raise_on_iopub_timeout = Bool(False,
         help=dedent(
@@ -252,7 +251,7 @@ def start_new_kernel(self, **kwargs):
         km = self.kernel_manager_class(kernel_name=self.kernel_name,
                                        config=self.config)
         km.start_kernel(extra_arguments=self.extra_arguments, **kwargs)
-                             
+
         kc = km.client()
         kc.start_channels()
         try:
@@ -263,18 +262,18 @@ def start_new_kernel(self, **kwargs):
             raise
         kc.allow_stdin = False
         return km, kc
-    
+
     @contextmanager
-    def setup_preprocessor(self, nb, resources):
+    def setup_preprocessor(self, nb, resources, kernel=None):
         """
         Context manager for setting up the class to execute a notebook.
 
-        The assigns `nb` to `self.nb` where it will be modified in-place. It also creates 
+        The assigns `nb` to `self.nb` where it will be modified in-place. It also creates
         and assigns the Kernel Manager (`self.km`) and Kernel Client(`self.kc`).
-        
+
         It is intended to yield to a block that will execute codeself.
-        
-        When control returns from the yield it stops the client's zmq channels, shuts 
+
+        When control returns from the yield it stops the client's zmq channels, shuts
         down the kernel, and removes the now unused attributes.
 
         Parameters
@@ -285,6 +284,8 @@ def setup_preprocessor(self, nb, resources):
             Additional resources used in the conversion process. For example,
             passing ``{'metadata': {'path': run_path}}`` sets the
             execution path to ``run_path``.
+        kernel : Optional pair for (kernel manager, kernel client)
+            If such a pair is passed, it will be used for code execution.
 
         Returns
         -------
@@ -298,17 +299,21 @@ def setup_preprocessor(self, nb, resources):
         # clear display_id map
         self._display_id_map = {}
 
-        self.km, self.kc = self.start_new_kernel(cwd=path)
-        try:
-            # Yielding unbound args for more easier understanding and downstream consumption 
-            yield nb, self.km, self.kc
-        finally:
-            self.kc.stop_channels()
-            self.km.shutdown_kernel(now=self.shutdown_kernel == 'immediate')
-
-            for attr in ['nb', 'km', 'kc']:
-                delattr(self, attr)
-
+        if kernel is None:
+            self.km, self.kc = self.start_new_kernel(cwd=path)
+            try:
+                # Yielding unbound args for more easier understanding and downstream consumption
+                yield nb, self.km, self.kc
+            finally:
+                self.kc.stop_channels()
+                self.km.shutdown_kernel(now=self.shutdown_kernel == 'immediate')
+
+                for attr in ['nb', 'km', 'kc']:
+                    delattr(self, attr)
+        else:
+            self.km, self.kc = kernel
+            return nb, self.kc
+
     def preprocess(self, nb, resources):
         """
         Preprocess notebook executing each code cell.