JupyterLab用户指南13:扩展

JupyterLab用户指南

扩展

从根本上说,JupyterLab被设计成一个可扩展的环境。JupyterLab扩展可以自定义或增强JupyterLab的任何部分。它们可以为notebook中的富媒体形式输出提供新主题、文件查看器和编辑器或渲染器。扩展可以向菜单或命令面板、键盘快捷键或设置系统中的设置添加项目。扩展可以提供供其他扩展使用的API,并且依赖于其他扩展。事实上,整个JupyterLab本身只是扩展的集合,其功能和权限并不比自定义扩展强大。有关开发扩展的信息,请参阅开发人员文档

安装扩展

JupyterLab扩展包含安装到Jupyterlab并在浏览器中运行的JavaScript。一个扩展包含一个或多个扩展JupyterLab的插件。JupyterLab扩展有两种类型: 源扩展 (安装后需要重建JupyterLab) 和预构建扩展 (不需要重建JupyterLab)。重建JupyterLab需要安装Node.js

JupyterLab扩展可以通过多种方式安装,包括:

  • Python pipconda包可以包含源扩展或预构建扩展。这些包还可以包括扩展运行所需的服务器端组件。
  • JupyterLab中的扩展管理器和jupyter labextension install命令可以从npm安装源扩展包。

安装源扩展需要Node.js并且重建JupyterLab才能激活。请参阅Installing Node.js 以及 Managing Extensions with jupyter labextension

安装Node.js

源扩展需要Node.js重建JupyterLab并激活扩展。如果将condaconda-forge包一起使用,则可以使用以下命令获取Node.js:

conda install -c conda-forge nodejs

如果您将conda与默认Anaconda包一起使用 (即,您通常不使用conda-forge),您应该使用conda install nodejs从Anaconda默认通道安装Node.js。 您也可以从系统包管理器中获取Node.js,或者从Node.js website网站下载Node.js并直接安装。

使用jupyter labextension管理扩展

jupyter labextension命令使您能够从npm安装或卸载源扩展、列出已安装的扩展或禁用扩展。请参阅jupyter labextension --help获取帮助。

安装和卸载源扩展

You can install source extensions from npm with:

您可以通过以下方式从npm安装源扩展:

jupyter labextension install my-extension my-other-extension

使用my-extension@version语法安装扩展的特定版本,例如:

jupyter labextension install my-extension@1.2.3

您还可以安装未上传到npm的源扩展,即,my-extension可以是包含扩展的本地目录、Gzip压缩文件或Gzip压缩文件的URL。

安装源扩展将需要安装Node.js并需要重建JupyterLab。

使用以下命令卸载源扩展:

jupyter labextension uninstall my-extension my-other-extension

如果要分几个阶段安装/卸载多个扩展,则可能需要通过在安装/卸载步骤中加入 --no-build标签来推迟重建JupyterLab。准备好重建后,可以运行以下命令:

jupyter lab build

如果要在Windows上重建JupyterLab,由于Windows上的默认路径长度,您可能会遇到FileNotFoundError。节点模块存储在深度嵌套的目录结构中,因此路径会变得相当长。如果您具有管理访问权限并且是Windows 8或10,则可以使用以下说明更新注册表设置: https://stackoverflow.com/a/37528731

列出已安装的扩展

列出所有已安装的扩展,包括安装有pipconda的扩展,需执行以下命令:

jupyter labextension list

jupyter labextension通过其JavaScript包名称来标识扩展,该名称可能不同于用于分发扩展的pipconda包的名称。

启用和禁用扩展

禁用扩展可阻止扩展中的所有插件在JupyterLab中运行 (尽管代码仍会被加载)。通过以下方式,您无需重建JupyterLab也可禁用特定的JupyterLab扩展 (包括核心扩展):

jupyter labextension disable my-extension

您可以通过以下方式启用禁用的扩展:

jupyter labextension enable my-extension

已安装的扩展在默认情况下处于启用状态,除非有配置明确禁用它们。可以使用命令行禁用或启用扩展。扩展或扩展中的单个插件可以由另一个扩展禁用。

