cookie Download - cookie -Quellcode -Download

cookie

AI-Quellcode

2024.08.19

Herunterladen

Wissenschaftlicher Python: Leitfaden, Cookie & SP-Repo-Review

Plätzchen

Eine Kopierer/CookieCutter -Vorlage für neue Python -Projekte basierend auf dem wissenschaftlichen Python Developer Guide. Was unterscheidet dies von anderen Vorlagen für Python -Pakete?

Lebt mit dem Entwicklungsleitfaden für wissenschaftliche Python: Jede Entscheidung ist klar dokumentiert und jedes beschriebene Tool und alles synchronisiert gehalten.
Neun verschiedene Backends zur Auswahl zum Erstellen von Paketen.
Optionale VCS -Versioning für die meisten Backends.
Template -Erzeugung in GitHub -Aktionen mit NOx getestet.
Unterstützt die Generation mit Kopierer, CookieCutter und Cruft.
Unterstützt GitHub -Aktionen, wenn Sie auf eine github.com -URL (Standard) abzielen, und fügt ansonsten experimentelle Gitlab -CI -Unterstützung hinzu.
Enthält mehrere kompilierte Backends mit Pybind11, wobei Räder für alle Plattformen mit Cibuildwheel hergestellt werden.
Bietet sp-repo-review um vorhandene Repos anhand der Richtlinien zu bewerten, wobei eine WebAssembly-Version in den Leitfaden integriert ist. Alle Schecks verknüpft.
Folgt PYPA Best Practices und regelmäßig aktualisiert.

Stellen Sie sicher, dass Sie zuerst den Entwicklungshandbuch für wissenschaftliche Python gelesen und möglicherweise in ein oder zwei Projekten verwendet haben. Dies ist kein minimales Beispiel oder Tutorial. Es handelt sich um eine Sammlung nützlicher Tools zum Starten eines neuen Projekts mit CookieCutter oder zum Kopieren in einzelnen Dateien für ein vorhandenes Projekt (von Hand von {{cookiecutter.project_name}}/ ).

Während der Generation können Sie aus den folgenden Backends für Ihr Paket auswählen:

Hatch: Dies verwendet Jungtiere, einen modernen Bauunternehmer mit einer schönen Dateieinschließung, erweiterbar über Plugins und gute Fehlermeldungen. (Für reine Python -Projekte empfohlen)
Flit: Ein modernes, leichtes PEP 621 -Build -System für reine Python -Projekte. Ersetzt setuptools, noifest.in, setup.py oder setup.cfg. Niedrige Lernkurve. Einfach in neue Verteilungen zu starten. Es ist schwierig, die richtigen Dateien enthalten zu erhalten, wenig dynamische Metadatenunterstützung.
PDM: Eine moderne, weniger Meinung nach All-in-One-Lösung für reine Python-Projekte, die Standards unterstützen. Ersetzt Setuptools, Venv/Pipenv, Pip, Rad und Twine. Unterstützt PEP 621.
Poesie: Eine All-in-One-Lösung für reine Pythonprojekte. Ersetzt Setuptools, Venv/Pipenv, Pip, Rad und Twine. Hochernskurve, ist aber All-in-One. Macht einige schlechte Standardannahmen für Bibliotheken. Die einzige mit einer nicht standardmäßigen PYProject.toml-Konfiguration.
setuptools: Das klassische Build -System, jedoch mit der neuen standardisierten Konfiguration.
Pybind11: Dies sind Setuptools, aber mit einer C ++ - Erweiterung in Pybind11 und von Cibuildwheel erzeugten Rädern.
SCIKIT-BUILD: Ein CMake-Projekt (Scikit-Build), das auch Pybind11 verwendet, verwendet Scikit-Build-Core. (Für C ++ - Projekte empfohlen)
Meson-Python: Ein Meson-Projekt verwendet auch Pybind11. (Keine VCS -Versioning)
Maturin: Ein Pep 621 -Builder für Rost -Binärverlängerungen. (Keine VCS -Versioning) (empfohlen für Rostprojekte)

Derzeit ist die beste Wahl wahrscheinlich, dass sie für reine Python-Projekte und Scikit-Build (wie die Auswahl von Scikit-Build-Core + Pybind11) für binäre Projekte (wie die Auswahl von Scikit-Build-Core + Pybind11).

Zu verwenden (moderne Kopierversion)

Installieren Sie copier und copier-templates-extensions . Mit PIPX ist das:

pipx install copier
pipx inject copier copier-templates-extensions

Führen Sie nun Kopierer aus, um Ihr Projekt zu generieren:

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

( <pkg> ist der Weg, um das neue Projekt zu platzieren. Wenn der Kopierer alt ist, verwenden Sie --UNSAFE anstelle von --trust )

Sie erhalten eine schönere CLI -Erfahrung mit Antwortvalidierung. Sie erhalten auch eine .copier-answers.yml Datei, mit der Sie in Zukunft Updates durchführen können.

