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, :c:func:`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 :class:`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 :func:`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:

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 :meth:`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 :func:`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 :mod:`IPython.kernel.zmq.eventloops`.