jupyter-project

一个用于处理（独特）项目和文件模板的JupyterLab扩展。它增加了从cookiecutter模板生成项目以及从Jinja2模板生成文件的能力。这些模板可以直接通过指定JSON模式从前端进行参数化。

此扩展由一个名为jupyter_project的Python包（用于服务器扩展）和一个名为jupyter-project的NPM包（用于前端扩展）组成。

• 需求
• 安装
• 配置
  • 文件模板
  • 项目模板
    • Conda集成
    • Git集成
  • 完整配置
• 故障排除
• 贡献
• 卸载
• 替代方案

与所有第三方扩展一起测试：
不使用它们进行测试：

需求

• Python需求

# setup.py#L63-L66

"cookiecutter",
"jinja2~=2.9",
"jsonschema",
"jupyterlab~=1.2"

• 可选Python需求

# setup.py#L69-L72

"all": [
    "jupyter_conda~=3.3", 
    "jupyterlab-git>=0.10,<0.20"
],

• 可选JupyterLab扩展

  • @jupyterlab/git
  • jupyterlab_conda

安装

注意：您需要NodeJS来安装此扩展。

使用pip

pip install jupyter_project
jupyter lab build

或使用conda

conda install -c conda-forge jupyter_project
jupyter lab build

配置扩展

默认情况下，此扩展不会向JupyterLab添加任何内容，因为模板必须作为服务器扩展配置密钥 JupyterProject 的一部分进行配置（有关更多信息，请参阅Jupyter服务器配置）。

接下来将描述Binder的配置示例——这是文件 binder/jupyter_notebook_config.json。

此扩展的配置部分必须命名为 JupyterProject

// ./binder/jupyter_notebook_config.json#L7-L7

