Scientific Python：指南、模板和 sp-repo-review

模板

[![Actions 状态][actions-badge]][actions-link] [![GitHub 讨论][github-discussions-badge]][github-discussions-link] [![ReadTheDocs 实时文档][rtd-badge]][rtd-link]

[![PyPI 版本][pypi-version]][pypi-link] [![PyPI 平台][pypi-platforms]][pypi-link]

基于 Scientific Python 开发者指南的新 Python 项目 [copier][]/[cookiecutter][] 模板。与其他 Python 包模板相比，它有何不同？

• 与 [Scientific-Python 开发指南][]共存：每个决策都有清晰的文档说明，每个工具都有描述，并且所有内容保持同步。
• 可选择十一种不同的后端来构建包。
• 大多数后端支持可选的 VCS 版本控制。
• 模板生成在 GitHub Actions 中使用 nox 进行测试。
• 支持使用 [copier][]、[cookiecutter][] 和 [cruft][] 生成。
• 如果目标是 github.com 网址（默认），则支持 GitHub Actions，否则添加实验性的 GitLab CI 支持。
• 包含几个使用 [pybind11][] 的编译后端，使用 [cibuildwheel][] 为所有平台生成轮子。
• 提供 [sp-repo-review][pypi-link] 来评估现有仓库是否符合指南，并集成了 WebAssembly 版本。所有检查都有交叉链接。
• 遵循 [PyPA][] 最佳实践并定期更新。

请确保你已阅读 [Scientific-Python 开发指南][]，并可能在一两个项目中使用过。这不是一个最小示例或教程。它是一个有用的工具集合，用于使用 cookiecutter 启动新项目，或为现有项目手动复制单个文件（从 {{cookiecutter.project_name}}/）。

在生成过程中，你可以为你的包选择以下后端：

1. [hatch][]：使用 hatchling，一个现代化的构建器，具有良好的文件包含功能，可通过插件扩展，并有良好的错误消息。（推荐用于纯 Python 项目）
2. [flit][]：一个现代化、轻量级的 [PEP 621][] 构建系统，适用于纯 Python 项目。替代 setuptools，无需 MANIFEST.in、setup.py 或 setup.cfg。学习曲线低，易于引导到新的发行版。难以包含正确的文件，动态元数据支持有限。
3. [pdm][]：一个现代化、不太固执己见的纯 Python 项目全面解决方案，支持标准。替代 setuptools、venv/pipenv、pip、wheel 和 twine。支持 [PEP 621][]。
4. [whey][]：一个现代化的 [PEP 621][] 构建器，具有一些 Trove 分类器的自动化选项。开发似乎已停滞。（无 VCS 版本控制）
5. [poetry][]：纯 Python 项目的全面解决方案。替代 setuptools、venv/pipenv、pip、wheel 和 twine。学习曲线较高，但功能全面。对库做出一些不好的默认假设。唯一一个使用非标准 pyproject.toml 配置的工具。
6. [setuptools621][setuptools]：经典构建系统，但使用新的标准化配置。
7. [setuptools][]：经典构建系统。功能最强大，但学习曲线高，需要大量配置。
8. [pybind11][]：这是 setuptools，但包含用 [pybind11][] 编写的 C++ 扩展，并使用 [cibuildwheel][] 生成轮子。
9. [scikit-build][]：一个使用 scikit-build（CMake）的项目，也使用 pybind11，使用 scikit-build-core。（推荐用于 C++ 项目）
10. [meson-python][]：一个使用 pybind11 的 Meson 项目。（无 VCS 版本控制）
11. [maturin][]：用于 Rust 二进制扩展的 [PEP 621][] 构建器。（无 VCS 版本控制）（推荐用于 Rust 项目）

目前，对于纯 Python 项目，最佳选择可能是 hatch，对于二进制项目，最佳选择可能是 scikit-build（如 scikit-build-core + pybind11 选项）。

使用方法（现代 copier 版本）

安装 copier 和 copier-templates-extensions。使用 [pipx][]，命令如下：

pipx install copier
pipx inject copier copier-templates-extensions

现在，运行 copier 生成你的项目：

copier copy gh:scientific-python/cookie <pkg> --trust

（<pkg> 是放置新项目的路径。如果 copier 版本较旧，请使用 --UNSAFE 而不是 --trust）

