开发指南

开发指南¶

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

注意

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

在哪里寻求帮助¶

Dask 的交流在以下地方进行

Dask Discourse 论坛：用于使用问题和一般讨论
Stack Overflow #dask 标签：用于使用问题
GitHub 问题跟踪器：用于讨论新功能或已确认的 Bug
Dask 社区 Slack：用于实时讨论

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

单独的代码仓库¶

Dask 在 GitHub dask 组织下的几个 Git 仓库中维护代码和文档，地址为 https://github.com/dask。这包括主仓库以及其他几个用于不同组件的仓库。下面是一个非穷尽列表：

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，则应在那里提出以开始公开讨论。

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

开发环境¶

下载代码¶

Fork 主Dask 仓库并克隆该 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 部分以及一般的解释性散文。

默认情况下，示例将进行 doctest 测试。文档中的可重现示例对于测试非常有价值，更重要的是，对于向用户传达常见用法也非常重要。在这种情况下，文档优先于测试，清晰的示例应优先于将 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 使用多个代码检查工具（flake8、black、isort、pyupgrade、mypy），这些工具由 CI 强制执行。开发者应在提交 PR 前本地运行它们，通过执行命令 pre-commit run --all-files。这确保了所有开发者的检查工具版本和选项一致。

您可以选择设置 pre-commit 钩子，使其在您进行 git commit 时自动运行。可以通过运行以下命令来完成

pre-commit install

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

贡献文档¶

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

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

如何构建 Dask 文档¶

要在本地构建文档，请 Fork 主 Dask 仓库，然后克隆该 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 中

命令行界面

更新日志