JupyterLab用户指南16：高级用法

JupyterLab用户指南

JupyterLab为其数据管理多个不同的位置。通过运行jupyter lab path显示这些位置:

  • Application Directory: JupyterLab在其中存储JupyterLab的主要构建及相关数据，包括内置于JupyterLab中的扩展。
  • User Settings Directory: JupyterLab在其中存储JupyterLab扩展的用户级设置
  • Workspaces Directory: JupyterLab在其中存储工作区

JupyterLab还为来自Jupyter路径层级中Jupyterconfig目录-labconfig分目录的配置数据执行LabConfig Directories目录。 此外，JupyterLab可以从Jupyterdata目录的labextensions子目录加载动态联合扩展，即捆绑依赖项的扩展。 通过运行jupyter --path查看这些Jupyter配置路径的位置。

JupyterLab构建流程

重建应用程序目录，请运行jupyter lab build。默认情况下，jupyter labextension install 命令构建应用程序，因此您通常不需要直接调用build 。

构建包括:

  • 使用模板文件填充staging/目录
  • 处理本地安装的包
  • 确保所有已安装资产可用
  • 捆绑资产
  • 将捆绑资产复制到static目录

请注意，构建将始终使用最新的JavaScript包，该JavaScript包符合JupyterLab自身和任何已安装扩展的依赖要求。如果您希望使用Python包附带的固定要求运行JupyterLab，则可以通过jupyter lab --core-mode启动。

构建过程使用特定的yarn版本以及JupyterLab附带的yarn.lock 文件中存储的npm包的默认工作组合。这些包源url指向默认的yarn注册表。

但是，如果您在yarn配置中自行定义了yarn注册表，那么默认的yarn注册表将被你的自定义注册表替换。如果随后切换回默认的yarn注册表，则需要在构建之前清理你的staging文件夹:

jupyter lab clean
jupyter lab build

禁用重建检查

JupyterLab会自动检查启动时是否需要重建。在某些情况下，例如自动测试，您可能希望完全禁用启动重建检查。这可以通过设置buildCheck以及buildAvailable实现，buildCheck和buildAvailable可在jupyter --paths返回的任一config位置中的jupyter_notebook_config.json (或.py等价)找到 。

{
  "LabApp": {
    "tornado_settings": {
      "page_config_data": {
        "buildCheck": false,
        "buildAvailable": false,
      }
    }
  }
}

LabConfig目录

对于jupyter --paths中列出的每个配置路径<jupyter_config_path>，<jupyter_config_path>/labconfig目录包含配置数据。来自所有这些目录的配置数据被组合成一个配置，优先级顺序由jupyter --paths给出。

JupyterLab使用的主文件是page_config.json。page_config.json数据用于向应用程序环境提供配置数据。

此文件中可能存在以下配置:

  1. terminalsAvailable标识终端是否 (即Mac/Linux上的bash/tsch或Windows上的PowerShell) 可通过启动器启动。(在Jupyter Lab中启用PowerShell访问之前，Windows主要需要此配置。)此字段的值为Boolean: true或false。
  2. disabledExtensions控制哪些扩展不应该加载。
  3. deferredExtensions控制哪些扩展在需要时才加载，不管是否将autoStart设置为true

