Kernel providers — jupyter_client 5.1.0 documentation

# Kernel providers

Note

This is a new interface under development, and may still change. Not all Jupyter applications use this yet. See Kernel specs 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 `jupyter_client.discovery.KernelProviderBase`, giving your provider an ID and overriding two methods.

class `MyKernelProvider`
  `id`

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

  `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.

  `make_manager`(name)

    Prepare and return a `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 `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 `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()

class `jupyter_client.discovery.` `KernelFinder`(providers)

  Manages a collection of kernel providers to find available kernel types

  providers should be a list of kernel provider instances.

  classmethod `from_entrypoints`()

    Load all kernel providers advertised by entry points.

    Kernel providers should use the “jupyter_client.kernel_providers” entry point group.

    Returns an instance of KernelFinder.

  `find_kernels`()

    Iterate over available kernel types.

    Yields 2-tuples of (prefixed_name, attributes)

  `make_manager`(name)

    Make a KernelManager instance for a given kernel type.

## Kernel providers included in `jupyter_client`

`jupyter_client` includes two kernel providers:

class `jupyter_client.discovery.` `KernelSpecProvider`

  Offers kernel types from installed kernelspec directories.

  See also

  Kernel specs

class `jupyter_client.discovery.` `IPykernelProvider`

  Offers a kernel type using the Python interpreter it’s running in.

  This checks if ipykernel is importable first.

## Glossary

Kernel instance
  A running kernel, a process which can accept ZMQ connections from frontends. Its state includes a namespace and an execution counter.
Kernel type
  The software to run a kernel instance, along with the context in which a kernel starts. One kernel type allows starting multiple, initially similar kernel instances. For instance, one kernel type may be associated with one conda environment containing `ipykernel`. The same kernel software in another environment would be a different kernel type. Another software package for a kernel, such as `IRkernel`, would also be a different kernel type.
Kernel provider
  A Python class to discover kernel types and allow a client to start instances of those kernel types. For instance, one kernel provider might find conda environments containing `ipykernel` and allow starting kernel instances in these environments.