kernelspec

Add and remove kernel specifications for Jupyter.

Functions:

• make_argv –

  Returns an argument vector (argv) that can be used to start a Kernel.

• write_kernel_spec –

  Write a kernel spec for launching a kernel.

• get_kernel_dir –

  The path to where kernel specs are stored for Jupyter.

make_argv

make_argv(
    *,
    connection_file: str = "{connection_file}",
    kernel_name: str = "async",
    kernel_factory: str | KernelFactoryType = "async_kernel.kernel.Kernel",
    fullpath: bool = True,
    **kwargs: dict[str, Any],
) -> list[str]

Returns an argument vector (argv) that can be used to start a Kernel.

This function returns a list of arguments can be used directly start a kernel with subprocess.Popen. It will always call command.command_line as a python module.

Parameters:

• connection_file

  (str, default: '{connection_file}' ) –

  The path to the connection file.

• kernel_factory

  (str | KernelFactoryType, default: 'async_kernel.kernel.Kernel' ) –

  Either the kernel factory object itself, or the string import path to a callable that returns a non-started kernel.

• kernel_name

  (str, default: 'async' ) –

  The name of the kernel to use.

• fullpath

  (bool, default: True ) –

  If True the full path to the executable is used, otherwise 'python' is used.

• **kwargs

  (dict[str, Any], default: {} ) –

  Additional settings to pass when creating the kernel passed to kernel_factory.

Returns:

• list ( list[str] ) –

  A list of command-line arguments to launch the kernel module.

Source code in src/async_kernel/kernelspec.py

def make_argv(
    *,
    connection_file: str = "{connection_file}",
    kernel_name: str = "async",
    kernel_factory: str | KernelFactoryType = "async_kernel.kernel.Kernel",
    fullpath: bool = True,
    **kwargs: dict[str, Any],
) -> list[str]:
    """Returns an argument vector (argv) that can be used to start a `Kernel`.

    This function returns a list of arguments can be used directly start a kernel with [subprocess.Popen][].
    It will always call [command.command_line][] as a python module.

    Args:
        connection_file: The path to the connection file.
        kernel_factory: Either the kernel factory object itself, or the string import path to a
            callable that returns a non-started kernel.
        kernel_name: The name of the kernel to use.
        fullpath: If True the full path to the executable is used, otherwise 'python' is used.
        **kwargs: Additional settings to pass when creating the kernel passed to `kernel_factory`.

    Returns:
        list: A list of command-line arguments to launch the kernel module.
    """
    argv = [(sys.executable if fullpath else "python"), "-m", "async_kernel", "-f", connection_file]
    for k, v in ({"kernel_factory": kernel_factory, "kernel_name": kernel_name} | kwargs).items():
        argv.append(f"--{k}={v}")
    return argv

write_kernel_spec

write_kernel_spec(
    path: Path | str | None = None,
    *,
    kernel_name: str = "async",
    display_name: str = "",
    fullpath: bool = False,
    prefix: str = "",
    kernel_factory: str | KernelFactoryType = "async_kernel.kernel.Kernel",
    connection_file: str = "{connection_file}",
    **kwargs: dict[str, Any],
) -> Path

Write a kernel spec for launching a kernel.

Parameters:

• path

  (Path | str | None, default: None ) –

  The path where to write the spec.

• kernel_name

  (str, default: 'async' ) –

  The name of the kernel to use.

• fullpath

  (bool, default: False ) –

  If True the full path to the executable is used, otherwise 'python' is used.

• display_name

  (str, default: '' ) –

  The display name for Jupyter to use for the kernel. The default is "Python ({kernel_name})".

• kernel_factory

  (str | KernelFactoryType, default: 'async_kernel.kernel.Kernel' ) –

  The string import path to a callable that creates the Kernel or, a self-contained function that returns an instance of a Kernel.

• connection_file

  (str, default: '{connection_file}' ) –

  The path to the connection file.

• prefix

  (str, default: '' ) –

  given, the kernelspec will be installed to PREFIX/share/jupyter/kernels/KERNEL_NAME. This can be sys.prefix for installation inside virtual or conda envs.

• **kwargs

  (dict[str, Any], default: {} ) –

  Pass additional settings to set on the instance of the Kernel when it is instantiated. Each setting should correspond to the dotted path to the attribute relative to the kernel. For example ..., **{'shell.timeout'=0.1}).

Example passing a callable kernel_factory:

When `kernel_factory` is passed as a callable, the callable is stored in the file
'kernel_spec.py' inside the kernelspec folder.

