开发指南

开发指南¶

Dask 是一个由社区维护的项目。我们欢迎通过 bug 报告、文档、代码、设计提案等多种形式进行贡献。本页面提供了关于如何最佳贡献的资源。

注意

Dask 努力成为一个欢迎具有不同背景的个人的社区。有关我们的价值观的更多信息，请参阅我们的行为准则和多样性声明

在哪里寻求帮助¶

Dask 的讨论集中在以下地方

Dask Discourse 论坛：用于提问用法和进行一般讨论
Stack Overflow #dask 标签：用于提问用法
GitHub 问题追踪器：用于讨论新功能或已知的 bug
Dask 社区 Slack：用于实时讨论

对于使用问题和 bug 报告，我们更倾向于使用 Discourse、Stack Overflow 和 GitHub 议题，而不是 Slack 聊天。Discourse、GitHub 和 Stack Overflow 更容易被将来的用户搜索到，因此那里的讨论对更多人有用，而不仅仅是直接参与者。

独立的代码仓库¶

Dask 在 GitHub dask 组织 (https://github.com/dask) 下的几个 Git 仓库中维护代码和文档。这包括主仓库和几个用于不同组件的其他仓库。以下是一个不完全列表：

https://github.com/dask/dask：主代码仓库，包含并行算法、单机调度器和大部分文档
https://github.com/dask/distributed：分布式内存调度器
https://github.com/dask/dask-ml：机器学习算法
https://github.com/dask/s3fs：S3 文件系统接口
https://github.com/dask/gcsfs：GCS 文件系统接口
https://github.com/dask/hdfs3：Hadoop 文件系统接口
...

Git 和 GitHub 起初可能具有挑战性。幸运的是，互联网上存在许多好的材料。我们在此不再赘述，建议您参考 pandas 关于此主题的文档和链接：https://pandas.ac.cn/docs/dev/development/contributing.html

议题¶

社区在GitHub 问题追踪器中讨论和追踪已知的 bug 和潜在的功能。如果您有新的想法或发现了 bug，应该在此提出以发起公开讨论。

如果您正在寻找一个入门级的议题来开始开发，请查看“good first issue” 标签，其中包含了适合初级开发者的议题。通常，假定您熟悉 Python、NumPy、pandas 以及一些并行计算知识。

开发环境¶

下载代码¶

fork 主仓库 Dask repository 并克隆 fork 的版本

git clone https://github.com/<your-github-username>/dask.git
cd dask

您还应该拉取最新的 git 标签（这确保 pip 的依赖解析器能够成功安装 Dask）

git remote add upstream https://github.com/dask/dask.git
git pull upstream main --tags

之后可以通过在 GitHub 上提交 pull request 来对 Dask 进行贡献。

安装¶

在您克隆的 Dask 仓库的顶层目录下，您可以使用 pip 或 conda 安装 Dask 的本地版本以及所有必要的依赖项

pip:

python -m pip install -e ".[complete,test]"

conda:

conda env create -n dask-dev -f continuous_integration/environment-3.12.yaml
conda activate dask-dev
python -m pip install --no-deps -e .

运行测试¶

Dask 使用 py.test 进行测试。您可以在主 dask 目录下运行测试，如下所示

py.test dask --verbose --doctest-modules

代码贡献¶

Dask 遵循类似于大多数 PyData 项目的开发标准。这些标准包括语言支持、测试、文档和代码风格。

Python 版本¶

Dask 支持 Python 3.9 到 3.12 版本。名称更改由 dask/compatibility.py 文件处理。

测试¶

Dask 使用了大量的单元测试来确保代码的正确性，无论是现在还是将来。所有代码贡献都需要进行测试覆盖。

测试使用 py.test 风格编写，采用普通函数

def test_fibonacci():
    assert fib(0) == 0
    assert fib(1) == 0
    assert fib(10) == 55
    assert fib(8) == fib(7) + fib(6)

    for x in [-3, 'cat', 1.5]:
        with pytest.raises(ValueError):
            fib(x)

这些测试应在覆盖所有分支和失败情况以及快速运行之间取得良好平衡（慢速测试套件运行频率较低）。

您可以通过在本地 dask 目录中运行 py.test 来本地运行测试

py.test dask

您还可以测试特定的模块或单个测试以获得更快的响应

py.test dask/dataframe

py.test dask/dataframe/tests/test_dataframe.py::test_rename_index

如果您希望测试运行得更快，可以使用 pytest-xdist 并行运行它们

py.test dask -n auto

每次推送到 GitHub 上的每个 pull request 时，测试都会在 GitHub Actions 上自动运行。

测试组织在各个模块的子目录中

dask/array/tests/test_*.py
dask/bag/tests/test_*.py
dask/bytes/tests/test_*.py
dask/dataframe/tests/test_*.py
dask/diagnostics/tests/test_*.py

对于 Dask 集合，例如 Dask Array 和 Dask DataFrame，通常使用 assert_eq 函数直接针对 NumPy 或 pandas 库测试其行为

import numpy as np
import dask.array as da
from dask.array.utils import assert_eq

def test_aggregations():
    rng = np.random.default_rng()
    nx = rng.random(100)
    dx = da.from_array(nx, chunks=(10,))

    assert_eq(nx.sum(), dx.sum())
    assert_eq(nx.min(), dx.min())
    assert_eq(nx.max(), dx.max())
    ...

这项技术有助于确保与上游库的兼容性，并且通常比直接测试正确性更简单。此外，通过将 Dask 集合直接传递给 assert_eq 函数而不是手动调用 compute，测试套件能够对惰性集合本身运行许多检查。

Docstrings¶

面向用户的函数应大致遵循 numpydoc 标准，包括 Parameters（参数）、Examples（示例）等部分以及一般性说明。

默认情况下，示例会进行 doc-test。文档中的可复现示例对于测试和（更重要的是）向用户传达常用用法非常有价值。在这种情况下，文档优于测试，清晰的示例应优先于将 docstring 用作测试空间。要在示例中跳过某个测试，请在该行后直接添加注释 # doctest: +SKIP。

def fib(i):
    """ A single line with a brief explanation

    A more thorough description of the function, consisting of multiple
    lines or paragraphs.

    Parameters
    ----------
    i: int
         A short description of the argument if not immediately clear

    Examples
    --------
    >>> fib(4)
    3
    >>> fib(5)
    5
    >>> fib(6)
    8
    >>> fib(-1)  # Robust to bad inputs
    ValueError(...)
    """

Docstrings 在 GitHub Actions 上使用 Python 3.12 进行测试。您可以使用 pytest 测试 docstrings，如下所示

py.test dask --doctest-modules

Docstring 测试需要安装 graphviz。可以通过以下方式安装

conda install -y graphviz

代码格式化¶

Dask 使用多种代码 linter（flake8、black、isort、pyupgrade、mypy），这些由 CI 强制执行。开发者在提交 PR 之前应该在本地运行它们，通过单个命令 pre-commit run --all-files。这确保了所有开发者的 linter 版本和选项一致。

（可选）您可能希望设置 pre-commit hooks，以便在您进行 git commit 时自动运行。这可以通过运行以下命令完成

pre-commit install

在 Dask 仓库的根目录下运行。现在，每次提交更改时都会运行代码 linter。您可以使用 git commit --no-verify 或其短版本 git commit -n 跳过这些检查。

文档贡献¶

Dask 使用 Sphinx 构建文档，文档托管在 https://readthedocs.org。文档使用 RestructuredText 标记语言（.rst 文件）维护在 dask/docs/source 目录下。文档包含散文和 API 文档。

提交给 Dask 的每个 pull request 都会自动构建文档，并提供实时预览。此外，您也可以按照下面概述的说明在本地构建文档。

如何构建 Dask 文档¶

要在本地构建文档，fork 主仓库 Dask repository 并克隆 fork 的版本

git clone https://github.com/<your-github-username>/dask.git
cd dask/docs

安装 requirements-docs.txt 中的软件包。

（可选）先创建并激活一个 conda 环境

conda create -n daskdocs -c conda-forge python=3.8
conda activate daskdocs

使用 pip 安装依赖项

python -m pip install -r requirements-docs.txt

然后使用 make 构建文档

make html

生成的 HTML 文件位于 build/html 目录中。

现在您可以编辑 rst 文件并再次运行 make html 来更新受影响的页面。

Dask CI 基础设施¶

Github Actions¶

Dask 使用 Github Actions 对每个 PR 进行持续集成 (CI) 测试。这些 CI 构建将在各种 Python 版本、操作系统和软件包依赖版本上运行测试套件。此外，如果提交消息包含短语 test-upstream，则会触发额外的 CI 构建，该构建使用多个依赖项的开发版本，包括：NumPy、pandas、fsspec 等。

Github Actions 的 CI 工作流程定义在 .github/workflows 中，附加的脚本和元数据位于 continuous_integration 中

命令行界面

更新日志