cookie

科学Python：指南，饼干和SP-Repo-Review

曲奇饼

基于科学Python开发人员指南的新Python项目的复印机/CookieCutter模板。是什么使这与其他模板不同的Python软件包有所不同？

• 伴随着科学派景发展指南：每个决定都清楚地记录下来，并描述了每个工具，并且一切都保持同步。
• 九个不同的后端可供选择用于建筑包。
• 大多数后端的可选VCS版本控制。
• 模板生成使用NOx在GitHub动作中测试。
• 支持复印机，烹饪和Cruft的生成。
• 如果针对github.com URL（默认值），则支持GitHub动作，并添加实验性Gitlab CI支持。
• 包括使用PYBIND11的几个编译后端，并使用Cibuildwheel为所有平台生产了轮子。
• 提供sp-repo-review以与指南集成的WebAssembly版本来评估现有存储量。所有检查都通过交联。
• 遵循PYPA最佳实践并定期更新。

请确保您首先阅读了科学派景开发指南，并可能将它们用于一两个项目。这不是一个最小的例子或教程。它是用于使用CookieCutter启动新项目的有用工具的集合，或者用于在单个文件中复制现有项目（手工，来自{{cookiecutter.project_name}}/ ）。

在一代中，您可以从以下后端选择包装：

1. 孵化：这使用了孵化器，一个现代化的构建器，具有良好的文件包含，可通过插件扩展以及良好的错误消息。 （建议用于纯Python项目）
2. Flit：现代，轻巧的PEP 621构建系统，用于纯Python项目。替换setuptools，no suftest.in，setup.py或setup.cfg。低学习曲线。容易引导到新的分布中。很难包含正确的文件，几乎没有动态元数据支持。
3. PDM：一种现代，不太自明的多合一解决方案，用于支持标准的纯Python项目。替换Setuptools，VENV/PIPENV，PIP，车轮和麻线。支持PEP 621。
4. 诗歌：纯Python项目的多合一解决方案。替换Setuptools，VENV/PIPENV，PIP，车轮和麻线。更高的学习曲线，但是多合一的。对库做出一些不良的默认假设。唯一具有非标准pyproject.toml config的人。
5. SetUptools：经典构建系统，但具有新的标准化配置。
6. pybind11：这是setuptools，但用pybind11编写的C ++扩展名，以及由Cibuildwheel产生的车轮。
7. Scikit-Build：使用Scikit-Build-Core使用PYBIND11的Scikit-Build（CMAKE）项目。 （建议用于C ++项目）
8. Meson-Python：也使用PYBIND11的梅森项目。 （无VCS版本化）
9. Maturin：PEP 621构建器，用于生锈的二进制扩展。 （无VCS版本） （建议生锈项目）

目前，最佳选择可能是用于纯Python项目的孵化，而Scikit-Build（例如Scikit-Build-Core + Pybind11选择）则用于二进制项目。

使用（现代复印机版本）

安装copier和copier-templates-extensions 。使用pipx，那就是：

pipx install copier
pipx inject copier copier-templates-extensions

现在，运行复印机生成您的项目：

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

（ <pkg>是放置新项目的途径。如果复印机旧，请使用--UNSAFE代替--trust ）

在答案验证方面，您将获得更好的CLI体验。您还将获得.copier-answers.yml文件，该文件将使您将来执行更新。

注意：add --vcs-ref=HEAD获取最新版本，而不是最后一个标记的版本；头部总是通过测试（这是CookieCutter使用的）。

使用（经典烹饪版本）

如果使用啤酒，请安装CookieCutter，理想情况下，使用brew install cookiecutter ，否则使用pipx install cookiecutter （或PREDEND 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/ 。

有几个示例依赖项和3.9的最低python版本，可以随意将其更改为实际需要/想要的任何东西。还有一个基本的Backports结构，带有一个小型键入示例。

包含组件：

• github动作运行对一代本身的测试
  • 使用NOX因此可以在本地检查Cookie开发
• GitHub动作部署
  • C ++后端包括用于车轮构建的Cibuildwheel
  • 使用PYPI受信任的发布者部署
• 通过有用的拉请请求，Disperabot定期定期保持最新操作
• 由预先承诺处理的格式
  • 没有理由不严格对新项目；删除您不需要的东西。
  • 包括mypy-静态打字
  • 包括ruff-标准格式，覆盖和自动框
    • 替换Flake8，Isort，Pyupgrade，Yesqa，Pycln和数十个插件
  • 包括拼写检查
• 可以使用Pylint NOX目标运行Pylint，该pylint集成了GHA注释
• 一个读取的sphinx docs文件夹和[docs]额外
• 测试文件夹和pytest [test]额外
• 一些常见目标包括一个noxfile

