Skip to content

Command line

The command async-kernel and alias async_kernel are provided at the command line.

The primary options available are:

Kernel spec

Kernel specs can be added/removed via the command line:

Example

async-kernel -a async --backend=trio --loop=tk --display_name="Async python tk trio"

The kernel spec looks like this:

{
    "argv": [
        "python",
        "-m",
        "async_kernel",
        "-f",
        "{connection_file}",
        "--start_interface=async_kernel.interface.start_kernel_zmq_interface",
        "--kernel_name=async",
        "--backend=trio",
        "--host=tk"
    ],
    "env": {},
    "display_name": "Async python tk trio",
    "language": "python",
    "interrupt_mode": "message",
    "metadata": {
        "debugger": true,
        "concurrent": true
    },
    "kernel_protocol_version": "5.5"
}

A single kernel spec is created in the folder <sys.prefix>/share/jupyter/kernels/async when async-kernel is installed with the following defaults.

Defaults

  • name: 'async'
  • display_name: 'async'
  • backend: asyncio
  • backend_options: {'use_uvloop':True} if uvloop or winloop is installed
  • host: None
  • host_options: None

The kernel spec can be updated by adding a kernel spec with the same name ('async').

Backend (interface-backend)

There are two supported backends 'asyncio' and 'trio'.

In CPython the backend is started using anyio.run. The type of backend can be specified at the attribute interface.backend. The backend_options can be specified at the attribute interface.backend_options. Options can be written as a literal python string.

async-kernel -a async-trio --interface.backend=trio

Kernel spec location

See here for a list of locations where Jupyter/IPython searches for the kernel specs.

The path where the kernel spec is installed/deleted can also be specified by either prefix or folder.

Options

  • prefix (optional): the prefix to use with PREFIX/share/jupyter/kernels (defaults is sys.prefix).
  • folder (optional) the full path to the kernels folder.

Examples

# Install for a user on linux
async-kernel -a async --path="~/.local/share/jupyter/kernels"

# Install for a user on Mac
async-kernel -a async --path="~/Library/Jupyter/kernels"

# Install for a user on windows
async-kernel -a async --path="%APPDATA%\jupyter\kernels"

Host loop (gui event loops - tk, qt)

Typically event loops don't like to share the thread with any other event loop. Trio provides the function trio.lowlevel.start_guest_run which allows it to run as a guest alongside the host event loop by means of callbacks. The author of aiologic has provided an (experimental) asyncio equivalent (gist).

async-kernel supports configuration of one host and one backend for the kernel. Below are some example kernel specs for host and backend kernel specs.

tk

# tk host asyncio backend
async-kernel -a async-tk --interface.host=tk

# tk host trio backend
async-kernel -a async-tk --interface.host=tk --backend=trio

qt

# qt host asyncio backend
async-kernel -a async-qt --interface.host=qt

# qt host trio backend
async-kernel -a async-qt-trio --interface.host=qt --interface.backend=trio

# PySide6 is default.  You can specify a different module via `host_options`
async-kernel -a async-qt --interface.host=qt --interface.host_options={'module':'PySide2'}

Host options

Options can be provided to configure how a host loads. There are only a few options available at present.

  • host_class'[type[Host| str]]` : A customised subclass of a Host or a dotted import path to the customised Host.
  • `'module': The module name on which to base the event loop. (Only applies to qt).

Backend options

Options can be provided for how the backend is started.

  • With a (gui) host: Options for start_guest_run
    • trio.lowlevel.start_guest_run
    • asyncio
      • host_uses_signal_set_wakeup_fd
      • host_uses_sys_set_asyncgen_hooks
      • loop_factory,
      • task_factory,
      • context,
      • debug,
  • Without a (gui) host: backend_options in anyio.run
# If uvloop is installed it will be used by default. You can do this to disable it.
async-kernel -a async "--interface.host_options={'use_uvloop':False}"

Custom arguments

Additional arguments can be included when defining the kernel spec, these include:

  • Arguments for async_kernel.kernelspec.write_kernel_spec
    • --start_interface
    • --fullpath=False
    • --display_name
    • --prefix
  • Nested attributes can be set on the kernel via `kernel.[nested.attribute.name']'. Each parameter should be specified as if it were a 'flag' as follows.

Prefix each setting with "--" and join using the delimiter "=".

--<PARAMETER or DOTTED.ATTRIBUTE.NAME>=<VALUE>

or, with compact notation to set a Boolean value as a Boolean flag.

# True
--<PARAMETER or DOTTED.ATTRIBUTE.NAME>

# False
--no-<PARAMETER or DOTTED.ATTRIBUTE.NAME>

Examples

start_interface

To specify an alternate kernel factory.

--start_interface=my_module.my_interface_factory

fullpath (True)

--fullpath

display name

To set the kernel display name to True.

"--display_name=My kernel display name"

Set the execute request timeout trait on the kernel shell.

--shell.timeout=0.1

Set kernel.quiet=True:

--quiet

Set kernel.quiet=False:

--no=quiet

Remove a kernel spec

Use the flag -r or --remove to remove a kernelspec.

If you added the custom kernel spec above, you can remove it with:

async-kernel -r async-trio-custom

Start a kernel

Use the flag -f or --connection_file followed by the full path to the connection file. To skip providing a connection file

This will start the default kernel (async).

async-kernel -f .

Additional settings can be passed as arguments.

async-kernel -f . --kernel_name=async-trio-custom --display_name='My custom kernel' --quiet=False

The call above will start a new kernel with a 'trio' backend. The quiet setting is a parameter that gets set on kernel. Parameters of this type are converted using [eval] prior to setting.

For further detail, see the API for the command line handler command_line.