Hinweis: Hinzufügen --vcs-ref=HEAD um die neueste Version anstelle der letzten Tagged-Version zu erhalten. Der Kopf besteht immer durch Tests (und ist das, was CookieCutter verwendet).

Zu verwenden (klassische CookieCutter -Version)

Installieren Sie CookieCutter, idealerweise mit brew install cookiecutter , wenn Sie das Gebräu verwenden. Andernfalls pipx install cookiecutter (oder vorbereiten Sie pipx run mit dem folgenden Befehl und überspringen Sie die Installation). Dann rennen:

cookiecutter gh:scientific-python/cookie

Wenn Sie CookieCutter 2.2.3+ verwenden, erhalten Sie schöne Beschreibungen für die Optionen wie Copier!

Zu verwenden (klassische Cruft -Version)

Sie können auch Cruft verwenden, wodurch CookieTutter -Projekte das Fähigkeitsaktualisierung verleiht. Installieren Sie mit pipx install cruft (oder erstellen Sie pipx run mit dem Befehl unten und überspringen Sie die Installation). Dann rennen:

cruft create gh:scientific-python/cookie

Post -Generation

Überprüfen Sie die wichtigsten Setup -Dateien, pyproject.toml und möglicherweise setup.cfg und setup.py (Pybind11 -Beispiel). Update README.md . Aktualisieren Sie auch Dokumente und fügen Sie den docs/ hinzu.

Es gibt einige Beispielabhängigkeiten und eine minimale Python -Version von 3.9. Wechseln Sie sie gerne in das, was Sie tatsächlich brauchen/wollen. Es gibt auch eine einfache Backports -Struktur mit einem kleinen Schreibbeispiel.

Enthaltene Komponenten:

Github -Aktionen führen Tests für die Generation selbst durch
- Verwendet NOX, sodass die Cookie -Entwicklung lokal überprüft werden kann
GitHub -Aktionen bereitstellen
- C ++ Backends umfassen Cibuildwheel für Radbaufe
- Verwendet PYPI Trusted Publisher Deployment
Depelabot hält die Aktionen regelmäßig durch nützliche Pull -Anfragen auf dem neuesten Stand
Formatierung von Pre-Commit
- Kein Grund, ein neues Projekt nicht streng zu haben; Entfernen Sie, was Sie nicht wollen.
- Beinhaltet mypy - statische Typisierung
- Beinhaltet Ruff - Standardformatierung, Linie und Autofixe
  - Ersetzt Flake8, ISORT, Pyupgrade, Yesqa, Pycln und Dutzende von Plugins
- Beinhaltet die Prüfung der Zaubersprüche
Ein Pylint -Nox -Ziel kann zum Ausführen von Pyraint verwendet werden, das GHA -Annotationen integriert hat
Ein redethedocs-fertiger Sphinx-Dokument und [docs] extra
Ein Testordner und PyTest [test] extra
Ein NoxFile ist mit einigen gemeinsamen Zielen enthalten

Für Entwickler:

Sie können lokal mit Nox testen:

# 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

Wenn Sie nox vor Ort nicht haben, können Sie PIPX wie pipx run nox verwenden.

Andere ähnliche Projekte

Hypermodern-Python ist ein weiteres Projekt, das es wert ist, mit vielen Ähnlichkeiten nachzudenken, z. B. großartige Dokumentation für jede Funktion und viele der gleichen verwendeten Tools. Es hat etwas andere Funktionen und konzentriert sich stärker auf Github -Aktionen. Die meisten unserer Anleitung können an ein anderes CI -System ziemlich einfach angepasst werden, wenn Sie GHA nicht verwenden möchten. Es erzwingt auch die Verwendung von Gedichten (anstatt eine Backend -Auswahl) und unterstützt keine kompilierten Projekte. Derzeit steckt es alle Entwicklungsabhängigkeiten in ein gemeinsames Umfeld, was zu langen Lösungszeiten und hohe Wahrscheinlichkeit von Konflikten führt. Es verwendet auch nicht die Art und Weise, wie es verwendet werden sollte. Es hat auch ein paar benutzerdefinierte Code.

Geschichte

Ein Großteil des Leitfadens, des CookieCutter und des Repo-Review begann als Teil von Scikit-Hep. Diese Projekte wurden während des Gipfels für wissenschaftliche Python-Entwickler mit dem NSLS-II-Leitfaden zusammengeführt, verallgemeinert und kombiniert.

SP-Repo-Review

sp-repo-review bietet Schecks basierend auf dem wissenschaftlichen Python Development Guide bei Scientific-Python/Cookie für Repo-Review.

Dieses Tool kann den Stil eines Repositorys überprüfen. Verwenden Sie so:

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