你将获得更好的 CLI 体验，包括答案验证。你还将获得一个 .copier-answers.yml 文件，允许你在将来进行更新。

注意：添加 --vcs-ref=HEAD 以获取最新版本，而不是最后标记的版本；HEAD 始终通过测试（这也是 cookiecutter 使用的版本）。

使用方法（经典 cookiecutter 版本）

安装 cookiecutter，如果你使用 brew，最好使用 brew install cookiecutter，否则使用 pipx install cookiecutter（或在下面的命令前加上 pipx run，并跳过安装）。然后运行：

cookiecutter gh:scientific-python/cookie

如果你使用的是 cookiecutter 2.2.3+，你将像 copier 一样获得选项的详细描述！

使用方法（经典 cruft 版本）

你也可以使用 [cruft][]，它增加了更新 cookiecutter 项目的能力。使用 pipx install cruft 安装（或在下面的命令前加上 pipx run，并跳过安装）。然后运行：

cruft create gh:scientific-python/cookie

生成后

检查关键设置文件、pyproject.toml，可能还有 setup.cfg 和 setup.py（pybind11 示例）。更新 README.md。同时更新和添加 docs/ 中的文档。

有一些示例依赖项和最低 Python 版本 3.8，你可以根据实际需要/想要的进行更改。还有一个基本的向后兼容结构，包含一个小型类型示例。

包含的组件：

• GitHub Actions 运行生成本身的测试
  • 使用 nox，因此可以在本地检查 cookie 开发
• GitHub actions 部署
  • C++ 后端包括用于轮子构建的 cibuildwheel
  • 使用 PyPI 受信任的发布者部署
• Dependabot 定期通过有用的拉取请求保持 actions 更新
• 格式化由 pre-commit 处理
  • 新项目没有理由不严格；移除你不想要的内容。
  • 包括 MyPy - 静态类型检查
  • 包括 Ruff - 标准格式化、代码检查和自动修复
    • 替代 Flake8、isort、pyupgrade、yesqa、pycln 和数十个插件
  • 包括拼写检查
• 可以使用 pylint nox 目标运行 pylint，它集成了 GHA 注释
• 一个 ReadTheDocs 就绪的 Sphinx 文档文件夹和 [docs] 额外依赖
• 一个测试文件夹和 pytest [test] 额外依赖
• 包含一个 noxfile，其中有一些常见目标

仅限 Setuptools：

• Setuptools 由 setup.cfg 控制，并有一个名义上的 setup.py。
  • 使用声明性语法避免了不必要的样板代码，这些样板代码通常是错误的（比如在打开 README 时处理编码不正确）。
  • 更容易最终适应 PEP 621。
  • 任何实际逻辑都可以放在 setup.py 中，与简单的元数据明确分开。
• 版本控制由 setuptools_scm 处理
  • 你可以轻松切换到手动版本控制，但这避免了在 git 标签和源代码中重复版本，并为每个提交唯一地版本化，避免了一些缓存问题。
• 使用 check-manifest 检查 MANIFEST.in
• 使用 setup-cfg-fmt 检查 setup.cfg

对于开发者：

你可以使用 [nox][] 在本地进行测试：

# 查看所有命令
nox -l

# 运行特定检查
nox -s "lint(setuptools)"

# 在项目 noxfile 上运行 noxfile 命令
nox -s "nox(whey)" -- docs

如果你本地没有 nox，可以使用 [pipx][]，例如 pipx run nox。

其他类似项目

[Hypermodern-Python][hypermodern]是另一个值得关注的项目，它与本项目有许多相似之处，比如每个功能都有详细的文档说明，并使用了许多相同的工具。它的功能集略有不同，更加注重GitHub Actions - 如果你不想使用GHA，我们的大部分指南都可以很容易地适应其他CI系统。它强制使用Poetry（而不是提供后端选择），并且不支持编译项目。目前它将所有开发依赖项都放入一个共享环境中，导致解析时间长且容易发生冲突。它也没有按照预期方式使用pre-commit。此外，它还包含相当多的自定义代码。

历史

本指南、cookiecutter和repo-review的大部分内容最初是Scikit-HEP的一部分。这些项目在2023年Scientific-Python开发者峰会期间与[NSLS-II][]指南合并、泛化和整合。

---

