迁移指南#

本指南概述了主要(可能存在破坏性)更改以及从一个版本更新 JupyterLite 到另一个版本所需的步骤。

0.5.00.6.0#

警告

JupyterLite 0.6.0 带来了一些主要的更改,根据您的 JupyterLite 设置,这些更改可能被视为破坏性的。请仔细阅读以下部分,检查您是否受到这些更改的影响

扩展#

JupyterLite 0.6.0 基于 JupyterLab 4.4 和 Jupyter Notebook 7.4 包。

此更新可能会影响您正在使用的扩展,因为它们可能依赖于 JupyterLab 4.4 和 Notebook 7.4 中引入的功能。

内容#

使用 jupyter-server 进行文件索引#

以前,如果缺少 jupyter-server 依赖项(用于索引文件),使用指定内容选项(例如 jupyter lite build --contents contents)运行构建只会简单地在构建日志中记录一个警告,这使得调试内容和文件丢失的问题变得困难。

在 JupyterLite 0.6.0 中,如果在未安装 jupyter-server 的情况下提供了 contents 选项,构建将失败。

浏览器存储#

以前,默认的内容管理器将文件存储在浏览器的本地存储(默认是 IndexedDB)中,键为“JupyterLite Storage”。这导致在同一来源下的不同 JupyterLite 部署之间“共享”文件,给用户带来一些困惑。

从 JupyterLite 0.6.0 开始,默认的内容管理器现在在存储键中使用基本 URL。例如,如果您在同一来源下有两个 JupyterLite 部署:

  • https://example.com/lite1

  • https://example.com/lite2

内容将存储在以下键下:

  • JupyterLite 存储 - /lite1

  • JupyterLite 存储 - /lite2

这意味着如果您或您的用户以前在其中一个部署中创建了文件,它们将不再可用。

要使用与以前相同的默认内容存储名称,您可以在 jupyter-lite.json 文件中将 contentsStorageName 选项设置为 JupyterLite Storage。例如:

{
  "jupyter-lite-schema-version": 0,
  "jupyter-config-data": {
    "contentsStorageName": "JupyterLite Storage"
  }
}

设置#

与上面提到的内容存储类似,默认设置存储现在在存储键中使用基本 URL。这意味着如果您或您的用户以前在界面中更改了一些设置(例如主题),在更新到 JupyterLite 0.6.0 后,这些设置将不再应用。

要配置自定义设置存储名称,您可以在 jupyter-lite.json 文件中设置 settingsStorageName 选项。例如:

{
  "jupyter-lite-schema-version": 0,
  "jupyter-config-data": {
    "settingsStorageName": "JupyterLite Storage"
  }
}

API 变更#

在 0.6.0 版本之前,JupyterLite 将扩展分为两类:

  • 常规 JupyterLab 扩展,以与 JupyterLab 相同的方式加载

  • “serverlite”扩展,在单独的 Lumino 应用程序上加载,例如自定义内核

为了替换默认的 serverlite 插件或添加额外的“服务器”功能,扩展作者必须提供一个 JupyterLiteServerPlugin

从 JupyterLite 0.6.0 开始,所有插件都注册到相同的插件注册表,包括内核和其他“服务器”插件,例如内核和会话管理器。这些插件现在是常规的 JupyterFrontEndPlugin 实例,或 ServiceManagerPlugin 实例(在 JupyterLab 4.4 中引入)。

因此,扩展不再需要在其 package.json 文件中使用 "liteExtensions": true 字段。该字段以前用于指示扩展是“serverlite”扩展。

以下是此架构更改导致的不同包中的更改。

如何迁移您的内核#

如果您编写了自定义内核,它应该在 JupyterLite 0.6.0 中继续正确加载。

但是,您可能希望对您的内核扩展进行以下更改:

  • 更新插件定义以使用 JupyterFrontEndPlugin 而不是 JupyterLiteServerPlugin

 /**
  * A plugin to register the custom kernel.
  */
