Dev: Javascript Events

HombreDeGatos edited this page Jan 10, 2016 · 18 revisions
Clone this wiki locally

(Note: this page is not currently consistent with IPython master)

Javascript events are used to notify unrelated parts of the notebook interface when something happens. For example, if the kernel is busy executing code, it may send an event announcing as such, which can then be picked up by other services, like the notification area. For details on how the events themselves work, see the JQuery documentation.

This page documents the core set of events, and explains when and why they are triggered.

Cell-related events

CellToolbar-related events

Dashboard-related events


When the iPython Notebook browser window opens for the first time and initializes the Dashboard App. The Dashboard App lists the files and notebooks in the current directory. Additionally, it lets you create and open new iPython Notebooks.

Kernel-related events


The kernel has been successfully created or re-created through /api/kernels, but a connection to it has not necessarily been established yet.


The kernel has been successfully created or re-created through /api/sessions, but a connection to it has not necessarily been established yet.


An attempt is being made to reconnect (via websockets) to the kernel after having been disconnected.


A connection has been established to the kernel. This is triggered as soon as all websockets (e.g. to the shell, iopub, and stdin channels) have been opened. This does not necessarily mean that the kernel is ready to do anything yet, though.


The kernel is starting. This is triggered once when the kernel process is starting up, and can be sent as a message by the kernel, or may be triggered by the frontend if it knows the kernel is starting (e.g., it created the kernel and is connected to it, but hasn't been able to communicate with it yet).


Like kernel_idle.Kernel, but triggered after the kernel has fully started up.


The kernel is restarting. This is triggered at the beginning of an restart call to /api/kernels.


The kernel is restarting on its own, which probably also means that something happened to cause the kernel to die. For example, running the following code in the notebook would cause the kernel to autorestart:

import os


The kernel is being interrupted. This is triggered at the beginning of a interrupt call to /api/kernels.


The connection to the kernel has been lost.


Not only was the connection lost, but it was lost due to an error (i.e., we did not tell the websockets to close).


The kernel's execution state is 'idle'.


The kernel's execution state is 'busy'.


The kernel has been manually killed through /api/kernels.


The kernel has been manually killed through /api/sessions.


This is triggered if the kernel dies, and the kernel manager attempts to restart it, but is unable to. For example, the following code run in the notebook will cause the kernel to die and for the kernel manager to be unable to restart it:

import os
from IPython.kernel.connect import get_connection_file
with open(get_connection_file(), 'w') as f:


The kernel could not be started through /api/sessions. This might be because the requested kernel type isn't installed. Another reason for this message is that the kernel died or was killed, but the session wasn't.

Notebook-related events