Henry Schreiner presenting the Development Guide and cookie project template at the first Scientific Python Developer Summit.

2023 年科学 Python 开发者峰会的一个成果是 科学 Python 开发指南，这是一份关于现代 Python 包开发的综合指南，包含一个支持 10 多个构建后端的 新的项目模板 和一个 基于 WebAssembly 的检查器，该检查器与指南中的检查相关联。该指南涵盖了诸如 现代、编译 和 经典 打包、样式 检查、类型检查、文档、任务运行器、CI、测试 等等！还有一些关于 教程、原则 和一些常见 模式 的章节。

这份指南（以及 cookie 和 repo-review）始于 2020 年的 Scikit-HEP。在峰会期间，它与 NSLS-II 指南合并，该指南为 原则 部分提供了基础。我要感谢并认可 Dan Allan 和 Gregory Lee 在峰会期间不懈地努力，对指南进行重新设计、重写、合并和修复，包括撰写大多数 教程 页面和第一个 模式 页面，以及将 环境 页面重写为教程。

指南#

项目的核心是指南，它包含四个部分

从最初的 Scikit-HEP 开发页面 中，添加了许多内容

  • 关于文档的全新指南页面，以及新的 sp-repo-review 检查，以帮助使用 readthedocs。
  • 编译项目页面！终于！使用 scikit-build-core、meson-python 和 maturin。该页面显示了 cookiecutter 的真实输出，与 cog 保持同步（所有三个组件使用单个仓库的一个巨大好处！）
  • 对 GHA CI 页面 进行了重大更新，包括在开发者峰会上介绍的关于复合操作的部分。
  • 现在包含了 CLI 入口点。
  • 添加了 Python 3.12 支持，删除了 Python 3.7 支持。
  • 整个指南中都添加了新的 sp-repo-review 徽章（稍后详细介绍！）
  • 更新了 Ruff 的移动和对 requires-python 的支持。
  • 对 GitHub Actions 进行了大量添加。

基础设施也进行了更新

  • 使用最新的 Jekyll（版本 4）和最新的 Just the Docs 主题。更丰富的提示框。现在使用了插件。
  • 实时 PR 预览（可能由世界上第一个 readthedocs Jekyll 构建提供！）。在峰会期间与 Zarr 开发人员共同开发。
  • 在索引页面上更好地宣传 cookie 和 sp-repo-review。
  • 自动更新和自动同步 CI 作业。

我们还做了一件我一直想做的事情：指南、cookiecutter 模板和检查都在同一个仓库中！该仓库是 scientific-python/cookie，它是已移动的 scikit-hep/cookie（cookiecutter 的旧 URL 仍然有效！）。

Cookie 是一个支持多个后端（包括编译后端）的新项目模板，与开发指南保持同步。我们建议从开发指南开始，手动设置第一个包，以便您了解每个部分的作用，但是一旦您完成了这些操作，cookie 就可以让您在几秒钟内开始一个新项目。

对 cookie 也进行了大量工作！

  • 通用默认值。如果有人将组织设置为 scikit-hep，我们仍然具有特殊集成；可以为其他组织提供相同的集成。
  • 所有自定义钩子都已删除；现在在整个模板中使用标准 jinja。也使用 cookiecutter 计算变量习惯用法。Windows 仍然完全支持并经过测试。现在添加新选择变得容易多了。
  • 添加了 cruft（cookiecutter 更新器）测试。
  • 现在也双重支持 copier，这是一个 cookiecutter 替代品，具有巨大的 CLI 改进（也支持更新）。可能是第一个同时支持两者的项目。CI（或本地 nox）检查以确保生成相同。与 copier 的更好界面，包括验证、描述性文本、箭头选择等。
  • 即使使用 cookiecutter 也改进了 CLI 体验（例如不再请求当前年份）。
  • 重新设计了文档模板。
  • 支持 cookiecutter 2.2 的漂亮描述（在 cookiecutter 2.2.0 发布大约四个小时后添加）和 cookiecutter 2.2.3 的选择描述。
  • 当不针对 github.com URL 时支持 GitLab CI（由 Giordon Stark 添加）。
  • 支持选择 VCS 或经典版本控制。