-const kernel: JupyterLiteServerPlugin<void> = {
+const kernel: JupyterFrontEndPlugin<void> = {
   id: 'my-custom-kernel:plugin',
   autoStart: true,
   requires: [IKernelSpecs],
-  activate: (app: JupyterLiteServer, kernelspecs: IKernelSpecs) => {
+  activate: (app: JupyterFrontEnd, kernelspecs: IKernelSpecs) => {
     kernelspecs.register({
       spec: {
         name: 'custom',

服务工作线程#

插件名称#

服务工作线程插件,在 SharedArrayBuffer 不可用时同步 JupyterLite 文件浏览器和内核之间的内容,已移至 @jupyterlite/application-extension 包。

如果您在自定义 jupyter-lite.json 文件中禁用了服务工作线程,您需要更新插件名称以禁用,如下所示:

{
  "jupyter-lite-schema-version": 0,
  "jupyter-config-data": {
-   "disabledExtensions": ["@jupyterlite/server-extension:service-worker"]
+   "disabledExtensions": ["@jupyterlite/application-extension:service-worker-manager"]
  }
}
服务工作线程通信#

服务工作线程使用 BroadcastChannel 与主线程通信。在以前的版本中,广播通道通过 IBroadcastChannelWrapper 提供给内核,并由 @jupyterlite/server-extension:emscripten-filesystem 插件提供。

从 JupyterLite 0.6.0 开始,服务工作线程管理器插件现在通过 @jupyterlite/application-extension:service-worker-manager 插件直接管理 BroadcastChannel

除了驱动器请求,BroadcastChannel 现在还处理 stdin 请求。

结果是:

  • IBroadcastChannelWrapper 已从 @jupyterlite/server 包中删除。

  • @jupyterlite/server-extension:emscripten-filesystem 插件已从 @jupyterlite/server-extension 包中删除。

  • BroadcastChannel ID 已从 '/api/drive.v1' 重命名为 '/sw-api.v1'

IBroadcastChannelWrapper@jupyterlite/server-extension:emscripten-filesystem 插件主要用于提供围绕文件系统访问所用的 BroadcastChannel 的便捷包装。此功能现在由 @jupyterlite/application-extension:service-worker-manager 插件及其 IServiceWorkerManager 服务处理。

如果您有自定义内核并且需要启用文件系统访问,请参阅 Pyodide 内核中的实现。

@jupyterlite/server#

以下类和接口已被删除:

  • JupyterLiteServer

  • JupyterLiteServerPlugin

  • Router

@jupyterlite/application#

registerPluginModuleregisterPluginModules 方法已从 SingleWidgetApp 类中删除。

如果您正在创建自己的 SingleWidgetApp 实例并使用这些方法注册插件,您现在应该使用 PluginRegistryPluginRegistry 现在是 JupyterLab 4.4 和 JupyterLite 0.6.0 中管理和解析插件的中心机制。

PluginRegistry 提供了一种更集中的插件管理方法,允许您在创建应用程序实例之前注册插件并通过注册表解析服务。

@jupyterlite/kernel#

以前用于在浏览器中管理内核的 Kernels 类(及其 IKernels 接口)已分别重命名为 LiteKernelClientIKernelClientIKernelClient 现在扩展了 @jupyterlab/services 提供的 IKernelAPIClient

@jupyterlite/session#

以前用于在浏览器中管理会话的 Sessions 类已重命名为 LiteSessionClient,它现在实现了 @jupyterlab/services 中的 ISessionAPIClient 接口。

@jupyterlite/contents#

以前用于在浏览器中管理内容的 Contents 类已重命名为 BrowserStorageDrive,并且现在实现了 @jupyterlab/services 中的 IDrive 接口。此驱动器现在通过 IDefaultDrive 作为默认驱动器提供。

ContentsAPIServiceWorkerContentsAPI 类现在将一个 options 对象作为其 constructor 的参数。

@jupyterlite/licenses#

警告

@jupyterlite/licenses 包已在 JupyterLite 0.6.0 中删除。

以前用于在浏览器中管理许可证的 Licenses 类已进行了重大的 API 更改。它现在实现了 @jupyterlab/apputils 中的 ILicensesClient 接口,并作为插件通过 @jupyterlite/apputils-extension:licenses-client 插件提供。

@jupyterlite/server-extension#

@jupyterlite/server-extension 包已被删除。JupyterLite 服务插件(内核、会话、内容、设置等)现在由 @jupyterlite/services-extension 包作为 ServiceManagerPlugin 插件提供。

@jupyterlite/settings#

以前用于在浏览器中管理设置的 Settings 类已替换了 JupyterLab 提供的默认 Setting.IManager。其 API 也相应地进行了更改,以满足 Setting.IManager 接口。

@jupyterlite/settings 包不再导出任何令牌。

@jupyterlite/translation#

警告

@jupyterlite/translation 包已在 JupyterLite 0.6.0 中删除。

现在通过实现 JupyterLab 提供的 ITranslatorConnector 接口来支持翻译,然后通过 @jupyterlite/apputils-extension:translator-connector 插件公开。

0.4.00.5.0#

扩展#

JupyterLite 0.5.0 基于 JupyterLab 4.3 和 Jupyter Notebook 7.3 包。

虽然预计不会有破坏性更改,但这可能会影响您正在使用的扩展,因为它们可能依赖于 JupyterLab 4.3 和 Notebook 7.3 中添加的功能。

有关更多信息,请参阅 JupyterLab 和 Notebook 的更新日志:

jupyterlite-core#

已停止支持 Python 3.8。 jupyterlite-core 现在需要 Python 3.9 或更高版本。

API 变更#

@jupyterlite/kernel#

IKernel 接口现在包含一个 changed 信号,该信号在内核启动或停止时发出。这应该只影响实现该接口以提供 JupyterLite 的自定义内核管理器的扩展。

配置#

以下配置选项已从 JupyterLite 模式中删除:

  • collaborative

  • fullWebRtcSignalingUrls

0.3.00.4.0#

扩展#

JupyterLite 0.4.0 基于 JupyterLab 4.2 和 Jupyter Notebook 7.2 包。

虽然预计不会有破坏性更改,但这可能会影响您正在使用的扩展,因为它们可能依赖于 JupyterLab 4.2 和 Notebook 7.2 中添加的功能。

有关更多信息,请参阅 JupyterLab 和 Notebook 的更新日志:

从内核访问文件#

JupyterLite 0.4.0 引入了一种更健壮的方式来从内核访问文件。

以前,JupyterLite 依赖于服务工作线程使文件对内核可见,以便用户可以通过笔记本中的代码操作它们。从 0.4.0 版本开始,JupyterLite 允许内核利用共享内存(通过 SharedArrayBuffer)来使文件访问更加健壮和有弹性,并避免缓存问题。

如果 COOP 和 COEP 头存在,JupyterLite 会通过 SharedArrayBuffer 使用共享内存来启用文件访问。否则,它会像以前一样默认使用服务工作线程。

有关更多信息,请参阅访问文件文档

API 变更#

@jupyterlite/application#

  • SingleWidgetShellcurrentChanged 信号的签名已从 ISignal<ISingleWidgetShell, void> 更改为 ISignal<ISingleWidgetShell, FocusTracker.IChangedArgs<Widget>>

这遵循了 JupyterLab 中的此更改: 添加 IShell.currentChanged 并根据它通知命令

@jupyterlite/contents#

TypeScript 接口 IEmscriptenNodeOps 已更改。所有方法现在都接受 IEmscriptenFSNode | IEmscriptenStream 作为输入,而不仅仅是 IEmscriptenFSNode。实现 IEmscriptenNodeOps 的类需要相应地更新。有关示例实现,请参阅 https://github.com/jupyterlite/jupyterlite/pull/1395。

TypeScript 接口 IDriveRequest 已删除。它已被类型定义 TDriveRequest<T extends TDriveMethod> 替换。这允许根据请求类型进行更精细的类型化。驱动器响应类型 TDriveResponse<T extends TDriveMethod> 也是如此。例如,一个“readdir”驱动器请求的类型将是 TDriveRequest<'readdir'>,其响应类型将是 TDriveResponse<'readdir'>

提供了一个新类 DriveContentsProcessor,它允许使用 jupyterlite 内容管理器执行驱动器请求。Emscripten 内核作者可以将其与扩展抽象 ContentsAPI 类结合使用,以提供自定义方式来实现从内核访问文件(例如,绕过服务工作线程方法)。

0.2.00.3.0#

扩展#

JupyterLite 0.3.0 基于 JupyterLab 4.1 和 Jupyter Notebook 7.1 包。

虽然预计不会有破坏性更改,但这可能会影响您正在使用的扩展,因为它们可能依赖于 JupyterLab 4.1 和 Notebook 7.1 中添加的功能。

jupyterlite 元包#

在 JupyterLite 0.3.0 之前,安装 jupyterlite 元包也会默认通过依赖 jupyterlite-javascript-kernel 安装 JavaScript (Web Worker) 内核。

现在已删除对 jupyterlite-javascript-kernel 的此依赖项,因此如果您想使用该内核,可能需要明确将 jupyterlite-javascript-kernel 添加到您的构建依赖项中。

注意

作为 jupyterlite-javascript-kernel 的替代方案,您可能还希望使用 Xeus JavaScript,它目前提供更多功能并且通常更具可用性。

注意

jupyterlite-javascript-kernel 现已移至 jupyterlite-javascript-kernel 仓库。

服务工作线程#

JupyterLite 使用服务工作线程使文件和笔记本对内核可见,以便用户可以通过笔记本中的代码操作它们。

在以前的版本中,服务工作线程默认启用了缓存,并且无法轻松禁用它。

然而,服务工作线程缓存是导致从内核访问文件时出现许多问题的原因,经常给用户带来错误,他们不得不清除缓存才能解决问题。

在 JupyterLite 0.3.0 中,服务工作线程缓存默认处于禁用状态,但如果需要,仍然可以启用它。

要启用服务工作线程缓存,请将 enableServiceWorkerCache 选项添加到您的 jupyter-lite.json 文件中。例如:

{
  "jupyter-lite-schema-version": 0,
  "jupyter-config-data": {
    "enableServiceWorkerCache": true
  }
}

0.1.00.2.0#

扩展#

JupyterLite 0.2.0 基于 JupyterLab 4 和 Jupyter Notebook 7 包。

JupyterLab 4 带来了一些可能影响扩展的破坏性更改。

如果您在 JupyterLite 部署中使用了 JupyterLab 3 扩展,您可能需要更新到与 JupyterLab 4 兼容的更新版本。

注意

对于扩展作者,请查看 JupyterLab 文档中的扩展迁移指南

Jupyter Notebook 7#

在 JupyterLite 0.1.x 中,笔记本界面由 RetroLab 提供。

在 JupyterLite 0.2.0 中,笔记本界面现在由 Jupyter Notebook 7 提供。

Jupyter Notebook 7 是 RetroLab 和经典笔记本的后继者,基于 JupyterLab 组件。

这意味着 URL 也已更改,以与 Jupyter Notebook 7 提供的 URL 对齐:

  • /retro/consoles -> /consoles

  • /retro/edit -> /edit

  • /retro/notebooks -> /notebooks

  • /retro/tree -> /tree

jupyterlite 元包#

0.1.x 版本中,安装 jupyterlite 元包会自动默认安装 Pyodide 内核,因为 jupyterlite 元包将依赖于 jupyterlite-pyodide-kernel

0.2.0 版本中不再是这种情况。您需要在构建环境中与 jupyterlite-core(提供 jupyter-lite CLI 的包)一起显式安装 jupyterlite-pyodide-kernel

请参阅添加内核的文档以了解更多信息。

服务工作线程#

服务工作线程文件名已更改。在 0.1.0 中,它是 service-worker-[hash].js,其中 hash 由 webpack 计算;在 0.2.0 中,哈希被删除,新文件名为 service-worker.js

API 变更#

jupyterlite-core#

  • Mathjax 插件已从 jupyterlite-core 包中删除。因此,jupyter-lite.json 中的 mathjaxConfigfullMathjaxUrl 选项可以删除,因为它们不再有任何效果。

    如果您想使用 Mathjax 2,可以安装 jupyterlab-mathjax2。有关更多信息,请参阅 jupyter-renderers 仓库。

    作为参考,请参阅更新到 Mathjax 3 的 JupyterLab Pull Request

@jupyterlite#

这些 API 更改仅在您在下游应用程序中重用 @jupyterlite 包时才相关。

  • @jupyterlite/kernels 公开的 IKernel 接口有一个新的 get 方法,用于按 ID 检索正在运行的内核。

0.1.0b190.1.0b20#

jupyterlite-core#

通过 jupyterlite-core 包分发的静态资产不再包含 JavaScript 内核。

相反,JavaScript 内核现在通过单独的 jupyterlite-javascript-kernel 包分发。

如果您想在部署中包含 JavaScript 内核,您必须在构建 JupyterLite 站点之前先安装它。例如:

python -m pip install jupyterlite-javascript-kernel

或者将其添加到 LiteBuildConfig/federated_extensions 配置条目。

目前,jupyterlite 包仍然通过依赖 jupyterlite-javascript-kernel 来包含 JavaScript 内核。但这可能会在未来的版本中发生变化。

我们建议您开始直接为您的部署使用 jupyterlite-core 包,并显式添加更多内核,例如 jupyterlite-pyodide-kerneljupyterlite-javascript-kernel

0.1.0b180.1.0b19#

jupyterlite-core#

此版本引入了一个新的 jupyterlite-core 包,除了现有的 jupyterlite 包。

jupyterlite-core 包提供了构建 JupyterLite 网站 CLI 扩展点的核心功能。目前它只包含一个在 Web Worker 中运行的 JavaScript 内核。如果您想在部署中包含 Python 内核,您必须在构建 JupyterLite 站点之前先安装它。例如:

python -m pip install jupyterlite-pyodide-kernel

或者将其添加到 LiteBuildConfig/federated_extensions 配置条目。

jupyterlite 包目前提供了一些 shim 以及 Pyodide 内核,以更好地兼容现有部署。

我们建议您开始为您的部署使用 jupyterlite-core 包,并额外安装 Python 内核,例如 jupyterlite-pyodide-kernel 或 Xeus 内核。

jupyterlite-pyodide-kernel#

Pyodide 内核已移至其自己的仓库:jupyterlite/pyodide-kernel

目前为了方便,它仍然默认与 jupyterlite 一起安装,但它不是 jupyterlite-core 的一部分。

此更改的一个结果是 pyolite JavaScript 包的重命名:

  • @jupyterlite/pyolite-kernel -> @jupyterlite/pyodide-kernel

  • @jupyterlite/pyolite-kernel-extension -> @jupyterlite/pyodide-kernel-extension

如果您使用了 litePluginSettings,请务必更新您的配置。

0.1.0b170.1.0b18#

JavaScript 内核现在在 Web Worker 而不是 IFrame 中运行,以简化 JupyterLite 中默认内核的运行方式。

这可能会影响扩展基本 JavaScriptKernel 的自定义内核作者,例如 https://github.com/jupyterlite/p5-kernel。

这在以下 PR 中进行了更改: #711

0.1.0b160.1.0b17#

使用 PipliteAddon.piplite_urls 而不是 LiteBuildConfig.piplite_urls#

如果您正在配置 piplite_urls 选项(在 https://python.org/en/stable/howto/python/wheels.html 中描述)以在构建时发送额外的 wheel,则此配置选项已从 LiteBuildConfig.piplite_urls 移至 PipliteAddon.piplite_urls

如果使用 jupyter_lite_build.json 文件,配置应如下所示:

{
  "PipliteAddon": {
    "piplite_urls": ["url-to-wheel1", "url-to-wheel2", "..."]
  }
}

这在以下 PR 中进行了更改: #934