xcube_jl_ext

xcube JupyterLab集成

此扩展由一个名为 xcube_jl_ext 的Python包（用于JupyterLab服务器扩展）和一个名为 xcube-jl-ext 的NPM包（用于JupyterLab前端扩展）组成。

此扩展为JupyterLab添加以下功能

1. 允许在JupyterLab中以小部件形式运行可配置的xcube Viewer。
2. 允许在Jupyter笔记本中使用xcube服务器和Viewer，即使JupyterLab是在远程运行，即由JupyterHub启动。

---

注意

此扩展仍处于实验阶段，尚未打包或部署。有关开发安装，请参阅下面的 开发 部分。

---

需求

• JupyterLab >= 3.0
• xcube >= 0.13

安装

要安装扩展，请执行

pip install xcube_jl_ext

卸载

要删除扩展，请执行

pip uninstall xcube_jl_ext

故障排除

如果您看到前端扩展但无法工作，请检查服务器扩展是否已启用

jupyter server extension list

如果已安装并启用了服务器扩展，但您看不到前端扩展，请检查前端扩展是否已安装

jupyter labextension list

开发

设置环境

从源代码构建 xcube Viewer 资源。注意您需要在您的系统上安装 yarn。

cd ${projects}
git clone https://github.com/dcs4cop/xcube-viewer.git
cd xcube-viewer
yarn install
yarn build

现在将环境变量 XCUBE_VIEWER_PATH 设置为指向 xcube Viewer 构建目录

export XCUBE_VIEWER_PATH=${projects}/xcube-viewer/build

请确保在专用的 xcube Python 环境中有一个 xcube 的源安装。

cd ${projects}
git clone https://github.com/dcs4cop/xcube.git
cd xcube
mamba env create

激活 xcube 环境并以可编辑（开发）模式安装 xcube

conda activate xcube
pip install -ve .

使用构建和运行 JupyterLab 扩展所需的软件包更新环境。

注意，我们开发环境中 jupyterlab 的版本应与目标系统的版本匹配。我们还安装了 jupyter-server-proxy。

mamba install -c conda-forge -c nodefaults jupyterlab=3.4.0 jupyter-server-proxy

同时安装一些打包和构建工具

mamba install -c conda-forge -c nodefaults nodejs jupyter-packaging
pip install build

请参阅 JupyterLab 扩展教程 了解如何使用这些工具。

从源代码安装扩展

确保 xcube 环境已激活

conda activate xcube

在 xcube 源文件夹旁边克隆 xcube JupyterLab 扩展仓库

cd ${projects}
git clone https://github.com/dcs4cop/xcube-jl-ext.git
cd xcube-jl-ext

安装初始项目依赖项并将扩展安装到 JupyterLab 环境中。将扩展的前端部分复制到 JupyterLab 中。我们每次对更改进行更改时都可以再次运行此 pip 安装命令，以将更改复制到 JupyterLab。

pip install -ve .

从 JupyterLab 到我们的源目录创建符号链接。这意味着我们的更改将自动在 JupyterLab 中可用

jupyter labextension develop --overwrite .

如果成功，我们可以运行 JupyterLab 并检查扩展是否按预期工作

jupyter lab

更改后构建

运行以下命令以重新构建扩展。这将在更改 package.json 或更改前端 TypeScript 文件和其他资源后需要。

jlpm run build

如果您希望避免每次更改后都进行构建，您可以在另一个终端中运行以下命令

jlpm run watch

从您的扩展目录运行。这将自动编译 TypeScript 文件，并在它们更改和保存时编译。

贡献

开发安装

注意：您将需要 NodeJS 来构建扩展包。

jlpm 命令是 JupyterLab 随附的 yarn 的固定版本，它是与 JupyterLab 一起安装的。您可以使用 yarn 或 npm 代替下面的 jlpm。

# Clone the repo to your local environment
# Change directory to the xcube_jl_ext directory
# Install package in development mode
pip install -e ".[test]"
# Link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite
# Server extension must be manually installed in develop mode
jupyter server extension enable xcube_jl_ext
# Rebuild extension Typescript source after making changes
jlpm build

您可以在不同的终端中同时监视源目录并运行 JupyterLab，以监视扩展源的更改并自动重新构建扩展。

# Watch the source directory in one terminal, automatically rebuilding when needed
jlpm watch
# Run JupyterLab in another terminal
jupyter lab

监视命令运行时，每次保存的更改都将立即在本地构建并提供给您运行的 JupyterLab。刷新 JupyterLab 以在浏览器中加载更改（您可能需要等待几秒钟才能重新构建扩展）。

默认情况下，jlpm build 命令为该扩展生成源映射，以便更容易使用浏览器开发工具进行调试。要为 JupyterLab 核心扩展也生成源映射，您可以运行以下命令

jupyter lab build --minimize=False

开发卸载

# Server extension must be manually disabled in develop mode
jupyter server extension disable xcube_jl_ext
pip uninstall xcube_jl_ext

在开发模式下，您还需要删除由 jupyter labextension develop 命令创建的符号链接。要找到其位置，您可以运行 jupyter labextension list 以确定 labextensions 文件夹的位置。然后您可以在该文件夹中删除名为 xcube-jl-ext 的符号链接。

测试扩展

服务器测试

此扩展使用 Pytest 进行 Python 代码测试。

安装测试依赖项（仅需要一次）

pip install -e ".[test]"
# Each time you install the Python package, you need to restore the front-end extension link
jupyter labextension develop . --overwrite

要执行它们，请运行

pytest -vv -r ap --cov xcube_jl_ext

前端测试

此扩展使用 Jest 进行 JavaScript 代码测试。

要执行它们，请执行

jlpm
jlpm test

集成测试

本扩展使用Playwright进行集成测试（也称为用户级测试）。更确切地说，使用JupyterLab辅助工具Galata来处理在JupyterLab中测试扩展。

有关更多信息，请参阅ui-tests的README。

打包扩展

参见RELEASE