Skip to content

Command line and kernel configuration

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

The primary options available are:

Kernel spec

The kernel spec can be configured 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",
        "--loop=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 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
  • loop: None
  • loop_options: None

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

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

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.loop=tk

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

qt

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

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

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

Loop options

Options can be provided to configure how a loop 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) loop: 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) loop: 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.loop_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.