"JupyterProject": {

它接受两个可选密钥： file_templates 和 project_template。第一个定义了包含模板文件的列表位置。第二个描述项目模板。它们都可以独立存在（即仅文件模板或仅项目模板）。

文件模板

文件模板可以位于由其完整路径提供的 location，或在Python module 内部的 location。在Binder示例中，模板位于 jupyter_project Python模块的 examples 文件夹中

// ./binder/jupyter_notebook_config.json#L8-L12

"file_templates": [
  {
    "name": "data-sciences",
    "module": "jupyter_project",
    "location": "examples",

这里出现的最后一个参数是 name。它唯一地描述了文件模板的来源。

接下来是这个来源中可用的模板文件列表。有三个模板文件示例。最短的配置是

// ./binder/jupyter_notebook_config.json#L14-L16

{
  "template": "demo.ipynb"
},

这将通过提供文件的副本来创建模板。

但通常，模板会包含参数。此扩展通过JSON schema规范处理参数。该模式将用于向用户显示一个表单，该表单将与模式进行验证。然后，将表单值传递给Jinja2以渲染模板。

此外，如果项目处于活动状态，其属性（如名称或目录名）将在Jinja模板中以 jproject.<property> 的形式可用（例如，jproject.name 表示项目名称）。

// ./binder/jupyter_notebook_config.json#L74-L92

{
  "default_name": "{{ modelName }}",
  "destination": "src/models",
  "schema": {
    "type": "object",
    "properties": {
      "authorName": {
        "type": "string"
      },
      "modelName": {
        "type": "string",
        "pattern": "^[a-zA-Z_]\\w*$"
      }
    },
    "required": ["modelName"]
  },
  "template_name": "Train Model",
  "template": "train_model.py"
}

在设置中，您可以看到三个尚未解释的额外条目

• template_name：在前端显示的模板的更友好名称。

• default_name：从模板生成的文件的默认名称（字符串可能包含在 schema 中定义的Jinja2变量）。

• destination：如果您使用的是项目模板，则生成的文件将放置在活动项目文件夹内的目标文件夹中。如果没有活动项目，文件将写入当前文件夹。它可以包含项目模板变量

  • {{jproject.name}}：项目名称
  • {{jproject.dirname}}：项目目录名称

最新的文件模板示例是所有可能性的完整示例（包括可以在模式中使用的变量类型）

// ./binder/jupyter_notebook_config.json#L17-L73

{
  "destination": "notebooks",
  "icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 16 16\"> <rect class=\"jp-icon3\" fill=\"#ffffff\" width=\"16\" height=\"16\" rx=\"2\" style=\"fill-opacity:1\" /> <path class=\"jp-icon-accent0\" fill=\"#faff00\" d=\"m 12.098275,4.7065364 -4.9999997,-0.62651 v 8.9554396 l 4.9999997,-0.32893 v -1.1 l -3.4999997,0.19305 V 8.9065364 h 1.9999997 v -1.1 l -1.9999997,-0.1 V 5.3539365 l 3.4999997,0.3526 z\" style=\"fill-opacity:1;stroke:none\" /> </svg> ",
  "template_name": "Example",
  "template": "example.ipynb",
  "schema": {
    "type": "object",
    "properties": {
      "exampleBoolean": {
        "default": false,
        "title": "A choice",
        "type": "boolean"
      },
      "exampleList": {
        "default": [1, 2, 3],
        "title": "A list of number",
        "type": "array",
        "items": {
          "default": 0,
          "type": "number"
        }
      },
      "exampleNumber": {
        "default": 42,
        "title": "A number",
        "type": "number",
        "minimum": 0,
        "maximum": 100
      },
      "exampleObject": {
        "default": {
          "number": 1,
          "street_name": "Dog",
          "street_type": "Street"
        },
        "title": "A object",
        "type": "object",
        "properties": {
          "number": { "type": "integer" },
          "street_name": { "type": "string" },
          "street_type": {
            "type": "string",
            "enum": ["Street", "Avenue", "Boulevard"]
          }
        },
        "required": ["number"]
      },
      "exampleString": {
        "default": "I_m_Beautiful",
        "title": "A string",
        "type": "string",
        "pattern": "^[a-zA-Z_]\\w*$"
      }
    },
    "required": ["exampleString"]
  }
},

细心的读者可能会注意到最后一个可用的设置：icon。它是一个字符串化的svg，将在前端为模板设置自定义图标。

如果您需要从不同的来源设置模板，您可以在 file_templates 列表中添加类似于 data-sciences 的条目。

项目模板

第二个主要配置部分是 project_template。模板必须指定一个指向有效 cookiecutter 模板源的 template 值。

// ./binder/jupyter_notebook_config.json#L96-L97

"project_template": {
  "template": "https://github.com/drivendata/cookiecutter-data-science",

您希望用户能够更改的cookiecutter模板参数必须以 JSON schema 的形式指定。

// ./binder/jupyter_notebook_config.json#L98-L125

"schema": {
  "type": "object",
  "properties": {
    "project_name": {
      "type": "string",
      "default": "Project Name"
    },
    "repo_name": {
      "title": "Folder name",
      "type": "string",
      "pattern": "^[a-zA-Z_]\\w*$",
      "default": "project_name"
    },
    "author_name": {
      "type": "string",
      "description": "Your name (or your organization/company/team)"
    },
    "description": {
      "type": "string",
      "description": "A short description of the project."
    },
    "open_source_license": {
      "type": "string",
      "enum": ["MIT", "BSD-3-Clause", "No license file"]
    }
  },
  "required": ["project_name", "repo_name"]
},

然后您需要将 folder_name 设置为cookiecutter模板生成的文件夹名称。这是一个接受在 schema 中定义的Jinja2变量的字符串。

示例中的最新选项是 default_path。这是可选的，如果设置，则应提供 JupyterLab 生成项目后打开的默认路径（文件夹或文件）。它可以包含项目模板变量。

• {{jproject.name}}：项目名称
• {{jproject.dirname}}：项目目录名称

// ./binder/jupyter_notebook_config.json#L126-L127

"folder_name": "{{ repo_name }}",
"default_path": "README.md",

Conda 环境集成

如果安装了可选扩展 jupyter_conda，并且 project_template 配置中指定了 conda_pkgs，那么 Conda 环境将遵循项目的生命周期；即项目创建时创建环境，打开项目时更新环境和更改其包，以及项目删除时删除环境。

conda_pkgs 设置应设置为与项目创建时要创建的 Conda 环境的默认环境类型匹配的字符串（有关更多信息，请参阅 jupyter_conda labextension）。您也可以设置一个用空格分隔的包列表。

binder 示例定义了

// ./binder/jupyter_notebook_config.json#L128-L128

"conda_pkgs": "awscli click coverage flake8 ipykernel python-dotenv>=0.5.1 sphinx"

如果项目 cookiecutter 模板中缺少 environment.yml，则默认的 conda 包设置是回退选项。

使用 conda 集成时，项目模板有两个可配置选项

• editable_install：如果为 True，则项目文件夹将使用 conda 环境中的 pip 以可编辑模式安装（默认：True）
• filter_kernel：如果为 True，则内核管理器的白名单将动态设置为项目环境内核之一（即项目打开时仅该内核可用）（默认：True）。

Git集成

如果安装了可选扩展 jupyterlab-git，则可以期待以下功能和/或行为

• 创建项目时，它将被初始化为 git 仓库，并执行带有所有生成文件的第一次提交。
• 当 git HEAD 发生变化（分支更改、拉取操作等）时，如果 environment.yml 文件已更改，则将更新 conda 环境。

完整配置

以下是所有服务器扩展设置的描述

{
  "JupyterProject": {
    "file_templates": {
      "description": "List of file template loaders",
      "type": "array",
      "items": {
        "description": ,
        "type": "object",
        "properties": {
          "location": {
            "description": "Templates path",
            "type": "string"
          },
          "module": {
            "description": "Python package containing the templates 'location' [optional]",
            "type": "string"
          },
          "name": {
            "description": "Templates group name",
            "type": "string"
          },
          "files": {
            "description": "List of template files",
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "properties": {
                "default_name": {
                  "description": "Default file name (without extension; support Jinja2 templating using the schema parameters)",
                  "default": "Untitled",
                  "type": "string"
                },
                "destination": {
                  "description": "Relative destination folder [optional]",
                  "type": "string"
                },
                "icon": {
                  "description": "Template icon to display in the frontend [optional]",
                  "default": null,
                  "type": "string"
                },
                "schema": {
                  "description": "JSON schema list describing the templates parameters [optional]",
                  "type": "object"
                },
                "template": {
                  "description": "Template path",
                  "type": "string"
                },
                "template_name" : {
                  "description": "Template name in the UI [optional]",
                  "type": "string"
                }
              },
              "required": ["template"]
            }
          }
        },
        "required": ["files", "location", "name"]
      }
    },
    "project_template": {
      "description": "The project template options",
      "type": "object",
      "properties": {
        "configuration_filename": {
          "description": "Name of the project configuration JSON file [optional]",
          "default": "jupyter-project.json",
          "type": "string"
        },
        "configuration_schema": {
          "description": "JSON schema describing the project configuration file [optional]",
          "default": {
            "type": "object",
            "properties": {"name": {"type": "string"}},
            "required": ["name"],
          },
          "type": "object"
        },
        "conda_pkgs": {
          "default": null,
          "description": "Type of conda environment or space separated list of conda packages (requires `jupyter_conda`) [optional]",
          "type": "string"
        },
        "default_path": {
          "description": "Default file or folder to open; relative to the project root [optional]",
          "type": "string"
        },
        "editable_install": {
          "description": "Should the project be installed in pip editable mode in the conda environment?",
          "type": "boolean",
          "default": true
        },
        "filter_kernel": {
          "description": "Should the kernel be filtered to match only the conda environment?",
          "type": "boolean",
          "default": true
        },
        "folder_name": {
          "description": "Project name (support Jinja2 templating using the schema parameters) [optional]",
          "default": "{{ name|lower|replace(' ', '_') }}",
          "type": "string"
        },
        "module": {
          "description": "Python package containing the template [optional]",
          "type": "string"
        },
        "schema": {
          "description": "JSON schema describing the template parameters [optional]",
          "default": {
            "type": "object",
            "properties": {"name": {"type": "string", "pattern": "^[a-zA-Z_]\\w*$"}},
            "required": ["name"],
          },
          "type": "object"
        },
        "template": {
          "description": "Cookiecutter template source",
          "default": null,
          "type": "string"
        }
      },
      "required": ["template"]
    }
  }
}

故障排除

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

jupyter serverextension list

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

jupyter labextension list

如果已安装，请尝试

jupyter lab clean
jupyter lab build

贡献

前端扩展基于 uniforms，并具有其 material-ui 风格，以处理和显示来自 JSON 模式的自动表单。

安装

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

# Clone the repo to your local environment
# Move to jupyter-project directory

# Install server extension
pip install -e .[test]
# Register server extension
jupyter serverextension enable --py jupyter_project

# Install dependencies
jlpm
# Build Typescript source
jlpm build
# Link your development version of the extension with JupyterLab
jupyter labextension link .
# Rebuild Typescript source after making changes
jlpm build
# Rebuild JupyterLab after making any changes
jupyter lab build

您可以监视源目录，并以监视模式运行 JupyterLab 以监视扩展源的更改，并自动重建扩展和应用程序。

# Watch the source directory in another terminal tab
jlpm watch
# Run jupyterlab in watch mode in one terminal tab
jupyter lab --watch

要使用工作示例运行，请从 binder 文件夹中执行 jupyter lab 以使用本地的 jupyter_notebook_config.json 作为配置。

卸载

使用pip

pip uninstall jupyter-project
jupyter labextension uninstall jupyter-project

或使用 pip

conda remove jupyter-project
jupyter labextension uninstall jupyter-project

替代方案

不喜欢这里的内容？尝试这些其他方法

• jupyterlab-starters
• jupyterlab_templates