Repo-review#

请参阅 repo-review 简介，以获取有关此内容的信息！

随之而来的是可能最大的变化，这是峰会上一些人提出的请求：scientific-python/repo-review（以前是 scikit-hep/repo-review）现在是一个完全通用的框架，用于在 Python 3.10+ 中实现检查。检查已移至 sp-repo-review，现在它是 scientific-python/cookie 的一部分。这里列出的变化太多，因此只列出 0.6、0.7、0.8、0.9 和 0.10 中的关键变化

  • 针对检查作者的详尽、漂亮的 文档（用于帮助指导新的文档指南页面和模板更新！）
  • 支持四种输出格式，rich（改进）、svg、json（新）、html（新）。
  • 支持列出所有检查。
  • GitHub Actions 支持 HTML 步骤摘要、pre-commit 支持。
  • 将拓扑排序推广到夹具，动态夹具。
  • 动态检查选择（通过夹具！基本上所有内容现在都由夹具提供支持）。
  • 所有输出格式（包括终端和 WebApp！）中的 URL 支持。
  • 支持包不在仓库根目录中。
  • 支持从命令行在远程仓库上运行。
  • 支持在 pyproject.toml 或命令行中选择/忽略配置。
  • 对族进行漂亮打印和可控排序。
  • 支持从 Python 运行，包括在自述文件中使用类似 cog 的内容运行。
  • 支持动态族描述（例如输出构建系统和使用的许可证）。
  • 支持将输出限制为仅错误或错误和跳过。
  • 支持一次在多个仓库上运行，输出针对多个仓库定制。还支持传递 pyproject.toml 路径，以便更容易地在混合仓库上运行。
  • 支持使用 validate-pyproject 对 [tool.repo-review] 进行 lint 检查。

完整变更日志 中有更多内容 - 您甚至可以看到 0.6.x 和 0.7.0 之间的 10 个 Beta 版本，其中进行了许多重构工作。如果您有想要编写检查的配置，请随时编写插件！

validate-pyproject 0.14 已添加了作为 repo-review 插件使用的支持，因此您可以使用 repo-review 验证 pyproject.toml 文件！这会对 [project] 和 [build-system] 表格、[tool.setuptools] 以及通过插件的其他工具进行 lint 检查。Scikit-build-core 0.5 可用作 validate-project 插件来对 [tool.scikit-build] 进行 lint 检查。Repo-review 具有用于 [tool.repo-review] 的插件。

sp-repo-review#

最后，sp-repo-review 包含以前的 repo-review 插件和检查

  • 与开发指南完全交叉链接。每个检查都有一个 URL 指向开发指南中的匹配徽章，其中正在讨论检查正在查找的内容！
  • 检查的完整列表（包括 URL），由 cog 生成，位于 自述文件 中。
  • 还附带 GitHub Action 和 pre-commit 检查
  • 发布（与 cookie 和指南同步，因为它们在同一个仓库中）为 CalVer，附带发行说明。
  • 拆分 CI，该 CI 会根据更改的文件选择要运行的内容，并使用尊重跳过的绿色复选标记（基于对 pypa/build 的出色贡献）。
Image of sp-repo-review showing checks

在 cibuildwheel 上运行 sp-repo-review

使用指南#

如果您有自己的指南，我们希望您能将其与 Scientific Python 开发指南进行比较，看看我们是否遗漏了任何内容 - 请告知我们，也许我们可以将其添加进来。然后，您可以链接到集中维护的指南，而不是手动维护完整的自定义指南。请参阅 scikit-hep/developer 以了解示例；许多页面现在都指向此指南。我们还可以为 cookie 提供组织集成，在用户针对您的组织时提供一些自定义设置（针对 scikit-hep 将添加一个徽章）。