.. @+leo-ver=5-thin
.. @+node:ekr.20100805165051.7171: * @file IpythonBridge.txt
.. @@language rest
.. @@tabwidth -4
.. @+all
.. @+node:ekr.20080203101507.1: ** @rst html\IPythonBridge.html
##########################
ILeo: Leo's IPython Bridge
##########################

.. contents::
    :depth: 2
.. @+node:ekr.20080203101507.2: *3* @rst-no-head links
.. Links

.. _ipython:                http://ipython.scipy.org/
.. _IPython:                http://ipython.scipy.org/
.. _`IPython Notebook`:     http://projects.scipy.org/ipython/ipython/wiki/NoteBook
.. _extensionAPI:           http://ipython.scipy.org/moin/IpythonExtensionApi
.. _`The Ipython Extension API`: extensionAPI_
.. _`Scripting Leo with Python`:    scripting.html

.. _`run Leo in a console window`:  installing.html#running-leo-from-a-console-window
.. _`console window`:               installing.html#running-leo-from-a-console-window

.. @+node:vivainio.20080302174639.1: *3* Overview
Leo's --ipython command-line option enables two-way communication
(**ILeo**, the **IPython bridge**) between Leo and IPython: you can run Leo
scripts from IPython, and IPython scripts from Leo.

The level of integration is much deeper than conventional integration in
IDEs. Most notably, you are able to store and manipulate *data* in Leo
nodes, in addition to mere program code--essentially making ILeo a
hierarchical spreadsheet, albeit with non-grid view of the data. The
possibilities of this are endless, and the approach can be applied in wide
range of problem domains with very little actual coding.
.. @+node:vivainio.20080302174639.2: *3* Starting ILeo
To run Leo's IPython bridge:

1. Install IPython 0.8.3 or above.

2. `run Leo in a console window`_ with the --ipython command-line option
   enabled. This option starts an instance of the IPython shell in the
   console. Leo and IPython run simultaneously and independently. Their
   separate event loops do not interfere with each other.
.. @+node:ekr.20131001045038.18981: *3* Running Leo scripts from IPython
*You can run any Leo script from IPython*. The IPython bridge injects an
object called _leo into IPython's namespace. IPython scripts may access
Leo's c and g objects as follows::

    c,g = _leo.c, _leo.g

This allows IPython scripts to do *anything* that a Leo script can do.
Scripts run from IPython *immediately* change Leo, *exactly* as if the
script were run from Leo.

**Important**: the _leo object is an instance of LeoNameSpace class,
defined in leo.core.leoIPython.py. This class allows IPython scripts to
access multiple Leo outlines at once. See the actual code for details.
.. @+node:ekr.20131001045038.18980: *3* Running IPython scripts from Leo
*You can run any IPython script from Leo*. Leo's ipython-exec (Alt-I)
command executes the body text of the presently selected Leo node in the
address space of the IPython shell. Such scripts *immediately* affect the
IPython interpreter.

The IPython bridge sets several global variables *within Leo*, allowing Leo
scripts *complete* access to all of IPython's code and data:

- g.app.ipk.namespace is IPython's namespace.
- g.app.ipk.ipkernel is an IPython IPKernelApp object.
- g.app.ipk.ipkernel.shell is an IPython InteractiveShell object.
.. @+node:ekr.20131001045038.18979: *3* ILeo as an IPython notebook
The IPython bridge turns Leo into another kind of `IPython Notebook`_.
IPython users typically use %edit to produce non-trivial functions/classes
instead of entering them directly on the interactive prompt. But this is a
bit clumsy. With Leo, *every Leo node works like an IPython %edit file*:

- You can execute any Leo node in IPython with <Alt-I> (ipython-exec)
- Saving your Leo outline saves all your IPython scripts.
- You can use Leo as always to organize all your IPython scripts.
.. @+node:ekr.20131001045038.17448: *3* Acknowledgements and history
This idea got started when I (Ville M. Vainio) saw this post by Edward Ream
on IPython developer mailing list:
http://lists.ipython.scipy.org/pipermail/ipython-dev/2008-January/003551.html

I was using FreeMind as mind mapping software, and so I had an immediate
use case for Leo (which, incidentally, is superior to FreeMind as mind
mapper). The wheels started rolling, I got obsessed with the power of this
concept (everything clicked together), and Edwards excitement paralleled
mine. Everything was mind-bogglingly easy/trivial, something that is
typical of all promising technologies.

The goal of close cooperation between Leo and IPython went from vague dream
to completed reality over the span of about 10 days. The IPython bridge has
continued to evolve since then.
.. @-all
.. @-leo