确定扩展是启用还是禁用的优先级顺序如下:

  • 出现 <jupyter_config_path>/labconfig/pageconfig.json文件,该文件具有disabledExtensions键,该键是以包名称作为键和布尔值的对象。
  • (已弃用) 在 <lab_app_dir>/settings/pageconfig.json中出现disabledExensions键。此值是要禁用的扩展列表,但不推荐使用,应采用labconfig位置中的分层配置方法。
  • 另一个JupyterLab扩展的元数据中出现disabledExtensions键,该键禁用指定扩展。如果该扩展本身已被禁用,则忽略该键。

使用命令行时,您可以定位配置的--level: user, system, 或 sys-prefix (默认)。 示例 <jupyter_config_path>/labconfig/pageconfig.json如下所示:

有关详细信息,请参阅有关LabConfig 目录的文档。

使用扩展管理器管理扩展

您可以使用JupyterLab中的扩展管理器来管理在npm上作为单个JavaScript包分发的扩展。

扩展管理器位于左侧边栏中。

: 默认视图有三个组件: 搜索栏、 “已安装” 部分以及 “发现” 部分。

免责声明

安装扩展允许其在服务器、内核和浏览器上执行任意代码。因此,我们要求您明确了解并同意这一情况。在默认情况下,免责声明需要用户确认同意。

图: 用户尚未确认同意该免责声明由于该免责声明尚未被同意,用户可以搜索某扩展,但无法安装 (没有可用的安装按钮)。

图: 您尚未勾选免责声明,不能安装该扩展要安装扩展,您首先必须同意并勾选该免责声明。完成后,这将保留在整个会话中,用户不必再次勾选。

图: 已同意并勾选免责声明为了便于使用,您可以隐藏免责声明,以减少其占用屏幕空间。

图: 免责声明已被隐藏

查找扩展

您可以使用扩展管理器查找JupyterLab的扩展。要在当前可用的扩展中自由查找,请扩展 “Discovery” 部分。这将触发对NPM注册表上所有JupyterLab扩展的搜索,并根据注册表的排序顺序列出结果。一种例外情况是,Jupyter组织发布的扩展总是排在前面。这些扩展的名称旁带有Jupyter图标。

或者,您可以使用搜索栏限制查找。这将在NPM注册表上执行JupyterLab扩展的自由文本搜索。

安装扩展

找到您认为有趣的源扩展后,请单击扩展列表条目的 “Install” 按钮进行安装。

安装扩展允许它在服务器、内核和客户端浏览器中执行任意代码。因此,您应该避免安装您不信任的扩展,并注意任何试图伪装成可信扩展的扩展。

开始安装扩展后不久,搜索栏下会出现一个下拉列表,显示扩展已下载,但需要重建才能完成安装。

如果您也想安装/卸载其他扩展,您可以忽略重建通知,直到您做了所有您想要的更改。满意后,单击 “Rebuild” 按钮在后台开始重建。重建完成后,将弹出一个对话框,指示需要重新加载页面才能将最新版本加载到浏览器中。如果您错误地忽略了重建通知,只需刷新浏览器窗口以触发新的重建检查。

管理已安装的扩展

扩展安装完成后将显示在 “Installed” 部分。之后便可以卸载 (如果它们是源扩展) 或禁用这些扩展。禁用扩展将阻止其被激活,但不会重建应用程序。

配套包

在安装扩展期间,JupyterLab将检查包的元数据,以获取有关配套包的任何说明。配套包可以是:

列表

在扩展管理器中搜索源扩展时,JupyterLab会显示完整的搜索结果,用户可自由安装任何源扩展。这是默认模式。为了提高安全性,您或您的管理员可以启用blocklistsallowlists模式。JupyterLab将根据定义的列表检查扩展。

警告 只允许存在一种模式。如果您或您的服务器管理员同时配置了阻止列表和允许列表,那么JupyterLab服务器将不会启动。

: 同时阻止和允许列表

下面详细介绍了Blocklist模式和Allowlist模式的行为。启用配置列表的详细信息请参阅Listing Configuration

默认模式

default模式下,没有列表启动,并且搜索行为如前文所述不变。

阻止列表模式

扩展可以随意下载,无需经过审查。但是,用户可以将恶意扩展添加到阻止列表中。除了已明确添加到阻止列表中的扩展,扩展管理器将显示其他所有扩展。因此,扩展管理器不允许您安装阻止列表中的扩展。