disabledExtensions和deferredExtensions字段值是具有布尔值的对象。对disabledExtensions和deferredExtensions模式执行以下检查顺序。

  • 如果配置值和包名称之间有相同的字符串匹配 (例如"@jupyterlab/apputils-extension")，那么整个包被禁用 (或延迟)。
  • 如果将字符串值编译为正则表达式，并且针对包名称的测试为阳性 (例如"@jupyterlab/apputils*$")，那么整个包被禁用 (或延迟)。
  • 如果在包中的配置值和单个插件ID之间有相同的字符串匹配 (例如"@jupyterlab/apputils-extension:settings)，那么该插件被禁用 (或延迟)。
  • 如果字符串值被编译为正则表达式，并且针对包中的单个插件ID测试为阳性 (例如"@jupyterlab/apputils-extension:set.*$")，那么该插件被禁用 (或延迟)。

示例<jupyter_config_path>/labconfig/pageconfig.json如下：

{
   "disabledExtensions": {
         "@jupyterlab/notebook-extension": true,
         "@jupyterlab/apputils-extension:settings": true
   },
   "deferredExtensions": {
          "@jupyterlab/apputils-extension:set.*$": true
   },
   "terminalsAvailable": false
}

有关更多信息，请参阅documentation on enabling and disabling extensions 。

JupyterLab应用程序目录

应用程序目录包含主要的JupyterLab应用程序文件，包括构建的资产、用于重建JupyterLab的文件、已安装的扩展和链接包等。

默认情况下，应用程序目录位于 <sys-prefix>/share/jupyter/lab，其中 <sys-prefix> 是当前Python环境下特定站点的目录前缀。您可以通过运行jupyter lab path查询当前应用程序路径。可以使用任何JupyterLab命令中的 --app-dir命令行选项，或通过设置JUPYTERLAB_DIR环境变量，来覆盖应用程序目录。

我们建议用户不要在类似Unix系统上的系统位置安装JupyterLab，因为这样应用程序目录将是只读状态。使用conda环境或pip install --user jupyterlab，这样应用程序目录是用户可写的。

此目录位置和语义不遵循标准的Jupyter配置语义，因为我们需要构建单个统一的应用程序，并且Jupyter的默认配置位置位于用户级别 (用户的主目录)。通过显式使用sys-前缀目录，我们可以确保在虚拟环境中实现更好的隔离。

JupyterLab应用程序目录包含子目录extensions、schemas、 settings、 staging、 static、 和 themes。在本节的剩余部分，我们将解释每个子目录。

扩展

extensions目录为应用程序的每个已安装扩展提供打包工具。如果应用程序目录与sys-prefix目录不同，则安装在sys-prefix目录中的扩展将在应用程序目录中使用。如果在sys-prefix目录中存在的应用程序目录中安装了扩展，它将阴影sys-prefix版本。卸载某扩展将首先卸载该阴影扩展，之后会尝试卸载sys-prefix版本 (如果再次调用)。如果无法卸载sys-prefix版本，仍可使用settings中的ignoredPackages元数据忽略其插件。

schemas

模式

schemas目录包含JSON Schemas，JSON Schemas描述各个扩展使用的设置。用户可以使用JupyterLab高级设置编辑器Advanced Settings Editor编辑这些设置。

设置

settings目录可能包含page_config.json, overrides.json, 以及/或者 build_config.json文件，具体取决于您系统上设置的配置。

page_config.json (已弃用)

此文件被视为已弃用。该文件可以具有与LabConfig目录中page_config.json文件相似的数据，不同之处在于disabledExtensions和deferredExtensions作为字符串数组呈现。

page_config.json文件的示例如下:

{
    "disabledExtensions": [
        "@jupyterlab/toc"
    ],
    "terminalsAvailable": false
}

overrides.json

您可以通过在overrides.json文件中定义新的默认值来重写扩展设置的默认值。例如，如果您希望将默认模式重写为暗黑模式，那么包含以下行的overrides.json文件应添加到应用程序设置目录中 (默认是share/jupyter/lab/settings文件夹)。

{
  "@jupyterlab/apputils-extension:themes": {
    "theme": "JupyterLab Dark"
  }
}

build_config.json

build_config.json文件用于跟踪使用jupyter labextension install <directory>安装的本地目录，以及已显式卸载的核心扩展。build_config.json文件的示例如下:

{
    "uninstalled_core_extensions": [
        "@jupyterlab/markdownwidget-extension"
    ],
    "local_extensions": {
        "@jupyterlab/python-tests": "/path/to/my/extension"
    }
}

暂存和静态

static目录包含将由JupyterLab应用程序加载的资产。staging目录用于创建构建，然后填充static目录。

运行jupyter lab将尝试运行应用程序目录中的static资产 (如果存在)。您可以运行jupyter lab --core-mode从安装目录 (即没有任何扩展的应用程序) 加载核心 JupyterLab应用程序。

如果启动JupyterLab且静态资产不存在，它将在控制台和浏览器中显示错误。

主题

themes目录包含JupyterLab主题扩展的资产 (如CSS和图标)。

JupyterLab用户设置目录

用户设置目录包含Jupyter扩展的用户级设置。

默认情况下，位置为$HOME/.jupyter/lab/user-settings/，其中$HOME是用户的主目录。此文件夹不在JupyterLab应用程序目录中，因为这些设置通常在Python环境中共享。可以使用JUPYTERLAB_SETTINGS_DIR环境变量修改位置。

JSON5文件在此文件夹中自动创建，记录用户在JupyterLab高级设置编辑器中进行的设置更改。文件名遵循 <extension_name>/<plugin_name>.jupyterlab-settings的模式。这些值重写扩展给出的默认值，以及应用程序设置目录中overrides.json文件的默认重写。

=JupyterLab工作区目录

JupyterLab会话始终位于工作区中。工作区包含JupyterLab的状态: 当前打开的文件、应用程序区域和选项卡的布局等。刷新页面后，将恢复工作区。

默认情况下，位置为$HOME/.jupyter/lab/workspaces/，其中 $HOME是用户的主目录。此文件夹不在JupyterLab应用程序目录中，因为这些文件通常在Python环境共享。可以使用JUPYTERLAB_WORKSPACES_DIR环境变量修改位置。

可以使用workspace命令行工具导入和导出这些文件以创建默认“profiles”。

jupyterlab
jupyter
notebook
客服