Kernel Sidecar

概述

kernel-sidecar提供了创建与Jupyter内核并行运行的应用程序的构建块，保持笔记本文档模型在内存中，并作为内核和所有其他客户端之间的中间人。可以构建到Sidecar应用中的功能有很多

• 持久化输出，即使没有客户端连接时也能执行单元格（例如，运行一个单元格，关闭浏览器，稍后回来查看输出）
• 代码单元格代码检查，如black或isort
• 变量浏览器，可以发送到新连接的客户端，而无需在内核中执行代码
• 自定义执行管理器，用于处理DAG/依赖单元格执行或在不向内核发送中断以删除所有队列单元格的情况下，对队列中的单元格进行退队

安装

pip install kernel-sidecar

关键概念

KernelSidecarClient

KernelSidecarClient类管理到内核的ZMQ连接，向内核发送执行请求或其他消息，并处理从内核返回的消息，这些消息在iopub、shell、control和stdin通道上。所有发送和接收的消息都使用Pydantic建模。在准备向内核发送请求时，它结构化为一个KernelAction，该动作将请求与零到多个针对该特定请求的回调连接。

KernelAction

KernelAction连接了侧车应用和内核之间请求-回复流中的三个关键部分

• 存储发送的请求消息
• 根据请求消息将消息委派给回调
• 基于请求类型使流程“可等待”，例如，当接收到execute_reply或error且status变为idle时，完成execute_request。

处理程序

当 KernelSidecarClient 通过 ZMQ 接收到消息，将其解析为 Pydantic 模型，并将它委托给适当的 Action 处理后，它会将该消息传递给所有附加到 Action 的 Handler，并等待它们处理该消息。Handler 对象可以通过创建以消息类型命名的函数来定义处理不同消息类型，例如 async def handle_display_data。请参考 handlers.DebugHandler 或 cli.OutputHandler 的自定义 Handler 示例。

通讯

通讯是客户端和内核在 execute_request 格式之外发送消息的一种灵活方式。可能最广泛使用通讯的包是 ipywidgets，但通讯对于 Sidecar 应用程序来说是一个非常强大的工具。通讯可以由 Sidecar 或内核打开。在打开之前，应该在另一端注册通讯的目标。通常，通过发送 execute_request 在内核中注册通讯目标，然后从 Sidecar 端发送 comm_open。请参考 tests/test_comms.py 的示例。

一旦通讯打开，它就有一个唯一的 comm_id。《KernelSidecarClient》会自动将所有 comm_msg 消息路由到具有相应 comm_id 的 CommHandler 实例。这种路由模式有点令人困惑，因为它与 Handler / Action 模式重叠，但它是因为 comm_msg 可能是作为 execute_request 或 comm_msg 或其他消息的结果而进入的。因此，将 CommManager -> CommHandler 路由基本应用到 KernelSidecarClient 通过 ZMQ 收到的每条消息。

模型

kernel-sidecar 有以下 Pydantic 模型：

• Jupyter Notebook 文档（models/notebook.py），应与 nbformat 解析/结构一致
• 通过 ZMQ 发送到内核的请求消息（models/requests.py）
• 从内核通过 ZMQ 收到的消息（models/messages.py）

CLI

kernel-sidecar 附带了一个用于测试与内核连接的小型 CLI。

❯ sidecar --help
Usage: sidecar [OPTIONS]

Options:
  -f FILE                         Kernel connection file  [required]
  --debug / --no-debug            Turn on DEBUG logging  [default: no-debug]
  --execute TEXT                  Execute code string instead of sending
                                  kernel info request
  --tail / --no-tail              Continue tailing ZMQ after connecting or
                                  executing code  [default: no-tail]
  --install-completion [bash|zsh|fish|powershell|pwsh]
                                  Install completion for the specified shell.
  --show-completion [bash|zsh|fish|powershell|pwsh]
                                  Show completion for the specified shell, to
                                  copy it or customize the installation.
  --help                          Show this message and exit.

通过在一个终端中启动 IPython 内核并在另一个终端中使用 CLI 来尝试它。

python -m ipykernel_launcher --debug -f /tmp/kernel.json

kernel-sidecar on  release-0.3.2 [$?] is 📦 v0.3.1 via 🐍 v3.11.0 (kernel-sidecar-py3.11) 
❯ sidecar -f /tmp/kernel.json
2023-03-10T14:31:59.992235Z [info     ] Attempting to connect:
{'control_port': 34897,
 'hb_port': 49821,
 'iopub_port': 40577,
 'ip': '127.0.0.1',
 'kernel_name': '',
 'key': '615bcebc-baf2e28abad1f6c017dc71dc',
 'shell_port': 37421,
 'signature_scheme': 'hmac-sha256',
 'stdin_port': 41405,
 'transport': 'tcp'} [kernel_sidecar.cli] filename=cli.py func_name=main lineno=62
2023-03-10T14:32:00.026503Z [info     ] {'banner': 'Python 3.11.0 (main, Nov  7 2022, 09:38:45) [GCC 9.4.0]\n'
           "Type 'copyright', 'credits' or 'license' for more information\n"
           "IPython 8.10.0 -- An enhanced Interactive Python. Type '?' for "
           'help.\n',
 'debugger': None,
 'help_links': [{'text': 'Python Reference',
                 'url': 'https://docs.pythonlang.cn/3.11'},
                {'text': 'IPython Reference',
                 'url': 'https://ipython.pythonlang.cn/documentation.html'},
                {'text': 'NumPy Reference',
                 'url': 'https://docs.scipy.org.cn/doc/numpy/reference/'},
                {'text': 'SciPy Reference',
                 'url': 'https://docs.scipy.org.cn/doc/scipy/reference/'},
                {'text': 'Matplotlib Reference',
                 'url': 'https://matplotlib.net.cn/contents.html'},
                {'text': 'SymPy Reference',
                 'url': 'https://docs.sympy.cn/latest/index.html'},
                {'text': 'pandas Reference',
                 'url': 'https://pandas.ac.cn/pandas-docs/stable/'}],
 'implementation': 'ipython',
 'implementation_version': '8.10.0',
 'language_info': {'codemirror_mode': {'name': 'ipython', 'version': 3},
                   'file_extension': '.py',
                   'mimetype': 'text/x-python',
                   'name': 'python',
                   'nbconvert_exporter': 'python',
                   'pygments_lexer': 'ipython3',
                   'version': '3.11.0'},
 'protocol_version': '5.3',
 'status': 'ok'} [kernel_sidecar.cli] filename=cli.py func_name=connect lineno=44

❯ sidecar -f /tmp/kernel.json --execute "print('Hello, World'); 1/0"
2023-03-10T14:33:27.394935Z [info     ] Attempting to connect:
{'control_port': 34897,
 'hb_port': 49821,
 'iopub_port': 40577,
 'ip': '127.0.0.1',
 'kernel_name': '',
 'key': '615bcebc-baf2e28abad1f6c017dc71dc',
 'shell_port': 37421,
 'signature_scheme': 'hmac-sha256',
 'stdin_port': 41405,
 'transport': 'tcp'} [kernel_sidecar.cli] filename=cli.py func_name=main lineno=62
2023-03-10T14:33:27.629630Z [info     ] Hello, World
                  [kernel_sidecar.cli] filename=cli.py func_name=handle_stream lineno=23
2023-03-10T14:33:27.702700Z [error    ] division by zero               [kernel_sidecar.cli] filename=cli.py func_name=handle_error lineno=31