如果您或您的管理员启用了阻止列表模式,JupyterLab将使用阻止列表并在搜索结果中删除所有阻止列表中的扩展。

如果您在某扩展被屏蔽之前已对其进行安装,则在已安装列表中的该扩展条目会被红色高亮。建议您卸载它。您可以在移动鼠标至问号图标阅读说明细则。

图:被屏蔽的已安装扩展,应将其删除

允许列表模式

允许列表中是一组被核准、用户能自由搜索和安装的扩展。扩展在添加到允许列表之前需要经过某种审核过程。使用允许列表时,扩展管理器将仅显示已明确添加到该列表中的扩展。

如果您或您的管理员启用了允许列表模式,JupyterLab将使用允许列表,并且仅显示该白名单中的扩展。其他扩展将不会显示在搜索结果中。

如果您已经安装了允许列表中的某个扩展,然后在某个时间点该扩展已从列表中删除,则已安装列表中的该扩展条目将被红色高亮。建议您卸载它。您可以将鼠标移至问号图标上阅读说明细则。

图: 第二个已安装的扩展已从允许列表中删除,应将其删除

列表配置

您或您的管理员可以使用以下特征来定义列表加载。

  • blocklist_uris: 以逗号分隔的URIs列表,从中获取阻止列表文件
  • allowlist_uris: 以逗号分隔的URIs列表,从中获取允许列表文件
  • listings_refresh_seconds: 刷新列表的间隔延迟 (秒)
  • listings_request_options: 用于列表 HTTP请求的可选关键字参数

例如,要启用blocklist,请使用 -- LabServerApp.blocklist_uris=http://example.com/blocklist.json 启动服务器,其中 [http://example.com/blocklist.json](http://example.com/blocklist.json) 是如下所述的blocklist JSON文件。

此页列出了listings_request_options的详细信息 (例如,您可以通过{'timeout': 10}来更改HTTP请求超时值)。

这些列表是托管在您所给出的URIs上的json文件。。name属性支持正则表达式。您也可以选择为您的记录添加更多字段 (type, reason, creation_date, last_update_date)。这些可选字段不在用户界面中使用。这是一个阻止列表文件的示例。

{
"blocklist": [
   {
      "name": "@jupyterlab-examples/launcher",
      "type": "jupyterlab",
      "reason": "@jupyterlab-examples/launcher is blocklisted for test purpose - Do NOT take this for granted!!!",
      "creation_date": "2020-03-11T03:28:56.782Z",
      "last_update_date":  "2020-03-11T03:28:56.782Z"
   }
]
}

In the following allowlist example a @jupyterlab/* will allowlist all jupyterlab organization extensions. 在以下允许列表示例中,@jupyterlab/* 将允许所有jupyterlab组织扩展。

{
"allowlist": [
   {
      "name": "@jupyterlab/*",
      "type": "jupyterlab",
      "reason": "All @jupyterlab org extensions are allowlisted, of course...",
      "creation_date": "2020-03-11T03:28:56.782Z",
      "last_update_date":  "2020-03-11T03:28:56.782Z"
   }
]
}

JupyterHub上的JupyterLab

JupyterHub 1.0+的JupyterLab可开箱即用,甚至可以与经典Notebook并行运行。 当使用JupyterHub部署JupyterLab时,它将在File菜单中显示允许用户注销或跳转到JupyterHub控制面板的其他菜单项。

默认情况下使用JupyterLab

如果您在运行JupyterHub的系统上安装JupyterLab,它将即刻在/lab URL上可用,但默认情况下,用户仍将被定向到经典Notebook (/tree)。要将用户的默认用户界面更改为JupyterLab,请在jupyterhub_config.py文件中设置以下配置选项:

c.Spawner.cmd=["jupyter-labhub"]

在此配置中,用户仍然可以通过在浏览器中输入该URL或使用JupyterLab的Help菜单中的 “Launch Classic Notebook” 项来访问/tree上的经典notebook。

示例配置

有关将JupyterLab与JupyterHub一起使用的全面配置的示例,请参阅jupyterhub-deploy-teaching 资源库。

客服