Warning

This documentation is for an old version of IPython. You can find docs for newer versions here.

Integrating with GUI event loops

When the user types %gui qt, IPython integrates itself with the Qt event loop, so you can use both a GUI and an interactive prompt together. IPython supports a number of common GUI toolkits, but from IPython 3.0, it is possible to integrate other event loops without modifying IPython itself.

Terminal IPython handles event loops very differently from the IPython kernel, so different steps are needed to integrate with each.

Event loops in the terminal

In the terminal, IPython uses a blocking Python function to wait for user input. However, the Python C API provides a hook, PyOS_InputHook(), which is called frequently while waiting for input. This can be set to a function which briefly runs the event loop and then returns.

IPython provides Python level wrappers for setting and resetting this hook. To use them, subclass IPython.lib.inputhook.InputHookBase, and define an enable(app=None) method, which initialises the event loop and calls self.manager.set_inputhook(f) with a function which will briefly run the event loop before exiting. Decorate the class with a call to IPython.lib.inputhook.register():

from IPython.lib.inputhook import register, InputHookBase

@register('clutter')
class ClutterInputHook(InputHookBase):
    def enable(self, app=None):
        self.manager.set_inputhook(inputhook_clutter)

You can also optionally define a disable() method, taking no arguments, if there are extra steps needed to clean up. IPython will take care of resetting the hook, whether or not you provide a disable method.

The simplest way to define the hook function is just to run one iteration of the event loop, or to run until no events are pending. Most event loops provide some mechanism to do one of these things. However, the GUI may lag slightly, because the hook is only called every 0.1 seconds. Alternatively, the hook can keep running the event loop until there is input ready on stdin. IPython provides a function to facilitate this:

IPython.lib.inputhook.stdin_ready()

Returns True if there is something ready to read on stdin.

If this is the case, the hook function should return immediately.

This is implemented for Windows and POSIX systems - on other platforms, it always returns True, so that the hook always gives Python a chance to check for input.

Event loops in the kernel

The kernel runs its own event loop, so it’s simpler to integrate with others. IPython allows the other event loop to take control, but it must call IPython.kernel.zmq.kernelbase.Kernel.do_one_iteration() periodically.

To integrate with this, write a function that takes a single argument, the IPython kernel instance, arranges for your event loop to call kernel.do_one_iteration() at least every kernel._poll_interval seconds, and starts the event loop.

Decorate this function with IPython.kernel.zmq.eventloops.register_integration(), passing in the names you wish to register it for. Here is a slightly simplified version of the Tkinter integration already included in IPython:

@register_integration('tk')
def loop_tk(kernel):
    """Start a kernel with the Tk event loop."""
    from tkinter import Tk

    # Tk uses milliseconds
    poll_interval = int(1000*kernel._poll_interval)
    # For Tkinter, we create a Tk object and call its withdraw method.
    class Timer(object):
        def __init__(self, func):
            self.app = Tk()
            self.app.withdraw()
            self.func = func

        def on_timer(self):
            self.func()
            self.app.after(poll_interval, self.on_timer)

        def start(self):
            self.on_timer()  # Call it once to get things going.
            self.app.mainloop()

    kernel.timer = Timer(kernel.do_one_iteration)
    kernel.timer.start()

Some event loops can go one better, and integrate checking for messages on the kernel’s ZMQ sockets, making the kernel more responsive than plain polling. How to do this is outside the scope of this document; if you are interested, look at the integration with Qt in IPython.kernel.zmq.eventloops.