rapids-dependency-file-generator

rapids-dependency-file-generator是一个Python CLI工具，它可以从单个YAML文件（通常命名为dependencies.yaml）生成conda environment.yaml文件和requirements.txt文件。

安装后，它会提供rapids-dependency-file-generator CLI命令，负责解析dependencies.yaml配置文件并生成适当的conda environment.yaml和requirements.txt依赖文件。

目录

• 安装
• 用法
• dependencies.yaml格式
  • files键
  • channels键
  • dependencies键
• 依赖列表如何合并
• 额外的CLI说明
• 示例

安装

rapids-dependency-file-generator可在PyPI上获取。要安装，请运行

pip install rapids-dependency-file-generator

用法

当调用rapids-dependency-file-generator时，它将从当前目录读取dependencies.yaml文件并生成子依赖文件。

dependencies.yaml文件具有以下特点

• 它打算提交到存储库的根目录
• 它可以定义矩阵，使输出依赖文件根据任何任意规范（或规范的组合）而变化，包括CUDA版本、机器架构、Python版本等。
• 它包含基于依赖目的（例如构建、运行、测试等）的分支依赖列表。分支依赖列表将根据以下依赖列表如何合并部分的描述进行合并。

dependencies.yaml格式

以下示例部分提供了有关在哪里可以查看示例dependency.yaml文件及其相应输出的说明。

dependencies.yaml文件有三个相关的顶级键：files、channels和dependencies。以下将详细介绍这些键。

files 键

顶层 files 键负责确定以下内容

• 应生成哪些类型的依赖文件（即 conda environment.yaml 文件和/或 requirements.txt 文件）
• 生成的文件应写入的位置（相对于 dependencies.yaml 文件）
• 应根据提供的矩阵生成哪些变体文件
• 顶层 dependencies 键中哪些依赖列表应包含在生成的文件中

以下是一个 files 键可能的样子示例

files:
  all: # used as the prefix for the generated dependency file names for conda or requirements files (has no effect on pyproject.toml files)
    output: [conda, requirements] # which dependency file types to generate. required, can be "conda", "requirements", "pyproject", "none" or a list of non-"none" values
    conda_dir: conda/environments # where to put conda environment.yaml files. optional, defaults to "conda/environments"
    requirements_dir: python/cudf # where to put requirements.txt files. optional, but recommended. defaults to "python"
    pyproject_dir: python/cudf # where to put pyproject.toml files. optional, but recommended. defaults to "python"
    matrix: # (optional) contains an arbitrary set of key/value pairs to determine which dependency files that should be generated. These values are included in the output filename.
      cuda: ["11.5", "11.6"] # which CUDA version variant files to generate.
      arch: [x86_64] # which architecture version variant files to generate. This value should be the result of running the `arch` command on a given machine.
    includes: # a list of keys from the `dependencies` section which should be included in the generated files
      - build
      - test
      - runtime
  build: # multiple `files` children keys can be specified
    output: requirements
    conda_dir: conda/environments
    requirements_dir: python/cudf
    matrix:
      cuda: ["11.5"]
      arch: [x86_64]
      py: ["3.8"]
    includes:
      - build

上述配置的结果是生成以下依赖文件

• conda/environments/all_cuda-115_arch-x86_64.yaml
• conda/environments/all_cuda-116_arch-x86_64.yaml
• python/cudf/requirements_all_cuda-115_arch-x86_64.txt
• python/cudf/requirements_all_cuda-116_arch-x86_64.txt
• python/cudf/requirements_build_cuda-115_arch-x86_64_py-38.txt

all*.yaml 和 requirements_all*.txt 文件将包含顶层 dependency 键中的 build、test 和 runtime 依赖列表的内容。而 requirements_build*.txt 文件将仅包含顶层 dependency 键中的 build 依赖列表的内容。

output 的值也可以是以下示例中的 none

files:
  test:
    output: none
    includes:
      - test

当使用 output: none 时，可以省略 conda_dir、requirements_dir 和 matrix 键。关于 output: none 的使用案例，请参阅下文中的 附加 CLI 说明 部分。

extras

某个文件可能包含一个 extras 条目，该条目可用于提供特定于特定文件类型的输入