对于开发人员：

您可以使用NOX在本地测试：

# See all commands
nox -l

# Run a specific check
nox -s "lint(scikit-build)"

# Run a noxfile command on the project noxfile
nox -s "nox(hatch)" -- docs

如果您在本地没有nox ，则可以使用PIPX，例如pipx run nox 。

其他类似的项目

Hyper-Modern-Python是另一个值得检查的项目，具有许多相似之处，例如每个功能的出色文档以及许多相同的工具。它具有一组略有不同的功能，并且更加专注于GitHub动作 - 如果您不想使用GHA，我们的指南大多数可以很容易地适应其他CI系统。它还迫使使用诗歌（而不是对后端选择），并且不支持编译的项目。目前，它将所有发展依赖性转移到共享环境中，导致较长的求解时间和冲突的很大机会。它也不使用预先承诺的预定方式。它也有很多自定义代码。

历史

大量的指南，烹饪和回购评论始于Scikit-Hep的一部分。这些项目在2023年的Scientific-Python开发人员峰会上合并，广泛并与NSLS-II指南相结合。

---

SP-Repo-Review

sp-repo-review提供了基于科学Python/cookie的科学派景开发指南的检查，用于repo-Review。

该工具可以检查存储库的样式。这样使用：

pipx run ' sp-repo-review[cli] ' < path to repository >

这将产生结果列表 - 绿色的选中标记意味着遵循此规则，红色X的平均规则不是。黄色警告标志意味着支票被跳过，因为先前的要求检查失败。有些检查会失败，这没关系 - 目标是将所有可能的问题引起您的注意，而不是强制遵守任意检查。最终可能有一种标记检查的方法。

例如， GH101期望您的所有操作文件都有一个不错的name:字段。如果您对CI中看到的基于文件的名称感到满意，则应随意忽略此支票（目前目视忽略它，最终可能会添加一种指定忽略的支票的方法）。

至少在科学派森开发指南中至少以某种方式提及所有检查。您应该首先阅读 - 如果您不尝试关注它们，则某些检查可能无法使用。例如，指南指定pytest配置将其放置在pyproject.toml中。如果将其放置在其他地方，则所有的pytest检查将被跳过。

这最初是为Scikit-Hep开发的，然后再搬到科学的Python。

其他使用方式

您也可以使用GitHub操作：

- uses : scientific-python/cookie@<version>

或预先提交的：

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

如果您使用additional_dependencies添加更多插件，例如validate-pyproject ，则还应包括"repo-review[cli]"以确保包括CLI要求。

支票列表

一般的

• PY001 ：有一个pyproject.toml
• PY002 ：有一个读数。（MD | rst）文件
• PY003 ：有许可证*文件
• PY004 ：有Docs文件夹
• PY005 ：具有测试文件夹
• PY006 ：具有预加密配置
• PY007 ：支持一个简单的任务跑步者（NOX，TOX，PIXI等）

拟型

• PP002 ：具有适当的构建系统表
• PP003 ：不将车轮列为构建二孔
• PP004 ：不需要上限的上限
• PP301 ：pytest pyproject
• 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动作

• GH100 ：具有GitHub操作配置
• GH101 ：有好名字
• GH102 ：重复PR上的自动cancel
• GH103 ：至少一个带有手动调度触发器的工作流程
• GH104 ：使用唯一的名称进行上载艺术
• GH200 ：由Dependabot维护
• GH210 ：使用DiDeNTABOT维护GitHub动作版本
• GH211 ：不要将核心动作固定为主要版本
• GH212 ：需要GHA更新分组

mypy

• MY100 ：使用mypy（pyproject配置）
• MY101 ：mypy严格模式
• MY102 ：mypy show_error_codes弃用
• MY103 ：mypy警告无法到达
• MY104 ：mypy启用忽略无代码
• MY105 ：mypy启用冗余-Expr
• MY106 ：mypy启用真相

预警

• PC100 ：有前钩子
• PC110 ：使用黑色或皱纹格式
• PC111 ：使用黑色docs
• PC140 ：使用类型检查器
• PC160 ：使用拼写检查器
• PC170 ：使用pygrep挂钩（仅在第一个时才需要）
• PC180 ：使用Markdown Formatter
• PC190 ：使用ruff
• PC191 ：ruff show修复如果启用了修复
• PC901 ：自定义预签名CI消息

拉夫

• RF001 ：有ruff配置
• RF002 ：必须设置目标版本
• RF003 ：不再需要指定SRC目录（0.6+）
• RF101 ：必须选择Bugbear
• RF102 ：必须选择ISORT
• RF103 ：必须选择Pyupgrade
• RF201 ：避免使用不推荐的配置设置
• RF202 ：使用（新的）绒毛配置部分