Dies erzeugt eine Liste von Ergebnissen - grüne Checkmarks bedeuten, dass diese Regel befolgt wird, der Mittelwert der Regel ist nicht. Ein gelbes Warnschild bedeutet, dass der Scheck übersprungen wurde, da ein früherer erforderlicher Scheck fehlgeschlagen ist. Einige Überprüfungen werden scheitern, das ist in Ordnung - das Ziel ist es, alle möglichen Probleme aufmerksam zu machen, nicht um die Einhaltung willkürlicher Überprüfungen zu erzwingen. Schließlich könnte es eine Möglichkeit geben, Schecks zu markieren, die ignoriert werden.

Zum Beispiel erwartet GH101 , dass alle Ihre Aktionsdateien einen schönen name: Feld. Wenn Sie mit den in CI angezeigten Dateinamen zufrieden sind, sollten Sie diese Überprüfung einfach ignorieren (nur visuell ignorieren Sie sie für den Moment visuell, eine Möglichkeit, ignorierte Schecks anzugeben, wird wahrscheinlich irgendwann hinzugefügt).

Alle Schecks werden zumindest in irgendeiner Weise im Entwicklungsleitfaden für wissenschaftliche Python erwähnt. Sie sollten das zuerst lesen - wenn Sie nicht versuchen, ihnen zu folgen, funktionieren einige der Schecks möglicherweise nicht. Beispielsweise geben die Richtlinien an, dass die PyTest -Konfiguration in pyproject.toml platziert werden. Wenn Sie es woanders platzieren, werden alle PyTest -Schecks übersprungen.

Dies wurde ursprünglich für Scikit-Hep entwickelt, bevor sie zu Scientific Python wechselte.

Andere Möglichkeiten zu verwenden

Sie können auch GitHub -Aktionen verwenden:

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

Oder vor dem Kommission:

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

Wenn Sie additional_dependencies verwenden, um weitere Plugins hinzuzufügen, z. B. validate-pyproject , sollten Sie auch "repo-review[cli]" einschließen, um sicherzustellen, dass die CLI-Anforderungen enthalten sind.

Liste der Schecks

Allgemein

PY001 : Hat eine PYProject.toml
PY002 : Hat eine lesende Datei (MD | RST)
PY003 : Hat eine Lizenz* Datei*
PY004 : Hat Docs -Ordner
PY005 : Hat Test -Ordner hat
PY006 : Hat eine Vorkommachtkonfiguration
PY007 : Unterstützt einen leichten Task -Läufer (NOX, Tox, Pixi usw.)

PYPROJECT

PP002 : hat eine ordnungsgemäße Build-System-Tabelle
PP003 : Listet Wheel nicht als Build-Dep auf
PP004 : erfordert nicht obere Kappe Python erfordert
PP301 : hat pytest in PyProject
PP302 : Legt einen Mindestpytest auf mindestens 6 fest
PP303 : Legt die Testpfade fest
PP304 : Legt die Protokollebene in PyTest fest
PP305 : Gibt xfail_strict an
PP306 : Gibt strenge Konfiguration an
PP307 : Gibt strenge Marker an
PP308 : Gibt eine nützliche PyTest -Zusammenfassung an
PP309 : Filterwarnungen angegeben

Dokumentation

RTD100 : Verwendet Redethedocs (PYProject -Konfiguration)
RTD101 : Sie müssen die RTD -Versionsnummer auf 2 festlegen
RTD102 : Sie müssen das Rtd -Build -Bild festlegen
RTD103 : Sie müssen die Rtd Python -Version festlegen

Github -Aktionen

GH100 : Hat GitHub -Aktionen config
GH101 : Hat schöne Namen
GH102 : Auto-Cancel auf wiederholten PRs
GH103 : Mindestens ein Workflow mit manuellem Versandauslöser
GH104 : Verwenden Sie eindeutige Namen für Upload-Artifact
GH200 : Von DeVeabot gepflegt
GH210 : Behält die GitHub -Aktionsversionen mit Abhängigkeit bei
GH211 : Pinieren Sie keine Kernaktionen als Hauptversionen
GH212 : Erfordernde GHA -Update -Gruppierung

Mypy

MY100 : Verwendet MyPy (PYProject -Konfiguration)
MY101 : MyPy Strict -Modus
MY102 : mypy show_error_codes veraltet
MY103 : mypy warnen unerreichbar
MY104 : MyPy ermöglicht es, ohne Code zu ignorieren
MY105 : MyPy ermöglicht redundant-expr
MY106 : Mypy ermöglicht die Wahrheit

Vorvermittlung

PC100 : hat vor-Commit-Hooks
PC110 : Verwendet Schwarz oder Ruff-Format
PC111 : Verwendet Black-Docs
PC140 : Verwendet einen Typ Checker
PC160 : Verwendet eine Zauberprüfung
PC170 : Verwendet PyGrep -Haken (nur erforderlich, wenn erstmals vorhanden ist)
PC180 : Verwendet ein Markdown -Formatierer
PC190 : Verwendet Ruff
PC191 : Ruff Show Fixes Wenn die Korrekturen aktiviert sind
PC901 : benutzerdefinierte CI-Nachricht vor dem Kommando