迁移指南#

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

0.5.0 到 0.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#

registerPluginModule 和 registerPluginModules 方法已从 SingleWidgetApp 类中删除。

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

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

@jupyterlite/kernel#

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

@jupyterlite/session#

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

@jupyterlite/contents#

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

ContentsAPI 和 ServiceWorkerContentsAPI 类现在将一个 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.0 到 0.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.0 到 0.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#

  • SingleWidgetShell 的 currentChanged 信号的签名已从 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.0 到 0.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.0 到 0.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 中的 mathjaxConfig 和 fullMathjaxUrl 选项可以删除，因为它们不再有任何效果。

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

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

@jupyterlite 包#

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

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

0.1.0b19 到 0.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-kernel 或 jupyterlite-javascript-kernel。

0.1.0b18 到 0.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.0b17 到 0.1.0b18#

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

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

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

0.1.0b16 到 0.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