:func:`display`

IPython provides a function :func:`display` for displaying rich representations of objects if they are available. The IPython display system provides a mechanism for specifying PNG or SVG (and more) representations of objects for GUI frontends. When you enable matplotlib integration via the %matplotlib magic, IPython registers convenient PNG and SVG renderers for matplotlib figures, so you can embed them in your document by calling :func:`display` on one or more of them. This is especially useful for saving your work.

In [4]: from IPython.display import display

In [5]: plt.plot(range(5)) # plots in the matplotlib window

In [6]: display(plt.gcf()) # embeds the current figure in the qtconsole

In [7]: display(*getfigs()) # embeds all active figures in the qtconsole

If you have a reference to a matplotlib figure object, you can always display that specific figure:

In [1]: f = plt.figure()

In [2]: plt.plot(np.rand(100))
Out[2]: [<matplotlib.lines.Line2D at 0x7fc6ac03dd90>]

In [3]: display(f)

# Plot is shown here

In [4]: plt.title('A title')
Out[4]: <matplotlib.text.Text at 0x7fc6ac023450>

In [5]: display(f)

# Updated plot with title is shown here.

--matplotlib inline

If you want to have all of your figures embedded in your session, instead of calling :func:`display`, you can specify --matplotlib inline when you start the console, and each time you make a plot, it will show up in your document, as if you had called :func:`display(fig)`.

The inline backend can use either SVG or PNG figures (PNG being the default). It also supports the special key 'retina', which is 2x PNG for high-DPI displays. To switch between them, set the InlineBackend.figure_format configurable in a config file, or via the %config magic:

In [10]: %config InlineBackend.figure_format = 'svg'

By default, IPython closes all figures at the completion of each execution. This means you don't have to manually close figures, which is less convenient when figures aren't attached to windows with an obvious close button. It also means that the first matplotlib call in each cell will always create a new figure:

In [11]: plt.plot(range(100))
<single-line plot>

In [12]: plt.plot([1,3,2])
<another single-line plot>

However, it does prevent the list of active figures surviving from one input cell to the next, so if you want to continue working with a figure, you must hold on to a reference to it:

In [11]: fig = gcf()
   ....: fig.plot(rand(100))
<plot>
In [12]: fig.title('Random Title')
<redraw plot with title>

This behavior is controlled by the :attr:`InlineBackend.close_figures` configurable, and if you set it to False, via %config or config file, then IPython will not close figures, and tools like :func:`gcf`, :func:`gca`, :func:`getfigs` will behave the same as they do with other backends. You will, however, have to manually close figures:

# close all active figures:
In [13]: [ fig.close() for fig in getfigs() ]

Multiple Consoles

Since the Kernel listens on the network, multiple frontends can connect to it. These do not have to all be qt frontends - any IPython frontend can connect and run code. When you start ipython qtconsole, there will be an output line, like:

[IPKernelApp] To connect another client to this kernel, use:
[IPKernelApp] --existing kernel-12345.json

Other frontends can connect to your kernel, and share in the execution. This is great for collaboration. The --existing flag means connect to a kernel that already exists. Starting other consoles with that flag will not try to start their own kernel, but rather connect to yours. :file:`kernel-12345.json` is a small JSON file with the ip, port, and authentication information necessary to connect to your kernel. By default, this file will be in your default profile's security directory. If it is somewhere else, the output line will print the full path of the connection file, rather than just its filename.

If you need to find the connection info to send, and don't know where your connection file lives, there are a couple of ways to get it. If you are already running an IPython console connected to the kernel, you can use the %connect_info magic to display the information necessary to connect another frontend to the kernel.

In [2]: %connect_info
{
  "stdin_port":50255,
  "ip":"127.0.0.1",
  "hb_port":50256,
  "key":"70be6f0f-1564-4218-8cda-31be40a4d6aa",
  "shell_port":50253,
  "iopub_port":50254
}

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-12345.json
or even just:
    $> ipython <app> --existing
if this is the most recent IPython session you have started.

Otherwise, you can find a connection file by name (and optionally profile) with :func:`IPython.lib.kernel.find_connection_file`:

$> python -c "from IPython.lib.kernel import find_connection_file;\
print find_connection_file('kernel-12345.json')"
/home/you/.ipython/profile_default/security/kernel-12345.json

And if you are using a particular IPython profile:

$> python -c "from IPython.lib.kernel import find_connection_file;\
print find_connection_file('kernel-12345.json', profile='foo')"
/home/you/.ipython/profile_foo/security/kernel-12345.json

You can even launch a standalone kernel, and connect and disconnect Qt Consoles from various machines. This lets you keep the same running IPython session on your work machine (with matplotlib plots and everything), logging in from home, cafés, etc.:

$> ipython kernel
[IPKernelApp] To connect another client to this kernel, use:
[IPKernelApp] --existing kernel-12345.json

This is actually exactly the same as the subprocess launched by the qtconsole, so all the information about connecting to a standalone kernel is identical to that of connecting to the kernel attached to a running console.

$> ipython qtconsole --ip=192.168.1.123

# generate 1024b of random data, and store in a file only you can read:
# (assumes IPYTHONDIR is defined, otherwise use your IPython directory)
$> python -c "import os; print os.urandom(128).encode('base64')" > $IPYTHONDIR/sessionkey
$> chmod 600 $IPYTHONDIR/sessionkey

# instruct IPython to sign messages with that key, instead of a new UUID
$> ipython qtconsole --Session.keyfile=$IPYTHONDIR/sessionkey

user@worker $> ipython kernel
[IPKernelApp] To connect another client to this kernel, use:
[IPKernelApp] --existing kernel-12345.json

user@client $> ipython qtconsole  --ssh=worker --existing /path/to/kernel-12345.json

[IPythonQtConsoleApp] To connect another client via this tunnel, use:
[IPythonQtConsoleApp] --existing kernel-12345-ssh.json

user@worker $> ipython kernel --ip=0.0.0.0
[IPKernelApp] To connect another client to this kernel, use:
[IPKernelApp] --existing kernel-12345.json

user@client $> ipython qtconsole --ssh=login --ip=192.168.1.123 --existing /path/to/kernel-12345.json

[client] $> ssh <server> <localport>:<remoteip>:<remoteport> -f -N

[client] $> ssh machine 12345:127.0.0.1:54321 -f -N

[client] $> ssh login 12345:192.168.1.16:54321 -f -N

Stopping Kernels and Consoles

Since there can be many consoles per kernel, the shutdown mechanism and dialog are probably more complicated than you are used to. Since you don't always want to shutdown a kernel when you close a window, you are given the option to just close the console window or also close the Kernel and all other windows. Note that this only refers to all other local windows, as remote Consoles are not allowed to shutdown the kernel, and shutdowns do not close Remote consoles (to allow for saving, etc.).

Rules:

• Restarting the kernel automatically clears all local Consoles, and prompts remote Consoles about the reset.
• Shutdown closes all local Consoles, and notifies remotes that the Kernel has been shutdown.
• Remote Consoles may not restart or shutdown the kernel.

Embedding the QtConsole in a Qt application

In order to make the QtConsole available to an external Qt GUI application (just as :func:`IPython.embed` enables one to embed a terminal session of IPython in a command-line application), there are a few options:

• First start IPython, and then start the external Qt application from IPython, as described above. Effectively, this embeds your application in IPython rather than the other way round.
• Use :class:`IPython.qt.console.rich_ipython_widget.RichIPythonWidget` in your Qt application. This will embed the console widget in your GUI and start the kernel in a separate process, so code typed into the console cannot access objects in your application.
• Start a standard IPython kernel in the process of the external Qt application. See :file:`examples/lib/ipkernel_qtapp.py` for an example. Due to IPython's two-process model, the QtConsole itself will live in another process with its own QApplication, and thus cannot be embedded in the main GUI.
• Start a special IPython kernel, the :class:`IPython.kernel.inprocess.ipkernel.InProcessKernel`, that allows a QtConsole in the same process. See :file:`examples/inprocess/embedded_qtconsole.py` for an example. While the QtConsole can now be embedded in the main GUI, one cannot connect to the kernel from other consoles as there are no real ZMQ sockets anymore.