以下是一个示例

files:
  build:
    output: pyproject
    includes: # a list of keys from the `dependencies` section which should be included in the generated files
      - build
    extras:
      table: table_name
      key: key_name

目前按文件类型支持的 extras 有

• pyproject.toml
  • table: pyproject.toml 中应写入依赖项的表。可接受的值是 "build-system"、"project" 和 "project.optional-dependencies"。
  • key: 对应于 table 中依赖项列表的键。这仅适用于 "project.optional-dependencies" 表，因为键名对于 "build-system" ("requires") 和 "project" ("dependencies") 是固定的。请注意，这隐式地禁止通过 "project" 表下的内联表包含可选依赖项。

channels 键

顶层 channels 键指定应包含在生成的任何 conda environment.yaml 文件中的通道。

它可能看起来像这样

channels:
  - rapidsai
  - conda-forge

如果没有 channels 键，将使用 RAPIDS 的某些合理默认值（请参阅 constants.py）。

dependencies 键

顶层 dependencies 键是应该指定分叉依赖列表的位置。

dependencies 键下面是一组键值对。对于每一对，键可以任意命名，但应与任何 files 条目的 includes 列表中的某个项目匹配。

每个键值对的值可以有以下子键

• common - 包含所有矩阵变体中相同的依赖项列表
• specific - 包含特定于特定矩阵组合的依赖项列表

下面将详细介绍每个键的值。

common 键

common 键包含具有以下键的对象列表

• output_types - 包含 packages 键中包的输出类型列表（例如，"conda" 用于 environment.yaml 文件或 "requirements" 用于 requirements.txt 文件）
• packages - 包含要包含在生成的输出文件中的包列表

specific 键

specific 键包含具有以下键的对象列表

• output_types - 与上面 common 键的 output_types 相同
• matrices - 定义特定于特定矩阵组合的包的对象列表（以下将描述）

matrices 键

每个在 matrices 键下的列表项都包含一个 matrix 键和一个 packages 键。matrix 键用于定义从 files.[*].matrix 中使用哪些矩阵组合与关联的包。packages 键是包含在生成输出文件中对应矩阵的包列表。这将在 如何合并依赖列表 中详细说明。

以下是一个上述结构的示例

dependencies:
  build: # dependency list name
    common: # dependencies common among all matrix variations
      - output_types: [conda, requirements] # the output types this list item should apply to
        packages:
          - common_build_dep
      - output_types: conda
        packages:
          - cupy
          - pip: # supports `pip` key for conda environment.yaml files
              - some_random_dep
    specific: # dependencies specific to a particular matrix combination
      - output_types: conda # dependencies specific to conda environment.yaml files
        matrices:
          - matrix:
              cuda: "11.5"
            packages:
              - cudatoolkit=11.5
          - matrix:
              cuda: "11.6"
            packages:
              - cudatoolkit=11.6
          - matrix: # an empty matrix entry serves as a fallback if there are no other matrix matches
            packages:
              - cudatoolkit
      - output_types: [conda, requirements]
        matrices:
          - matrix: # dependencies specific to x86_64 and 11.5
              cuda: "11.5"
              arch: x86_64
            packages:
              - a_random_x86_115_specific_dep
          - matrix: # an empty matrix/package entry to prevent error from being thrown for non 11.5 and x86_64 matches
            packages:
      - output_types: requirements # dependencies specific to requirements.txt files
        matrices:
          - matrix:
              cuda: "11.5"
            packages:
              - another_random_dep=11.5.0
          - matrix:
              cuda: "11.6"
            packages:
              - another_random_dep=11.6.0
  test:
    common:
      - output_types: [conda, requirements]
        packages:
          - pytest

依赖列表如何合并

顶级 files 和 dependencies 键的信息用于确定在生成的依赖文件最终输出中应包含哪些依赖项。

考虑以下顶级 files 键配置

files:
  all:
    output: conda
    conda_dir: conda/environments
    requirements_dir: python/cudf
    matrix:
      cuda: ["11.5", "11.6"]
      arch: [x86_64]
    includes:
      - build
      - test

