迁移指南#
本指南概述了主要(可能存在破坏性)更改以及从一个版本更新 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 仓库。
@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