sp-repo-review

sp-repo-review为repo-review提供基于[Scientific-Python开发指南][]（位于scientific-python/cookie）的检查。

此工具可以检查仓库的风格。使用方法如下：

pipx run 'sp-repo-review[cli]' <仓库路径>

这将生成一个结果列表 - 绿色对勾表示遵循了该规则，红色叉号表示未遵循。黄色警告标志表示由于之前的必要检查失败，该检查被跳过。有些检查可能会失败，这没关系 - 目的是让你注意到所有可能的问题，而不是强制遵守任意的检查。将来可能会有一种方法来标记忽略的检查。

例如，GH101期望所有action文件都有一个合适的name:字段。如果你对CI中看到的基于文件的名称感到满意，你可以随意忽略这个检查（目前只能在视觉上忽略，以后可能会添加指定忽略检查的方法）。

所有检查都在[Scientific-Python开发指南][]中有所提及。你应该先阅读该指南 - 如果你不打算遵循它们，某些检查可能无法正常工作。例如，指南规定pytest配置应放在pyproject.toml中。如果你将其放在其他地方，那么所有pytest检查都将被跳过。

这个项目最初是为Scikit-HEP开发的，后来转移到了Scientific Python。

其他使用方式

你也可以使用GitHub Actions：

- uses: scientific-python/cookie@<版本>

或者pre-commit：

- repo: https://github.com/scientific-python/cookie
  rev: <版本>
  hooks:
    - id: sp-repo-review

如果你使用additional_dependencies来添加更多插件，比如validate-pyproject，你还应该包含"repo-review[cli]"以确保包含CLI要求。

检查列表

通用

• PY001：有pyproject.toml文件
• PY002：有README.(md|rst)文件
• PY003：有LICENSE*文件
• PY004：有docs文件夹
• PY005：有tests文件夹
• PY006：有pre-commit配置
• PY007：支持简单的任务运行器（nox或tox）

PyProject

• PP002：有正确的build-system表
• PP003：不将wheel列为构建依赖
• PP301：pyproject中有pytest
• PP302：设置pytest最低版本至少为6
• PP303：设置测试路径
• PP304：设置pytest的日志级别
• PP305：指定xfail_strict
• PP306：指定严格配置
• PP307：指定严格标记
• PP308：指定有用的pytest摘要
• PP309：指定警告过滤

文档

• RTD100: 使用 ReadTheDocs（pyproject 配置）
• RTD101: 必须将 RTD 版本号设置为 2
• RTD102: 必须设置 RTD 构建镜像
• RTD103: 必须设置 RTD Python 版本

GitHub Actions

• GH100: 有 GitHub Actions 配置
• GH101: 有合适的名称
• GH102: 对重复的 PR 自动取消
• GH103: 至少有一个工作流具有手动触发选项
• GH104: 为 upload-artifact 使用唯一名称
• GH200: 由 Dependabot 维护
• GH210: 使用 Dependabot 维护 GitHub action 版本
• GH211: 不要将核心 actions 固定为主要版本
• GH212: 要求 GHA 更新分组

MyPy

• MY100: 使用 MyPy（pyproject 配置）
• MY101: MyPy 严格模式
• MY102: MyPy show_error_codes 已废弃
• MY103: MyPy 警告不可达代码
• MY104: MyPy 启用 ignore-without-code
• MY105: MyPy 启用 redundant-expr
• MY106: MyPy 启用 truthy-bool

Pre-commit

• PC100: 有 pre-commit-hooks
• PC110: 使用 black 或 ruff-format
• PC111: 使用 blacken-docs
• PC140: 使用类型检查器
• PC160: 使用拼写检查器
• PC170: 使用 PyGrep hooks（仅当存在 rST 时需要）
• PC180: 使用 Markdown 格式化工具
• PC190: 使用 Ruff
• PC191: 如果启用修复功能，Ruff 会显示修复内容
• PC901: 自定义 pre-commit CI 消息

Ruff

• RF001: 有 Ruff 配置
• RF002: 必须设置目标版本
• RF003: 如果使用，必须指定 src 目录
• RF101: 必须选择 Bugbear
• RF102: 必须选择 isort
• RF103: 必须选择 pyupgrade
• RF201: 避免使用已废弃的配置设置
• RF202: 使用（新的）lint 配置部分