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}}/
)。
在生成过程中,你可以为你的包选择以下后端:
- [hatch][]:使用 hatchling,一个现代化的构建器,具有良好的文件包含功能,可通过插件扩展,并有良好的错误消息。(推荐用于纯 Python 项目)
- [flit][]:一个现代化、轻量级的 [PEP 621][] 构建系统,适用于纯 Python 项目。替代 setuptools,无需 MANIFEST.in、setup.py 或 setup.cfg。学习曲线低,易于引导到新的发行版。难以包含正确的文件,动态元数据支持有限。
- [pdm][]:一个现代化、不太固执己见的纯 Python 项目全面解决方案,支持标准。替代 setuptools、venv/pipenv、pip、wheel 和 twine。支持 [PEP 621][]。
- [whey][]:一个现代化的 [PEP 621][] 构建器,具有一些 Trove 分类器的自动化选项。开发似乎已停滞。(无 VCS 版本控制)
- [poetry][]:纯 Python 项目的全面解决方案。替代 setuptools、venv/pipenv、pip、wheel 和 twine。学习曲线较高,但功能全面。对库做出一些不好的默认假设。唯一一个使用非标准 pyproject.toml 配置的工具。
- [setuptools621][setuptools]:经典构建系统,但使用新的标准化配置。
- [setuptools][]:经典构建系统。功能最强大,但学习曲线高,需要大量配置。
- [pybind11][]:这是 setuptools,但包含用 [pybind11][] 编写的 C++ 扩展,并使用 [cibuildwheel][] 生成轮子。
- [scikit-build][]:一个使用 scikit-build(CMake)的项目,也使用 pybind11,使用 scikit-build-core。(推荐用于 C++ 项目)
- [meson-python][]:一个使用 pybind11 的 Meson 项目。(无 VCS 版本控制)
- [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中有pytestPP302
:设置pytest最低版本至少为6PP303
:设置测试路径PP304
:设置pytest的日志级别PP305
:指定xfail_strictPP306
:指定严格配置PP307
:指定严格标记PP308
:指定有用的pytest摘要PP309
:指定警告过滤
文档
RTD100
: 使用 ReadTheDocs(pyproject 配置)RTD101
: 必须将 RTD 版本号设置为 2RTD102
: 必须设置 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-codeMY105
: MyPy 启用 redundant-exprMY106
: MyPy 启用 truthy-bool
Pre-commit
PC100
: 有 pre-commit-hooksPC110
: 使用 black 或 ruff-formatPC111
: 使用 blacken-docsPC140
: 使用类型检查器PC160
: 使用拼写检查器PC170
: 使用 PyGrep hooks(仅当存在 rST 时需要)PC180
: 使用 Markdown 格式化工具PC190
: 使用 RuffPC191
: 如果启用修复功能,Ruff 会显示修复内容PC901
: 自定义 pre-commit CI 消息