在这个示例中，rapids-dependency-file-generator 将生成两个 conda 环境文件：conda/environments/all_cuda-115_arch-x86_64.yaml 和 conda/environments/all_cuda-116_arch-x86_64.yaml。

由于 output 值为 conda，rapids-dependency-file-generator 将遍历任何 dependencies.build.common 和 dependencies.test.common 列表项，并使用任何具有 output_types 键为 conda 或 [conda, ...] 的条目的 packages。

进一步地，对于 11.5 和 x86_64 矩阵组合，任何输出包含 conda 且其 matrices 列表项与以下定义之一匹配的 build.specific 和 test.specific 列表项也将被合并

specific:
  - output_types: conda
    matrices:
      - matrix:
          cuda: "11.5"
        packages:
          - some_dep1
          - some_dep2
# or
specific:
  - output_types: conda
    matrices:
      - matrix:
          cuda: "11.5"
          arch: "x86_64"
        packages:
          - some_dep1
          - some_dep2
# or
specific:
  - output_types: conda
    matrices:
      - matrix:
          arch: "x86_64"
        packages:
          - some_dep1
          - some_dep2

每个 matrices 列表必须有一个与给定输入矩阵匹配的匹配项（只有 matrices 列表中的第一个匹配项会被使用）。如果没有找到特定矩阵组合的匹配项，则会抛出错误。在不抛出错误的情况下，可以使用空 matrix 和 packages 列表项。

- output_types: conda
  matrices:
    - matrix:
        cuda: "11.5"
        arch: x86_64
        py: "3.8"
      packages:
        - a_very_specific_115_x86_38_dep
    - matrix: # an empty matrix entry serves as a fallback if there are no other matrix matches
      packages:

合并后的依赖列表将被排序和去重。

额外的CLI说明

不提供任何参数调用 rapids-dependency-file-generator 是为 RAPIDS 开发者提供的默认行为。它将生成顶级 files 配置中指定的所有必要的依赖文件。

但是，有一些 CLI 参数可以在生成文件之前增强 files 配置值。

考虑使用 output: none 时的示例

files:
  test:
    output: none
    includes:
      - test

上述配置生成的 test 文件对 CI 很有用，但可能没有必要将这些文件提交到存储库。在这种情况下，可以使用以下 CLI 参数

ENV_NAME="cudf_test"

rapids-dependency-file-generator \
  --file-key "test" \
  --output "conda" \
  --matrix "cuda=11.5;arch=$(arch)" > env.yaml
mamba env create --file env.yaml
mamba activate "$ENV_NAME"

# install cudf packages built in CI and test them in newly created environment...

--file-key 参数传递来自 files 配置的 test 键名。额外的标志用于生成单个依赖文件。当以这种方式使用 CLI 时，它将打印到 stdout 而不是将结果内容写入文件系统。

--file-key、--output 和 --matrix 标志必须一起使用。--matrix 可以是一个空字符串，如果应该生成的文件不依赖于任何特定的矩阵变体。

如果向 --matrix 传递了同一键的多个值，例如 cuda_suffixed=true;cuda_suffixed=false，则只使用最后一个值。

--prepend-channel 参数接受要使用的附加通道，例如 rapids-dependency-file-generator --prepend-channel my_channel --prepend-channel my_other_channel。如果同时提供了 --output 和 --prepend-channel，则输出格式必须是 conda。预置通道对于在 CI 工作流中添加要测试的包的本地通道很有用。

运行 rapids-dependency-file-generator -h 将显示最新的 CLI 参数。

示例

tests/examples 目录包含示例 dependencies.yaml 文件及其相应的输出文件。

要创建新的 example 测试，请执行以下操作

• 在 tests/examples 中创建一个新的目录，并在其中包含 dependencies.yaml 文件
• 确保输出目录（例如 conda_dir，requirements_dir 等）设置为写入 output/actual
• 运行 rapids-dependency-file-generator --config tests/examples/<new_folder_name>/dependencies.yaml 生成初始输出文件
• 手动检查生成的文件是否正确
• 将 output/actual 的内容复制到 output/expected，这样它就会被提交到仓库并用作未来更改的基线
• 将新文件夹名称添加到 test_examples.py