### Build and Upload to PyPI (Bash)

Source: https://github.com/jupyter/jupyter_client/blob/main/RELEASING.md

This sequence of commands builds the distribution packages and uploads them to PyPI. It requires `build` and `twine` to be installed via `pipx`. Ensure `dist/` and `build/` directories are clean before building.

```bash
rm -rf dist/*
rm -rf build/*
pipx run build .
pipx run twine check dist/*
pipx run twine upload dist/*
```

--------------------------------

### Bump Version and Tag (Bash)

Source: https://github.com/jupyter/jupyter_client/blob/main/RELEASING.md

This snippet shows how to set the new version, bump it using hatch, and create a Git tag for the release. It requires `hatch` to be installed and an environment variable `version` to be set.

```bash
export version=<NEW_VERSION>
pipx run hatch version ${version}
git tag -a ${version} -m {version}
```

--------------------------------

### Kernel Pre and Post Start Operations

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Manages tasks before and after a kernel starts. `pre_start_kernel` prepares the kernel for startup, especially when using random ports. `post_start_kernel` handles any necessary post-startup configurations. These methods are crucial for a robust kernel launch sequence.

```python
from jupyter_client.manager import KernelManager

km = KernelManager()

# Prepares a kernel for startup in a separate process.
# If random ports are used, this must be called before channels are created.
# Any Popen kwargs can be passed down.
km.pre_start_kernel(cwd='/path/to/working/dir')

# Performs any post startup tasks relative to the kernel.
# Accepts keyword arguments used in the kernel process's launch.
km.post_start_kernel(extra_env={'VAR': 'value'})

```

--------------------------------

### Example kernel.json Configuration

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/kernels.md

This JSON configuration defines the necessary parameters for a Jupyter kernel. It specifies the command-line arguments to start the kernel ('argv'), a user-friendly display name ('display_name'), and the programming language it supports ('language'). The 'argv' field includes a placeholder '{connection_file}' which Jupyter replaces with the path to the connection file.

```json
{
 "argv": ["python3", "-m", "IPython.kernel",
          "-f", "{connection_file}"],
 "display_name": "Python 3",
 "language": "python"
}
```

--------------------------------

### Example pyproject.toml for Packaging Kernels

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/kernels.md

This TOML file demonstrates a configuration using the 'hatch' build backend for packaging a Jupyter kernel as a Python package. It defines build settings that ensure the kernel directory, including 'kernel.json' and icons, is correctly included in the package and installed into the appropriate Jupyter share directory.

```toml
[build.hooks.hatch.environment.project.dependencies]
# Install build backend and packaging tools
build = "*"
hatchling = "*"

[build.hooks.hatch.build]
script = "hatch_build.py"

```

--------------------------------

### Start Kernel Channels (Python)

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Starts the communication channels (shell, iopub, stdin, hb, control) for the kernel. Creates and starts the channels if they don't exist. Requires `start_kernel()` to be called first if using random ports. Raises `RuntimeError` if channels were previously stopped. Returns `None`.

```Python
start_channels(shell=True, iopub=True, stdin=True, hb=True, control=True)
```

--------------------------------

### Kernel Provisioner - Post Launch

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.provisioning.md

Performs any steps following the kernel process launch. This method is called during the kernel start sequence.

```APIDOC
## async POST /jupyter/jupyter_client/provisioning/post_launch

### Description
Performs any steps following the kernel process launch. This method is called from KernelManager.post_start_kernel() as part of its start kernel sequence.

### Method
POST

### Endpoint
/jupyter/jupyter_client/provisioning/post_launch

### Parameters
#### Query Parameters
- **kwargs** (dict) - Optional - Additional keyword arguments.

### Request Example
```json
{
  "kwargs": {}
}
```

### Response
#### Success Response (200)
- **None** (None) - This method does not return any value.

#### Response Example
```json
null
```
```

--------------------------------

### Install Kernel Spec

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Installs a kernel specification with a specified name. It can optionally replace an existing kernel spec and allows installation to system, user, or a specified prefix directory. Debugging flags can be used to increase logging output.

