如何为 cuSpatial 做贡献#

cuSpatial 是 RAPIDS 社区的一部分。为 cuSpatial 做贡献时，开发者应遵循 RAPIDS 贡献指南。RAPIDS 文档的贡献章节详细介绍了如何确定问题、提交并合并 PR 的流程。

目录结构和文件命名#

The cuspatial 包包含几个子包。

  • core 包含 cuspatial 的主要组件

  • io 包含用于读写外部数据对象的 I/O 函数

  • tests 包含 cuspatial 的单元测试

  • utils 包含实用函数

  • _lib 包含包装 C++ libcuspatial 后端的 Cython API。

library_design 进一步讨论了 cuspatial 的高层库设计。

Cython 代码#

_lib 文件夹包含所有 cython 代码。在 libcuspatial 中暴露给 cuspatial 的每个功能都应有两个 Cython 文件

  1. 一个 pxd 文件，声明 C++ API，以便在 Cython 中使用，以及

  2. 一个 pyx 文件，包含包装这些 C++ API 的 Cython 函数，以便从 Python 调用它们。

pyx 文件组织在 _lib 根目录下。pxd 文件位于 _lib/cpp 下。pxd 文件应镜像 libcuspatial 中 cpp/include 的文件层级结构。

更多信息请参阅Cython 层设计文档。

代码风格#

cuSpatial 使用多种 linter 来确保整个代码库风格一致，并使用 pre-commit 进行管理。强烈建议开发者在开始任何开发工作之前设置 pre-commit。仓库根目录下的 .pre-commit-config.yaml 文件是 linting 的主要依据。

要安装 pre-commit，请通过 conda/pip 安装

# conda
conda install -c conda-forge pre-commit

# pip
pip install pre-commit

然后在提交代码前运行 pre-commit 钩子

pre-commit run

此外，您还可以设置 pre-commit 钩子在每次执行 git commit 时自动运行。这可以通过在 cuspatial 仓库中运行以下命令来完成

pre-commit install

现在每次提交更改时都会运行代码 linter 和格式化程序。

您可以使用 git commit --no-verify 或其缩写版本 git commit -n 跳过这些检查。

Linter 详情#

具体来说，cuSpatial 使用以下工具

  • flake8 检查通用的代码格式规范符合性。

  • black 是一个自动代码格式化程序。

  • isort 确保导入按一致的方式排序。

Linter 配置数据存储在多个文件中。cuSpatial 通常使用 pyproject.toml，并且优先使用根目录文件而非项目特定文件。然而，工具之间以及仓库中不同包之间的差异导致了以下注意事项

  • flake8 尚无支持 pyproject.toml 的计划，因此必须将其配置放在 .flake8 文件中。

  • isort 必须按项目配置，以设置哪个项目是“第一方”项目。

编写测试#

贡献给 cuspatial 的每个新功能都应包含单元测试。单元测试文件应添加到 tests 文件夹中。一般来说，tests 文件夹镜像了 cuspatial 包的文件夹层级结构。在最低层级，每个模块会展开为一个文件夹，其中包含针对该模块中特定功能的测试文件。

cuSpatial 使用 pytest 作为单元测试框架。conftest.py 包含可以在不同测试函数之间共享的有用夹具（fixtures）。重用这些夹具可以减少测试代码中的冗余。

cuspatial 计算 API 应努力与其宿主 (CPU) 等效实现结果一致性。对于 GeoSeries 和 GeoDataFrame 功能，单元测试应将结果与相应的 geopandas 函数进行比较。