Making simple Python wrapper kernels

You can reuse IPython's kernel machinery to easily make new kernels. This is useful for languages that have Python bindings, such as Hy (see Calysto Hy), or languages where the REPL can be controlled in a tty using pexpect, such as bash.

The Metakernel library makes it easier to write a wrapper kernel that includes a base set of line and cell magics. It also has a ProcessKernel subclass that makes it easy to write kernels that use pexpect. See Octave Kernel as an example.

If releasing a wrapper kernel as a Python package, see the steps in packaging-kernels.

Required steps

Subclass ipykernel.kernelbase.Kernel, and implement the following methods and attributes:

To launch your kernel, add this at the end of your module

if __name__ == '__main__':
    from ipykernel.kernelapp import IPKernelApp
    IPKernelApp.launch_instance(kernel_class=MyKernel)

Now create a JSON kernel spec file and install it using jupyter kernelspec install </path/to/kernel>. Place your kernel module anywhere Python can import it (try current directory for testing). Finally, you can run your kernel using jupyter console --kernel <mykernelname>. Note that <mykernelname> in the below example is echo.

Example

echokernel.py will simply echo any input it's given to stdout

from ipykernel.kernelbase import Kernel

class EchoKernel(Kernel):
    implementation = 'Echo'
    implementation_version = '1.0'
    language = 'no-op'
    language_version = '0.1'
    language_info = {
        'name': 'Any text',
        'mimetype': 'text/plain',
        'file_extension': '.txt',
    }
    banner = "Echo kernel - as useful as a parrot"

    def do_execute(self, code, silent, store_history=True, user_expressions=None,
                   allow_stdin=False):
        if not silent:
            stream_content = {'name': 'stdout', 'text': code}
            self.send_response(self.iopub_socket, 'stream', stream_content)

        return {'status': 'ok',
                # The base class increments the execution count
                'execution_count': self.execution_count,
                'payload': [],
                'user_expressions': {},
               }

if __name__ == '__main__':
    from ipykernel.kernelapp import IPKernelApp
    IPKernelApp.launch_instance(kernel_class=EchoKernel)

Here's the Kernel spec kernel.json file for this

{"argv":["python","-m","echokernel", "-f", "{connection_file}"],
 "display_name":"Echo"
}

Optional steps

You can override a number of other methods to improve the functionality of your kernel. All of these methods should return a dictionary as described in the relevant section of the messaging spec.