examples/Notebook/Connecting with the Qt Console.ipynb

{
 "metadata": {
  "name": "",
  "signature": "sha256:9a1dd30de04270174c09ef33ca214e5b15ca3721547420087c1563ad557d78e3"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Connecting to an existing IPython kernel using the Qt Console"
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "The Frontend/Kernel Model"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The traditional IPython (`ipython`) consists of a single process that combines a terminal based UI with the process that runs the users code.\n",
      "\n",
      "While this traditional application still exists, the modern IPython consists of two processes:\n",
      "\n",
      "* Kernel: this is the process that runs the users code.\n",
      "* Frontend: this is the process that provides the user interface where the user types code and sees results.\n",
      "\n",
      "IPython currently has 3 frontends:\n",
      "\n",
      "* Terminal Console (`ipython console`)\n",
      "* Qt Console (`ipython qtconsole`)\n",
      "* Notebook (`ipython notebook`)\n",
      "\n",
      "The Kernel and Frontend communicate over a ZeroMQ/JSON based messaging protocol, which allows multiple Frontends (even of different types) to communicate with a single Kernel. This opens the door for all sorts of interesting things, such as connecting a Console or Qt Console to a Notebook's Kernel.  For example, you may want to connect a Qt console to your Notebook's Kernel and use it as a help\n",
      "browser, calling `??` on objects in the Qt console (whose pager is more flexible than the\n",
      "one in the notebook).  \n",
      "\n",
      "This Notebook describes how you would connect another Frontend to a Kernel that is associated with a Notebook."
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Manual connection"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "To connect another Frontend to a Kernel manually, you first need to find out the connection information for the Kernel using the `%connect_info` magic:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%connect_info"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "{\n",
        "  \"stdin_port\": 52858, \n",
        "  \"ip\": \"127.0.0.1\", \n",
        "  \"hb_port\": 52859, \n",
        "  \"key\": \"7efd45ca-d8a2-41b0-9cea-d9116d0fb883\", \n",
        "  \"shell_port\": 52856, \n",
        "  \"iopub_port\": 52857\n",
        "}\n",
        "\n",
        "Paste the above JSON into a file, and connect with:\n",
        "    $> ipython <app> --existing <file>\n",
        "or, if you are local, you can connect with just:\n",
        "    $> ipython <app> --existing kernel-b3bac7c1-8b2c-4536-8082-8d1df24f99ac.json \n",
        "or even just:\n",
        "    $> ipython <app> --existing \n",
        "if this is the most recent IPython session you have started.\n"
       ]
      }
     ],
     "prompt_number": 6
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "You can see that this magic displays everything you need to connect to this Notebook's Kernel."
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Automatic connection using a new Qt Console"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "You can also start a new Qt Console connected to your current Kernel by using the `%qtconsole` magic. This will detect the necessary connection\n",
      "information and start the Qt Console for you automatically."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "a = 10"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 1
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%qtconsole"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 2
    }
   ],
   "metadata": {}
  }
 ]
}