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 ：使用（新的）絨毛配置部分