Kernel providers

Note

This is a new interface under development, and may still change. Not all Jupyter applications use this yet. See :ref:`kernelspecs` for the established way of discovering kernel types.

Creating a kernel provider

By writing a kernel provider, you can extend how Jupyter applications discover and start kernels. For example, you could find kernels in an environment system like conda, or kernels on remote systems which you can access.

To write a kernel provider, subclass :class:`jupyter_client.discovery.KernelProviderBase`, giving your provider an ID and overriding two methods.

.. attribute:: id

   A short string identifying this provider. Cannot contain forward slash
   (``/``).

.. method:: find_kernels()

   Get the available kernel types this provider knows about.
   Return an iterable of 2-tuples: (name, attributes).
   *name* is a short string identifying the kernel type.
   *attributes* is a dictionary with information to allow selecting a kernel.

.. method:: make_manager(name)

   Prepare and return a :class:`~jupyter_client.KernelManager` instance
   ready to start a new kernel instance of the type identified by *name*.
   The input will be one of the names given by :meth:`find_kernels`.

For example, imagine we want to tell Jupyter about kernels for a new language called oblong:

# oblong_provider.py
from jupyter_client.discovery import KernelProviderBase
from jupyter_client import KernelManager
from shutil import which

class OblongKernelProvider(KernelProviderBase):
    id = 'oblong'

    def find_kernels(self):
        if not which('oblong-kernel'):
            return  # Check it's available

        # Two variants - for a real kernel, these could be something like
        # different conda environments.
        yield 'standard', {
            'display_name': 'Oblong (standard)',
            'language': {'name': 'oblong'},
            'argv': ['oblong-kernel'],
        }
        yield 'rounded', {
            'display_name': 'Oblong (rounded)',
            'language': {'name': 'oblong'},
            'argv': ['oblong-kernel'],
        }

    def make_manager(self, name):
        if name == 'standard':
            return KernelManager(kernel_cmd=['oblong-kernel'],
                                 extra_env={'ROUNDED': '0'})
        elif name == 'rounded':
            return KernelManager(kernel_cmd=['oblong-kernel'],
                                 extra_env={'ROUNDED': '1'})
        else:
            raise ValueError("Unknown kernel %s" % name)

You would then register this with an entry point. In your setup.py, put something like this:

setup(...
    entry_points = {
    'jupyter_client.kernel_providers' : [
        # The name before the '=' should match the id attribute
        'oblong = oblong_provider:OblongKernelProvider',
    ]
})

Finding kernel types

To find and start kernels in client code, use :class:`jupyter_client.discovery.KernelFinder`. This uses multiple kernel providers to find available kernels. Like a kernel provider, it has methods find_kernels and make_manager. The kernel names it works with have the provider ID as a prefix, e.g. oblong/rounded (from the example above).

from jupyter_client.discovery import KernelFinder
kf = KernelFinder.from_entrypoints()

## Find available kernel types
for name, attributes in kf.find_kernels():
    print(name, ':', attributes['display_name'])
# oblong/standard : Oblong (standard)
# oblong/rounded : Oblong(rounded)
# ...

## Start a kernel by name
manager = kf.make_manager('oblong/standard')
manager.start_kernel()

.. module:: jupyter_client.discovery

.. autoclass:: KernelFinder

   .. automethod:: from_entrypoints

   .. automethod:: find_kernels

   .. automethod:: make_manager