```python
import async_kernel.kernelspec


def kernel_factory(settings):
    from async_kernel import Kernel

    class MyKernel(Kernel):
        async def execute_request(self, job):
            print(job)
            return await super().execute_request(job)

    return MyKernel(settings)


async_kernel.kernelspec.write_kernel_spec(
    kernel_name="async-print-job", kernel_factory=kernel_factory
)
```

Warning:
    Moving the spec folder will break the import which is stored as an absolute path.

Referenced by:

• Usage Command line Add a kernel spec Custom arguments

Source code in src/async_kernel/kernelspec.py

def write_kernel_spec(
    path: Path | str | None = None,
    *,
    kernel_name: str = "async",
    display_name: str = "",
    fullpath: bool = False,
    prefix: str = "",
    kernel_factory: str | KernelFactoryType = "async_kernel.kernel.Kernel",
    connection_file: str = "{connection_file}",
    **kwargs: dict[str, Any],
) -> Path:
    """
    Write a kernel spec for launching a kernel.

    Args:
        path: The path where to write the spec.
        kernel_name: The name of the kernel to use.
        fullpath: If True the full path to the executable is used, otherwise 'python' is used.
        display_name: The display name for Jupyter to use for the kernel. The default is `"Python ({kernel_name})"`.
        kernel_factory: The string import path to a callable that creates the Kernel or,
            a *self-contained* function that returns an instance of a `Kernel`.
        connection_file: The path to the connection file.
        prefix: given, the kernelspec will be installed to PREFIX/share/jupyter/kernels/KERNEL_NAME.
            This can be sys.prefix for installation inside virtual or conda envs.
        **kwargs: Pass additional settings to set on the instance of the `Kernel` when it is instantiated.
            Each setting should correspond to the dotted path to the attribute relative to the kernel.
            For example `..., **{'shell.timeout'=0.1})`.

    Example passing a callable kernel_factory:

        When `kernel_factory` is passed as a callable, the callable is stored in the file
        'kernel_spec.py' inside the kernelspec folder.

        ```python
        import async_kernel.kernelspec


        def kernel_factory(settings):
            from async_kernel import Kernel

            class MyKernel(Kernel):
                async def execute_request(self, job):
                    print(job)
                    return await super().execute_request(job)

            return MyKernel(settings)


        async_kernel.kernelspec.write_kernel_spec(
            kernel_name="async-print-job", kernel_factory=kernel_factory
        )
        ```

        Warning:
            Moving the spec folder will break the import which is stored as an absolute path.
    """
    assert re.match(re.compile(r"^[a-z0-9._\-]+$", re.IGNORECASE), kernel_name)
    path = Path(path) if path else (get_kernel_dir(prefix) / kernel_name)
    # stage resources
    try:
        path.mkdir(parents=True, exist_ok=True)
        if callable(kernel_factory):
            with path.joinpath("kernel_factory.py").open("w") as f:
                f.write(textwrap.dedent(inspect.getsource(kernel_factory)))
            kernel_factory = f"{path}{CUSTOM_KERNEL_MARKER}{kernel_factory.__name__}"
        # validate
        if kernel_factory != "async_kernel.kernel.Kernel":
            import_kernel_factory(kernel_factory)
        shutil.copytree(src=RESOURCES, dst=path, dirs_exist_ok=True)
        spec = KernelSpec()
        spec.argv = make_argv(
            kernel_factory=kernel_factory,
            connection_file=connection_file,
            kernel_name=kernel_name,
            fullpath=fullpath,
            **kwargs,
        )
        spec.name = kernel_name
        spec.display_name = display_name or f"Python ({kernel_name})"
        spec.language = "python"
        spec.interrupt_mode = "message"
        spec.metadata = {"debugger": True}
        # write kernel.json
        with path.joinpath("kernel.json").open("w") as f:
            json.dump(spec.to_dict(), f, indent=1)
    except Exception:
        shutil.rmtree(path, ignore_errors=True)
        raise
    else:
        return path

get_kernel_dir

get_kernel_dir(prefix: str = '') -> Path

The path to where kernel specs are stored for Jupyter.

Parameters:

• prefix

  (str, default: '' ) –

  Defaults to sys.prefix (installable for a particular environment).

Source code in src/async_kernel/kernelspec.py

def get_kernel_dir(prefix: str = "") -> Path:
    """
    The path to where kernel specs are stored for Jupyter.

    Args:
        prefix: Defaults to sys.prefix (installable for a particular environment).
    """
    return Path(prefix or sys.prefix) / "share/jupyter/kernels"