Merge pull request #1862 from minrk/bindkernel

Minor bind_kernel improvements.

* `bind_kernel()` on an already bound kernel is a no-op.
* `%qtconsole` on an engine implies bind_kernel
* add bind_kernel, and `%px %qtconsole` to docs

IPython/parallel/__init__.py

@@ -20,6 +20,7 b' import warnings'
 
 import zmq
 
+from IPython.config.configurable import MultipleInstanceError
 from IPython.zmq import check_for_zmq
 
 if os.name == 'nt':
@@ -51,12 +52,23 b' def bind_kernel(**kwargs):'
     
     This function returns immediately.
     """
+    from IPython.zmq.ipkernel import IPKernelApp
     from IPython.parallel.apps.ipengineapp import IPEngineApp
+    
+    # first check for IPKernelApp, in which case this should be a no-op
+    # because there is already a bound kernel
+    if IPKernelApp.initialized() and isinstance(IPKernelApp._instance, IPKernelApp):
+        return
+    
     if IPEngineApp.initialized():
+        try:
         app = IPEngineApp.instance()
+        except MultipleInstanceError:
+            pass
     else:
-        raise RuntimeError("Must be called from an IPEngineApp instance")
-    
     return app.bind_kernel(**kwargs)
 
+    raise RuntimeError("bind_kernel be called from an IPEngineApp instance")
+    
+
 

IPython/zmq/zmqshell.py

@@ -420,6 +420,16 b' class KernelMagics(Magics):'
         Useful for connecting a qtconsole to running notebooks, for better
         debugging.
         """
+        
+        # %qtconsole should imply bind_kernel for engines:
+        try:
+            from IPython.parallel import bind_kernel
+        except ImportError:
+            # technically possible, because parallel has higher pyzmq min-version
+            pass
+        else:
+            bind_kernel()
+        
         try:
             p = connect_qtconsole(argv=arg_split(arg_s, os.name=='posix'))
         except Exception as e:

docs/source/parallel/parallel_multiengine.txt

@@ -554,6 +554,64 b' on the engines until you do ``%autopx`` again.'
     Auto Parallel Disabled
 
 
+Engines as Kernels
+******************
+
+Engines are really the same object as the Kernels used elsewhere in IPython,
+with the minor exception that engines connect to a controller, while regular kernels
+bind their sockets, listening for connections from a QtConsole or other frontends.
+
+Sometimes for debugging or inspection purposes, you would like a QtConsole connected
+to an engine for more direct interaction.  You can do this by first instructing
+the Engine to *also* bind its kernel, to listen for connections:
+
+.. sourcecode:: ipython
+
+    In [50]: %px from IPython.parallel import bind_kernel; bind_kernel()
+
+Then, if your engines are local, you can start a qtconsole right on the engine(s):
+
+.. sourcecode:: ipython
+
+    In [51]: %px %qtconsole
+
+Careful with this one, because if your view is of 16 engines it will start 16 QtConsoles!
+
+Or you can view just the connection info, and work out the right way to connect to the engines,
+depending on where they live and where you are:
+
+.. sourcecode:: ipython
+
+    In [51]: %px %connect_info
+    Parallel execution on engine(s): [0, 1, 2, 3]
+    [stdout:0] 
+    {
+      "stdin_port": 60387, 
+      "ip": "127.0.0.1", 
+      "hb_port": 50835, 
+      "key": "eee2dd69-7dd3-4340-bf3e-7e2e22a62542", 
+      "shell_port": 55328, 
+      "iopub_port": 58264
+    }
+
+    Paste the above JSON into a file, and connect with:
+        $> ipython <app> --existing <file>
+    or, if you are local, you can connect with just:
+        $> ipython <app> --existing kernel-60125.json 
+    or even just:
+        $> ipython <app> --existing 
+    if this is the most recent IPython session you have started.
+    [stdout:1] 
+    {
+      "stdin_port": 61869,
+    ...
+
+.. note::
+
+    ``%qtconsole`` will call :func:`bind_kernel` on an engine if it hasn't been done already,
+    so you can often skip that first step.
+
+
 Moving Python objects around
 ============================