```APIDOC
## POST /jupyter/kernelspec/install

### Description
Installs a kernel specification. This command allows for the installation of a new kernel spec, with options to replace an existing one, specify the installation directory (system, user, or custom prefix), and enable debug logging.

### Method
POST

### Endpoint
`/jupyter/kernelspec/install`

### Parameters
#### Query Parameters
- **SOURCE_DIR** (string) - Required - The directory containing the kernel spec files.

#### Request Body
- **name** (string) - Optional - The name to assign to the kernel spec.
- **replace** (boolean) - Optional - If true, replaces any existing kernel spec with the same name.
- **user** (boolean) - Optional - If true, installs the kernel spec to the per-user registry.
- **prefix** (string) - Optional - Specifies a prefix directory for installation. Kernelspec will be installed in `PREFIX/share/jupyter/kernels/`.
- **debug** (boolean) - Optional - Sets the application log level to DEBUG for verbose logging.

### Request Example
```json
{
  "name": "my-python-kernel",
  "replace": true,
  "user": true,
  "prefix": "/opt/jupyter",
  "debug": false
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating successful installation.

#### Response Example
```json
{
  "message": "Kernel spec 'my-python-kernel' installed successfully."
}
```
```

--------------------------------

### Kernel Provisioner - Pre Launch

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.provisioning.md

Prepares for kernel process launch by applying substitutions and finalizing launch parameters. This method is crucial for environment setup.

```APIDOC
## async POST /jupyter/jupyter_client/provisioning/pre_launch

### Description
Performs any steps in preparation for kernel process launch. This includes applying additional substitutions to the kernel launch command and environment. It also includes preparation of launch parameters. Subclass implementations are advised to call this method as it applies environment variable substitutions and calls the provisioner’s `_finalize_env()` method.

### Method
POST

### Endpoint
/jupyter/jupyter_client/provisioning/pre_launch

### Parameters
#### Query Parameters
- **kwargs** (dict) - Optional - Additional keyword arguments.

### Request Example
```json
{
  "kwargs": {}
}
```

### Response
#### Success Response (200)
- **dict[str, Any]** - The potentially updated keyword arguments that are passed to launch_kernel().

#### Response Example
```json
{
  "kernel_cmd": ["python", "-m", "ipykernel_launcher"],
  "env": {
    "PATH": "/usr/local/bin:/usr/bin:/bin"
  }
}
```
```

--------------------------------

### Example hatch_build.py for Packaging Kernels

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/kernels.md

This Python script is designed to be used with the 'hatch' build backend for packaging Jupyter kernels. It defines the build process, ensuring that the kernel's metadata files (like kernel.json) and assets (like icons) are collected and placed in the correct 'share/jupyter/kernels/' directory within the installed Python package.

```python
from hatchling.builders.hooks.plugin import BuildHook

class CustomBuildHook(BuildHook):
    def build_hook(self, **kwargs):
        self.build_static_data()

    def build_static_data(self):
        import shutil
        import os

        kernel_dir = os.path.join(self.root, 'share', 'jupyter', 'kernels', 'echo')
        os.makedirs(kernel_dir, exist_ok=True)

        # Copy kernel.json
        shutil.copy(os.path.join(self.root, 'kernel.json'), kernel_dir)

        # Copy logo files (example)
        for icon in ['logo-64x64.png', 'logo-32x32.png']:
            src_path = os.path.join(self.root, icon)
            if os.path.exists(src_path):
                shutil.copy(src_path, kernel_dir)

```

--------------------------------

### KernelManager - Pre Start Kernel

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Prepares a kernel for startup in a separate process. If random ports are used, this must be called before channels are created.

```APIDOC
## async pre_start_kernel(**kw)

### Description
Prepares a kernel for startup in a separate process. If random ports (port=0) are being used, this method must be called before the channels are created.

### Method
ASYNC POST

### Endpoint
/jupyter/jupyter_client/pre_start_kernel

### Parameters
#### Request Body
- **kw** (dict) - Optional keyword arguments that are passed down to build the kernel_cmd and launching the kernel (e.g. Popen kwargs).

### Response
#### Success Response (200)
- **Tuple[List[str], Dict[str, Any]]** - A tuple containing a list of strings and a dictionary of any type.

#### Response Example
```json
[
  ["arg1", "arg2"],
  {"key1": "value1", "key2": 123}
]
```
```

--------------------------------

### KernelManager - Start Kernel

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Starts a kernel on this host in a separate process. If random ports are used, this must be called before channels are created.

```APIDOC
## async start_kernel(**kw)

### Description
Starts a kernel on this host in a separate process. If random ports (port=0) are being used, this method must be called before the channels are created.

### Method
ASYNC POST

### Endpoint
/jupyter/jupyter_client/start_kernel

### Parameters
#### Request Body
- **kw** (dict) - Optional keyword arguments that are passed down to build the kernel_cmd and launching the kernel (e.g. Popen kwargs).

### Response
#### Success Response (200)
- **None** (None) - No return value.

#### Response Example
None
```

--------------------------------

### KernelManager - Post Start Kernel

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Performs any post startup tasks relative to the kernel.

```APIDOC
## async post_start_kernel(**kw)

### Description
Performs any post startup tasks relative to the kernel.

### Method
ASYNC POST

### Endpoint
/jupyter/jupyter_client/post_start_kernel

### Parameters
#### Request Body
- **kw** (dict) - Optional keyword arguments that were used in the kernel process’s launch.

### Response
#### Success Response (200)
- **None** (None) - No return value.

#### Response Example
None
```

--------------------------------

### ZeroMQ Connection String Example

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/kernels.md

This example demonstrates how to construct a ZeroMQ connection string for the shell socket using the transport protocol, IP address, and shell port specified in the kernel's connection file. This format is used by the kernel to bind to the appropriate socket for communication.

```shell
tcp://127.0.0.1:57503
```

--------------------------------

### Control Kernel Lifecycle: Start, Stop, and Restart

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Manage the lifecycle of kernels using asynchronous methods. This includes starting new kernels, shutting them down forcefully or gracefully, and handling restart operations with callbacks.

```python
async def manage_kernel_lifecycle(kernel_manager):
    # Start a new kernel
    kernel_id = await kernel_manager.start_kernel()
    print(f"Started kernel with ID: {kernel_id}")

    # Check if the kernel is alive
    is_alive = kernel_manager.is_alive(kernel_id)
    print(f"Is kernel alive? {is_alive}")

    # Shutdown the kernel gracefully
    await kernel_manager.shutdown_kernel(kernel_id)
    print(f"Initiated shutdown for kernel: {kernel_id}")

    # Wait for shutdown to complete
    await kernel_manager.finish_shutdown(kernel_id)
    print(f"Kernel {kernel_id} finished shutting down.")

    # Example of adding a restart callback
    def restart_handler(kernel_id):
        print(f"Kernel {kernel_id} restarted.")
    kernel_manager.add_restart_callback(kernel_id, restart_handler, event='restart')
```

--------------------------------

### InstallKernelSpec App

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

A command-line application to install a kernel spec.

```APIDOC
## Class: jupyter_client.kernelspecapp.InstallKernelSpec

### Description
An app to install a kernel spec.

### Usage
```bash
jupyter kernelspec install <source_directory> [--user] [--prefix=<prefix>] [--name=<kernel_name>]
```

### Options

- `--user`: Install the kernel spec for the current user only.
- `--prefix=<prefix>`: Install the kernel spec to the specified prefix directory.
- `--name=<kernel_name>`: Specify a name for the installed kernel spec.

### Examples

```bash
jupyter kernelspec install /path/to/my_kernel --user
```

### Aliases

- `config`: `JupyterApp.config_file`
- `log-level`: `Application.log_level`
- `name`: `InstallKernelSpec.kernel_name`
- `prefix`: `InstallKernelSpec.prefix`
```

--------------------------------

### Synchronous Kernel Startup

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Starts a new synchronous kernel and returns its manager and client instances. This is a blocking operation with a default startup timeout.

```python
from jupyter_client.manager import start_new_kernel

# Start a new kernel
manager, client = start_new_kernel()
print(f"Kernel started. Manager: {manager}, Client: {client}")

# Perform operations with the client
# ...

# Shutdown the kernel
manager.shutdown_kernel()
```

--------------------------------

### Asynchronous Kernel Startup

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Starts a new asynchronous kernel and returns its manager and client instances. It allows for non-blocking kernel operations, with a default startup timeout.

```python
import asyncio
from jupyter_client.manager import start_new_async_kernel

async def main():
    manager, client = await start_new_async_kernel()
    print(f"Async kernel started. Manager: {manager}, Client: {client}")
    # Perform async operations with the client
    # ...
    await manager.shutdown_kernel()

asyncio.run(main())
```

--------------------------------

### Start a New Kernel Process

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Initiates a new kernel in a separate process on the local host. If random ports are used (port=0), this must be called before channel creation. Accepts keyword arguments for Popen and kernel command construction.

```python
from jupyter_client.manager import start_kernel

# Start a kernel with default settings
kernel_manager, kernel_client = start_kernel()

# Start a kernel with custom arguments
kernel_manager, kernel_client = start_kernel(kernel_cmd=['python', '-m', 'ipykernel_launcher'], Popen_kwargs={'cwd': '/path/to/working/dir'})

```

--------------------------------

### MultiKernelManager Methods

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/modules.md

Provides methods for managing multiple kernels, including starting, stopping, and signaling them.

```APIDOC
## MultiKernelManager Methods

### Description
Provides methods for managing multiple kernels, including starting, stopping, and signaling them.

### Methods

- **request_shutdown()**: Request shutdown of a kernel.
- **restart_kernel()**: Restart a kernel.
- **shared_context**: Get the shared context for the kernel manager.
- **shutdown_all()**: Shutdown all managed kernels.
- **shutdown_kernel()**: Shutdown a specific kernel.
- **signal_kernel()**: Send a signal to a kernel.
- **start_kernel()**: Start a new kernel.
- **update_env()**: Update the environment variables for a kernel.
```

--------------------------------

### Kernel Manager Utility Functions

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/modules.md

Utility functions related to starting and managing asynchronous kernels.

```APIDOC
## Kernel Manager Utility Functions

### Description
This section covers utility functions for checking kernel state and starting new kernels, including asynchronous operations.

### Methods
- `in_pending_state()`
- `run_kernel()`
- `start_new_async_kernel()`
- `start_new_kernel()`

### Parameters
(Specific parameter details for each function would require further documentation.)

### Request Example
(Not applicable for these utility functions.)

### Response
(Response details vary by function.)

#### Success Response (Varies by function)
- `in_pending_state()`: Returns a boolean indicating if the kernel is in a pending state.
- `start_new_kernel()`: Returns a client object for the newly started kernel.

#### Response Example
```python
# Example for start_new_kernel()
from jupyter_client import KernelManager
km = KernelManager()
client = km.start_new_kernel()
print(f"Started kernel with ID: {client.kernel.kernel_id}")
```
```

--------------------------------

### jupyter_client.launcher.launch_kernel

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Launches a localhost kernel, binding to the specified ports. This function is used to start a new Jupyter kernel process.

```APIDOC
## jupyter_client.launcher.launch_kernel

### Description
Launches a localhost kernel, binding to the specified ports.

### Method
Python Function

### Endpoint
N/A (Python Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Function Parameters
- **cmd** (list of str) - Required - A string of Python code that imports and executes a kernel entry point.
- **stdin** (optional) - Standard streams, as defined in subprocess.Popen.
- **stdout** (optional) - Standard streams, as defined in subprocess.Popen.
- **stderr** (optional) - Standard streams, as defined in subprocess.Popen.
- **env** (dict) - Optional - Environment variables passed to the kernel.
- **independent** (bool) - Optional (default: False) - If set, the kernel process is guaranteed to survive if this process dies.
- **cwd** (path) - Optional - The working dir of the kernel process.
- **\*\*kw** (optional) - Additional arguments for Popen.

### Request Example
```python
from subprocess import Popen
from jupyter_client.launcher import launch_kernel

cmd = ["python", "-m", "ipykernel_launcher", "-f", "kernel.json"]
process = launch_kernel(cmd)
```

### Response
#### Success Response (Popen)
- **Popen instance** (Popen) - An instance for the kernel subprocess.

#### Response Example
```python
<subprocess.Popen object at 0x...>
```
```

--------------------------------

### Push to GitHub (Bash)

Source: https://github.com/jupyter/jupyter_client/blob/main/RELEASING.md

This command pushes the local repository changes, including the new tag, to the remote GitHub repository. It assumes 'upstream' is configured as the remote.

```bash
git push upstream  && git push upstream --tags
```

--------------------------------

### List Kernel Specs

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Lists all installed Jupyter kernel specifications. This command can output the results in JSON format for machine readability and can also list only missing kernels.

```APIDOC
## GET /jupyter/kernelspec/list

### Description
Retrieves a list of all installed Jupyter kernel specifications. Options are available to format the output as JSON for programmatic use and to filter the list to show only missing kernels.

### Method
GET

### Endpoint
`/jupyter/kernelspec/list`

### Parameters
#### Query Parameters
- **json** (boolean) - Optional - If true, outputs the spec name and location as machine-readable JSON.
- **missing** (boolean) - Optional - If true, lists only the kernel specifications that are missing their interpreters.

### Request Example
```http
GET /jupyter/kernelspec/list?json=true
```

### Response
#### Success Response (200)
- **kernels** (object) - A dictionary where keys are kernel spec names and values are their locations, or a JSON array of kernel spec information if `json` parameter is true.

#### Response Example
```json
{
  "kernels": {
    "python3": "/usr/local/share/jupyter/kernels/python3",
    "ir": "/usr/local/share/jupyter/kernels/ir"
  }
}
```
```

--------------------------------

### AsyncKernelManager API Changes

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/migration.md

Details signature and attribute changes in the AsyncKernelManager class for Jupyter Client 7.0, including methods that are now async.

```APIDOC
## AsyncKernelManager API Changes

### Description
This section outlines the API modifications for `AsyncKernelManager` in Jupyter Client 7.0. In addition to the signature and attribute changes common with `KernelManager`, several methods have been made asynchronous.

### Asynchronous Method Changes

- **`async def pre_start_kernel(self, **kwargs) -> Tuple[List[str], Dict[str, Any]]`**
  - **Description**: The `pre_start_kernel` method is now an `async` method and returns a tuple containing the formatted kernel startup command list and an updated dictionary of keyword arguments.
  - **Method**: `async def`
  - **Returns**: `Tuple[List[str], Dict[str, Any]]`

- **`async def post_start_kernel(self, **kwargs)`**
  - **Description**: The `post_start_kernel` method has been made `async`.
  - **Method**: `async def`

- **`async def request_shutdown(self, restart: bool = False)`**
  - **Description**: The `request_shutdown` method is now `async` and accepts a `restart` boolean keyword argument.
  - **Method**: `async def`
  - **Parameters**: `restart` (bool, optional, defaults to `False`)

- **`async def cleanup_resources(self, restart: bool = False)`**
  - **Description**: The `cleanup_resources` method is now `async` and accepts a `restart` boolean keyword argument.
  - **Method**: `async def`
  - **Parameters**: `restart` (bool, optional, defaults to `False`)

### Shared Changes with KernelManager

- **Signature and attribute changes** as described in the `KernelManager` section above also apply to `AsyncKernelManager` where relevant (e.g., `_launch_kernel`, `finish_shutdown`, `_kill_kernel`, `_send_kernel_sigterm`, removal of `kernel` attribute, replacement with `provisioner`).

```

--------------------------------

### Command to Start Jupyter Console with a Specific Kernel

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/kernels.md

This command allows users to launch the Jupyter terminal console pre-configured to use a specified kernel. For example, '--kernel bash' will start the console with the 'bash' kernel, enabling shell command execution within the Jupyter environment.

```bash
jupyter console --kernel bash
```

--------------------------------

### Set Development Version (Bash)

Source: https://github.com/jupyter/jupyter_client/blob/main/RELEASING.md

After a release, this command updates the version to the next development iteration, adding a 'dev' tag. It utilizes `hatch` and requires the `hatch` package to be installed via `pipx`.

```bash
pipx run hatch version <DEV_VERSION>
```

--------------------------------

### Registering a Kernel Provisioner via Entry Points

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/provisioning.md

This configuration example shows how to register a custom kernel provisioner using Python's setuptools entry points. The 'jupyter_client.kernel_provisioners' key maps a provisioner name (e.g., 'k8s-provisioner') to its implementation class (e.g., 'my_package:K8sProvisioner'), making it discoverable by Jupyter.

```ini
'jupyter_client.kernel_provisioners': [
            'k8s-provisioner = my_package:K8sProvisioner',
        ],
```

--------------------------------

### Manage Multiple Python Kernels Simultaneously

Source: https://context7.com/jupyter/jupyter_client/llms.txt

This example demonstrates managing multiple Python kernel instances concurrently using `MultiKernelManager`. It shows how to start, list, retrieve, communicate with, and shut down individual or all kernels. Dependencies include `jupyter_client.MultiKernelManager`.

```python
from jupyter_client import MultiKernelManager

# Create a multi-kernel manager
mkm = MultiKernelManager()

# Start multiple kernels
kernel_id_1 = mkm.start_kernel(kernel_name='python3')
kernel_id_2 = mkm.start_kernel(kernel_name='python3')

print(f"Started kernels: {mkm.list_kernel_ids()}")

# Get a specific kernel manager
km1 = mkm.get_kernel(kernel_id_1)

# Create client for first kernel
nc1 = km1.client()
nc1.start_channels()
nc1.wait_for_ready(timeout=60)

# Execute code in first kernel
msg_id = nnc1.execute('result = 100 + 200')
print(f"Executed in kernel {kernel_id_1}: {msg_id}")

# Check kernel status
is_alive = mkm.is_alive(kernel_id_1)
print(f"Kernel {kernel_id_1} alive: {is_alive}")

# Shutdown individual kernel
nc1.stop_channels()
mkm.shutdown_kernel(kernel_id_1)

# Shutdown all remaining kernels
mkm.shutdown_all()
```

--------------------------------

### Abstract Kernel Provisioner Methods

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.provisioning.md

Abstract methods that must be implemented by subclasses of KernelProvisionerBase. These cover core kernel management operations like launching, killing, cleaning up, and polling the kernel process. They are designed to mirror subprocess.Popen functionality where applicable.

```python
from abc import ABC, abstractmethod
from typing import Any, Dict, List, Optional, Tuple, Union

class KernelProvisionerBase(ABC):
    @abstractmethod
    async def cleanup(self, restart: bool = False) -> None:
        pass

    @abstractmethod
    async def kill(self, restart: bool = False) -> None:
        pass

    @abstractmethod
    async def launch_kernel(self, cmd: List[str], **kwargs) -> Dict[str, Union[int, str, bytes]]:
        pass

    @abstractmethod
    async def poll(self) -> Optional[int]:
        pass

    @property
    @abstractmethod
    def has_process(self) -> bool:
        pass
```

--------------------------------

### Register Custom Provisioner Entry Point (Python/Setup.py)

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/provisioning.md

This snippet demonstrates how to register a custom kernel provisioner by defining an entry point in the setup.py file. It specifies the group name 'jupyter_client.kernel_provisioners' and maps a provisioner name to its corresponding Python module and class. This allows Jupyter Client to discover and load the custom provisioner.

```python
'jupyter_client.kernel_provisioners': [
    'rbac-provisioner = acme.rbac.provisioner:RBACProvisioner',
]
```

--------------------------------

### Implement Custom Jupyter Kernel Provisioner

Source: https://context7.com/jupyter/jupyter_client/llms.txt

Shows how to create a custom kernel provisioner by subclassing KernelProvisionerBase. This allows modification of kernel launch arguments, such as adding custom environment variables or altering the command. The example demonstrates overriding pre_launch and post_launch methods to customize the kernel environment and verify its startup. Registration via kernel.json is also illustrated.

```python
from jupyter_client.provisioning import KernelProvisionerBase
from jupyter_client import KernelManager
import os
import signal

class CustomProvisioner(KernelProvisionerBase):
    """Custom provisioner with environment modifications."""

    async def pre_launch(self, **kwargs):
        """Modify launch arguments before kernel starts."""
        kwargs = await super().pre_launch(**kwargs)

        # Add custom environment variables
        env = kwargs.get('env', os.environ.copy())
        env['CUSTOM_VAR'] = 'custom_value'
        env['KERNEL_MODE'] = 'production'
        kwargs['env'] = env

        # Modify kernel command if needed
        cmd = kwargs['cmd']
        print(f"Launching kernel with command: {cmd}")

        return kwargs

    async def post_launch(self, **kwargs):
        """Actions after kernel launches."""
        await super().post_launch(**kwargs)
        print(f"Kernel process started with PID: {self.process.pid}")

    async def cleanup(self, restart=False):
        """Custom cleanup logic."""
        print(f"Cleaning up kernel (restart={restart})")
        await super().cleanup(restart=restart)

# Register custom provisioner in kernel.json:
# {
#   "argv": ["python", "-m", "ipykernel_launcher", "-f", "{connection_file}"],
#   "display_name": "Python 3 Custom",
#   "language": "python",
#   "metadata": {
#     "kernel_provisioner": {
#       "provisioner_name": "custom-provisioner"
#     }
#   }
# }

# Use kernel with custom provisioner
km = KernelManager(kernel_name='python3')
km.start_kernel()

# The custom provisioner's pre_launch and post_launch methods
# are automatically called during kernel startup

pc = km.client()
pc.start_channels()
pc.wait_for_ready(timeout=60)

# Execute code to verify custom environment
msg_id = pc.execute('import os\nprint(os.environ.get("CUSTOM_VAR"))')

# Get output
while True:
    msg = pc.get_iopub_msg(timeout=5)
    if msg['header']['msg_type'] == 'stream':
        print(f"Custom env var: {msg['content']['text'].strip()}")
    elif (msg['header']['msg_type'] == 'status' and
          msg['content']['execution_state'] == 'idle'):
        break

pc.stop_channels()
km.shutdown_kernel()
```

--------------------------------

### Kernel Provisioner Methods

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Provides details on various methods available for managing kernel provisioners, such as retrieving information, managing lifecycle, and handling signals.

```APIDOC
## Kernel Provisioner Methods

### Description
This section details the methods associated with `KernelProvisionerBase` for managing kernel lifecycle and retrieving information.

### Methods

- **get_provisioner_info()**: Retrieves information about the kernel provisioner.
- **get_shutdown_wait_time()**: Gets the time to wait for shutdown.
- **get_stable_start_time()**: Gets the time until the kernel start is stable.
- **has_process**: Checks if the provisioner has an associated process.
- **kernel_id**: The unique identifier for the kernel.
- **kernel_spec**: The kernel specification.
- **kill()**: Terminates the kernel process.
- **launch_kernel()**: Launches a new kernel.
- **load_provisioner_info()**: Loads provisioner information.
- **poll()**: Polls the status of the kernel process.
- **post_launch()**: Actions to perform after kernel launch.
- **pre_launch()**: Actions to perform before kernel launch.
- **send_signal()**: Sends a signal to the kernel process.
- **shutdown_requested()**: Checks if a shutdown has been requested.
- **terminate()**: Terminates the kernel.
- **wait()**: Waits for the kernel process to terminate.
```

--------------------------------

### Display Data Transient Data Example

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/messaging.md

Provides an example of the 'transient' field within a 'display_data' message. This field holds runtime metadata, such as 'display_id', which is not intended for persistence in documents or notebooks. It's useful for managing live kernel session information.

```default
transient = {
    'display_id': 'abcd'
}
```

--------------------------------

### Kernel Provisioner Lifecycle Methods (Python)

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.provisioning.md

This snippet outlines the core asynchronous methods for managing a kernel's lifecycle within the jupyter_client framework. These methods are intended to be implemented by subclasses of KernelProvisionerBase.

```python
async def pre_launch(**kwargs):
    """Perform any steps in preparation for kernel process launch."""
    pass

async def post_launch(**kwargs):
    """Perform any steps following the kernel process launch."""
    pass

async def send_signal(signum):
    """Sends signal identified by signum to the kernel process."""
    pass

async def shutdown_requested(restart=False):
    """Allows the provisioner to determine if the kernel’s shutdown has been requested."""
    pass

async def terminate(restart=False):
    """Terminates the kernel process."""
    pass

async def wait():
    """Waits for kernel process to terminate."""
    pass
```

--------------------------------

### Kernel Provisioner Lifecycle and Information Methods

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.provisioning.md

Methods for managing the kernel provisioner's state and information. This includes sending signals, terminating the kernel, waiting for it to finish, and retrieving or loading provisioner-specific information for persistence and recovery.

```python
import asyncio
from typing import Any, Dict, Union, Optional

class KernelProvisionerBase:
    async def send_signal(self, signum: int) -> None:
        """Sends a signal to the process group of the kernel."""
        # Implementation details... 
        pass

    async def terminate(self, restart: bool = False) -> None:
        """Terminate the provisioner and optionally restart."""
        # Implementation details...
        pass

    async def wait(self) -> Optional[int]:
        """Wait for the provisioner process."""
        # Implementation details...
        pass

    async def get_provisioner_info(self) -> Dict[str, Any]:
        """Captures the base information necessary for persistence."""
        # Implementation details...
        pass

    async def load_provisioner_info(self, provisioner_info: Dict[str, Any]) -> None:
        """Loads the base information necessary for persistence."""
        # Implementation details...
        pass

    def get_shutdown_wait_time(self, recommended: float = 5.0) -> float:
        """Returns the time allowed for a complete shutdown."""
        # Implementation details...
        return recommended

    def get_stable_start_time(self, recommended: float = 10.0) -> float:
        """Returns the expected upper bound for a kernel (re-)start to complete."""
        # Implementation details...
        return recommended

    @property
    def connection_info(self) -> Dict[str, Union[int, str, bytes]]:
        """Kernel connection information."""
        return {}

    @property
    def kernel_id(self) -> Union[str, Any]: # Assuming Unicode is a type alias for str or similar
        """Kernel identifier."""
        pass

    @property
    def kernel_spec(self) -> Any:
        """Kernel specification."""
        pass
```

--------------------------------

### Start and Manage a Single Python Kernel

Source: https://context7.com/jupyter/jupyter_client/llms.txt

This snippet demonstrates how to create and manage a single Python kernel subprocess using KernelManager. It includes starting the kernel, creating a client, establishing communication channels, waiting for the kernel to be ready, and performing a clean shutdown. Dependencies include `jupyter_client.KernelManager`.

```python
from jupyter_client import KernelManager

# Start a new Python kernel
km = KernelManager(kernel_name='python3')
km.start_kernel()

# Create a client to communicate with the kernel
nc = km.client()
nc.start_channels()

# Wait for kernel to be ready
try:
    nnc.wait_for_ready(timeout=60)
    print("Kernel is ready")
except RuntimeError as e:
    print(f"Kernel failed to start: {e}")
    nnc.stop_channels()
    km.shutdown_kernel()
    raise

# Clean shutdown
nc.stop_channels()
km.shutdown_kernel()
```

--------------------------------

### KernelSpecManager API

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/modules.md

Manages the installation, removal, and listing of kernel specifications for Jupyter.

```APIDOC
## KernelSpecManager Methods

### `install_kernel_spec()`

Installs a kernel specification.

### Method
`install_kernel_spec(kernel_name, spec, user=False, prefix=None, kind=None)`

### Parameters

*   **kernel_name** (str) - The name of the kernel.
*   **spec** (dict) - The kernel specification dictionary.
*   **user** (bool, optional) - Whether to install for the current user. Defaults to False.
*   **prefix** (str, optional) - The installation prefix. Defaults to None.
*   **kind** (str, optional) - The kind of kernel spec to install. Defaults to None.

### `install_native_kernel_spec()`

Installs a native kernel specification.

### Method
`install_native_kernel_spec(kernel_name, spec, user=False, prefix=None, kind=None)`

### Parameters

*   **kernel_name** (str) - The name of the kernel.
*   **spec** (dict) - The kernel specification dictionary.
*   **user** (bool, optional) - Whether to install for the current user. Defaults to False.
*   **prefix** (str, optional) - The installation prefix. Defaults to None.
*   **kind** (str, optional) - The kind of kernel spec to install. Defaults to None.

### `remove_kernel_spec()`

Removes a kernel specification.

### Method
`remove_kernel_spec(kernel_name, user=False, prefix=None)`

### Parameters

*   **kernel_name** (str) - The name of the kernel to remove.
*   **user** (bool, optional) - Whether to remove from the current user's specs. Defaults to False.
*   **prefix** (str, optional) - The installation prefix. Defaults to None.

### Properties

*   **kernel_dirs** (list) - List of directories where kernel specs are searched.
*   **kernel_spec_class** (class) - The class used for kernel specifications.
*   **user_kernel_dir** (str) - The directory for user-specific kernel specs.
*   **whitelist** (list) - List of explicitly whitelisted kernel names.
```

--------------------------------

### KernelSpecManager

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Manages kernel specifications, allowing operations like finding, retrieving, and installing kernels.

```APIDOC
## Class: jupyter_client.kernelspec.KernelSpecManager

### Description
A manager for kernel specs.

### Methods

#### find_kernel_specs()
- **Description**: Returns a dict mapping kernel names to resource directories.
- **Return type**: `dict`[`str`, `str`]

#### get_all_specs()
- **Description**: Returns a dict mapping kernel names to kernelspecs.
- **Return type**: `dict`[`str`, `Any`]

#### get_kernel_spec(kernel_name)
- **Description**: Returns a `KernelSpec` instance for the given kernel_name.
- **Parameters**:
  - **kernel_name** (str) - The name of the kernel to retrieve.
- **Raises**:
  - `NoSuchKernel`: If the given kernel name is not found.
- **Return type**: `KernelSpec`

#### install_kernel_spec(source_dir, kernel_name=None, user=False, replace=None, prefix=None)
- **Description**: Install a kernel spec by copying its directory.
- **Parameters**:
  - **source_dir** (str) - The directory containing the kernel spec to install.
  - **kernel_name** (str, optional) - The name to assign to the installed kernel. Defaults to the basename of `source_dir`.
  - **user** (bool, optional) - If True, install for the current user only. Defaults to False (systemwide).
  - **replace** (bool, optional) - Whether to replace an existing kernel spec with the same name.
  - **prefix** (str, optional) - If given, install to `PREFIX/share/jupyter/kernels/KERNEL_NAME`.
- **Return type**: `str` (The path that was installed)

#### remove_kernel_spec(name)
- **Description**: Remove a kernel spec directory by name.
- **Parameters**:
  - **name** (str) - The name of the kernel spec to remove.
- **Return type**: `str` (The path that was deleted)

### Attributes

- **allowed_kernelspecs** (list) - List of allowed kernel names.
- **data_dir** (str) - Path to the data directory for kernelspecs.
- **ensure_native_kernel** (bool) - If True, ensures the IPython kernel is added if no Python kernelspec is registered.
- **kernel_dirs** (list[str]) - List of directories to search for kernel specs.
- **kernel_spec_class** - The `KernelSpec` class to use.
- **user_kernel_dir** (str) - Path to the user's kernelspec data directory.
- **whitelist** (deprecated) - Use `allowed_kernelspecs` instead.
```

--------------------------------

### Jupyter Client Initialization and Configuration

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Provides details on the initialize function and various configuration attributes for kernel management.

```APIDOC
## initialize(argv=None)

### Description
Initializes the application or component. It accepts an optional argument vector.

### Method
(Not specified, likely a method within a class)

### Endpoint
(Not applicable, likely a function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Example usage (assuming context of a class)
# initialize(argv=['--some-arg'])
```

### Response
#### Success Response
- **Return type:** `None`

## Kernel Attributes

### kernel_argv

An instance of a Python list. Represents the argument vector for the kernel.

### kernel_client_class

Alias for `BlockingKernelClient`. Specifies the class to be used for kernel clients.

### kernel_manager_class

The kernel manager class to use.

### kernel_name

* **Type:** `str` or `Unicode`
* **Description:** The name of the default kernel to start.

### name

* **Type:** `Union`[`str`, `Unicode`]
* **Default:** `'jupyter-console-mixin'`
* **Description:** The name identifier for this component.

### sshkey

Path to the SSH key to use for logging in to the SSH server.

### sshserver

The SSH server to use to connect to the kernel.
```

--------------------------------

### Kernel Polling and State

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Methods and attributes related to starting, stopping, and monitoring the state of a kernel.

```APIDOC
## start()

### Description
Starts the polling of the kernel to monitor its status.

### Method
POST (conceptual, as this is a method call)

### Endpoint
N/A (Python method)

### Parameters
None

### Request Example
```python
kernel_manager.start()
```

### Response
#### Success Response (200)
None (returns None)

#### Response Example
None
```

```APIDOC
## stop()

### Description
Stops the polling of the kernel.

### Method
POST (conceptual, as this is a method call)

### Endpoint
N/A (Python method)

### Parameters
None

### Request Example
```python
kernel_manager.stop()
```

### Response
#### Success Response (200)
None (returns None)

#### Response Example
None
```

```APIDOC
## restart_limit

### Description
Gets or sets the number of consecutive autorestarts before the kernel is presumed dead.

### Method
GET/PUT (conceptual)

### Endpoint
N/A (Python attribute)

### Parameters
None

### Request Example
```python
print(kernel_manager.restart_limit)
kernel_manager.restart_limit = 5
```

### Response
#### Success Response (200)
- **restart_limit** (int) - The current limit for autorestarts.
```

```APIDOC
## stable_start_time

### Description
Gets or sets the time in seconds to consider the kernel to have completed a stable start up.

### Method
GET/PUT (conceptual)

### Endpoint
N/A (Python attribute)

### Parameters
None

### Request Example
```python
print(kernel_manager.stable_start_time)
kernel_manager.stable_start_time = 10.0
```

### Response
#### Success Response (200)
- **stable_start_time** (float) - The time in seconds for stable startup.
```

```APIDOC
## time_to_dead

### Description
Gets or sets the kernel heartbeat interval in seconds.

### Method
GET/PUT (conceptual)

### Endpoint
N/A (Python attribute)

### Parameters
None

### Request Example
```python
print(kernel_manager.time_to_dead)
kernel_manager.time_to_dead = 30
```

### Response
#### Success Response (200)
- **time_to_dead** (int) - The heartbeat interval in seconds.
```

--------------------------------

### Command to List Available Kernel Specs

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/kernels.md

This command-line instruction is used to display all the kernel specifications that Jupyter has discovered and made available on the system. It helps users understand which kernels they can choose from when launching Jupyter applications.

```bash
jupyter kernelspec list
```

--------------------------------

### Kernel Specification JSON

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/wrapperkernels.md

This JSON file defines the metadata and execution command for the Echo kernel. It specifies the display name as 'Echo' and provides the command-line arguments to launch the kernel, which includes executing the 'echokernel' Python module and passing the connection file path.

```json
{
"argv":["python","-m","echokernel", "-f", "{connection_file}"],
"display_name":"Echo"
}
```

--------------------------------

### Manage Kernel Specifications

Source: https://context7.com/jupyter/jupyter_client/llms.txt

This snippet illustrates how to discover, inspect, and manage installed Jupyter kernel specifications using the KernelSpecManager. It covers listing available kernels, retrieving detailed information for a specific kernel, and installing a custom kernel specification. Dependencies include jupyter_client. This functionality is crucial for understanding and configuring available programming environments.

```python
from jupyter_client import KernelSpecManager
from jupyter_client.kernelspec import find_kernel_specs, get_kernel_spec

# List all available kernel specs
ksm = KernelSpecManager()
specs = ksm.find_kernel_specs()
print("Available kernels:")
for name, path in specs.items():
    print(f"  {name}: {path}")

# Get detailed spec for a specific kernel
spec = ksm.get_kernel_spec('python3')
print(f"\nKernel: {spec.display_name}")
print(f"Language: {spec.language}")
print(f"Command: {spec.argv}")
print(f"Interrupt mode: {spec.interrupt_mode}")

# Get all specs with metadata
all_specs = ksm.get_all_specs()
for kernel_name, info in all_specs.items():
    print(f"\n{kernel_name}:")
    print(f"  Resource dir: {info['resource_dir']}")
    print(f"  Display name: {info['spec']['display_name']}")

# Install a custom kernel spec
try:
    installed_path = ksm.install_kernel_spec(
        source_dir='/path/to/kernel/spec',
        kernel_name='my_kernel',
        user=True  # Install in user directory
    )
    print(f"Installed kernel spec to: {installed_path}")
except Exception as e:
    print(f"Installation failed: {e}")
```

--------------------------------

### List Provisioners

Source: https://github.com/jupyter/jupyter_client/blob/main/docs/api/jupyter_client.md

Lists the available provisioners that can be used for kernel specifications within the Jupyter environment. Provisioners manage the lifecycle of kernels.

```APIDOC
## GET /jupyter/kernelspec/provisioners

### Description
Retrieves a list of available provisioners that can be utilized when defining or managing Jupyter kernel specifications. Provisioners are responsible for launching and managing kernel processes.

### Method
GET

### Endpoint
`/jupyter/kernelspec/provisioners`

### Parameters
None

### Response
#### Success Response (200)
- **provisioners** (array) - A list of available provisioner names or objects.

#### Response Example
```json
{
  "provisioners": [
    "local",
    "conda",
    "virtualenv"
  ]
}
```
```