add IPython.start_kernel

minrk · minrk · commit a10986ac3e0d · 2013-07-04T12:23:31.000-07:00
for symmetry
diff --git a/IPython/__init__.py b/IPython/__init__.py
@@ -61,6 +61,12 @@
 def embed_kernel(module=None, local_ns=None, **kwargs):
     """Embed and start an IPython kernel in a given scope.
     
+    If you don't want the kernel to initialize the namespace
+    from the scope of the surrounding function,
+    and/or you want to load full IPython configuration,
+    you probably want `IPython.start_kernel()` instead.
+
+    
     Parameters
     ----------
     module : ModuleType, optional
@@ -112,3 +118,30 @@ def start_ipython(argv=None, **kwargs):
     """
     from IPython.terminal.ipapp import launch_new_instance
     return launch_new_instance(argv=argv, **kwargs)
+
+def start_kernel(argv=None, **kwargs):
+    """Launch a normal IPython kernel instance (as opposed to embedded)
+    
+    `IPython.embed_kernel()` puts a shell in a particular calling scope,
+    such as a function or method for debugging purposes,
+    which is often not desirable.
+    
+    `start_kernel()` does full, regular IPython initialization,
+    including loading startup files, configuration, etc.
+    much of which is skipped by `embed()`.
+    
+    Parameters
+    ----------
+    
+    argv : list or None, optional
+        If unspecified or None, IPython will parse command-line options from sys.argv.
+        To prevent any command-line parsing, pass an empty list: `argv=[]`.
+    user_ns : dict, optional
+        specify this dictionary to initialize the IPython user namespace with particular values.
+    kwargs : various, optional
+        Any other kwargs will be passed to the Application constructor,
+        such as `config`.
+    """
+    from IPython.kernel.zmq.kernelapp import launch_new_instance
+    return launch_new_instance(argv=argv, **kwargs)
+    
