Téléchargement cookie - Téléchargement du code source cookie

cookie

Code Source AI

2024.08.19

Télécharger

Python scientifique: guide, cookie et SP-Repo-Review

Cookie

Un modèle de copieur / gookietter pour de nouveaux projets Python basés sur le Guide scientifique du développeur Python. Qu'est-ce qui rend cela différent des autres modèles pour les packages Python?

Vit avec le guide de développement scientifique-python: chaque décision est clairement documentée et chaque outil décrit, et tout est gardé en synchronisation.
Neuf backends différents à choisir pour la construction de forfaits.
VCS en option VCS pour la plupart des backends.
Génération de modèle testée dans les actions GitHub à l'aide de NOx.
Soutient la génération avec Copier, Cookietter et Cruft.
Prend en charge les actions GitHub si le ciblage d'une URL github.com (la valeur par défaut) et ajoute une prise en charge expérimentale de GitLab CI autrement.
Comprend plusieurs backends compilés à l'aide de Pybind11, avec des roues produites pour toutes les plates-formes à l'aide de Cibuildwheel.
Fournit sp-repo-review pour évaluer les références existantes contre les directives, avec une version WebAssembly intégrée au guide. Tous les vérifications réticulées.
Suit les meilleures pratiques PYPA et régulièrement mises à jour.

Assurez-vous d'avoir lu le guide de développement scientifique-python en premier et que vous les avez peut-être utilisés sur un projet ou deux. Ce n'est pas un exemple ou un tutoriel minimal. Il s'agit d'une collection d'outils utiles pour démarrer un nouveau projet à l'aide de Cookietter, ou pour la copie dans des fichiers individuels pour un projet existant (à la main, à partir de {{cookiecutter.project_name}}/ ).

Pendant la génération, vous pouvez sélectionner parmi les backends suivants pour votre package:

Hatch: Cela utilise un nouveau-né, un constructeur moderne avec une belle inclusion de fichiers, extensible via des plugins et de bons messages d'erreur. (Recommandé pour les projets Python purs)
FLIT: un système de construction moderne et léger PEP 621 pour les projets pur python. Remplace Setuptools, no manifest.in, setup.py ou setup.cfg. Courbe d'apprentissage faible. Facile à démarrer dans de nouvelles distributions. Difficile d'obtenir les bons fichiers inclus, peu de support de métadonnées dynamiques.
PDM: Une solution tout-en-un moderne et moins opinionnée aux projets Python purs soutenant les normes. Remplace les Setuptools, Venv / Pipenv, Pip, Wheel et Twine. Prend en charge PEP 621.
Poésie: une solution tout-en-un aux projets pys python. Remplace les Setuptools, Venv / Pipenv, Pip, Wheel et Twine. Courbe d'enseignement supérieur, mais est tout-en-un. Fait de mauvaises hypothèses par défaut pour les bibliothèques. Le seul avec une configuration pyproject.toml non standard.
SETUPTOALS: le système de construction classique, mais avec la nouvelle configuration standardisée.
Pybind11: Il s'agit de SetUtuptools mais avec une extension C ++ écrite en Pybind11 et des roues générées par Cibuildwheel.
SCIKIT-BUILD: Un projet Scikit-Build (CMake) utilisant également Pybind11, en utilisant Scikit-Build-Core. (Recommandé pour les projets C ++)
Meson-Python: un projet Meson utilisant également Pybind11. (Pas de version VCS)
Maturin: un constructeur PEP 621 pour les extensions binaires de la rouille. (Pas de version VCS) (Recommandé pour les projets de rouille)

Actuellement, le meilleur choix est probablement l'éclosion des projets Python purs, et Scikit-Build (comme le choix Scikit-Build-Core + Pybind11) pour des projets binaires.

À utiliser (version de copie moderne)

Installez copier et copier-templates-extensions . En utilisant Pipx, c'est-à-dire:

pipx install copier
pipx inject copier copier-templates-extensions

Maintenant, exécutez le copieur pour générer votre projet:

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

( <pkg> est le chemin pour mettre le nouveau projet. Si le copieur est ancien, utilisez --UNSAFE au lieu de --trust )

Vous obtiendrez une expérience CLI plus agréable avec la validation des réponses. Vous obtiendrez également un fichier .copier-answers.yml , qui vous permettra d'effectuer des mises à jour à l'avenir.

Remarque: add --vcs-ref=HEAD pour obtenir la dernière version au lieu de la dernière version taguée; La tête passe toujours des tests (et c'est ce que Cookietter utilise).

À utiliser (version classique de Cookiectter)

Installez Cookietter, idéalement avec brew install cookiecutter si vous utilisez Brew, sinon avec pipx install cookiecutter (ou prend pipx run vers la commande ci-dessous et sautez l'installation). Puis courez:

cookiecutter gh:scientific-python/cookie

Si vous utilisez Cookietter 2.2.3+, vous obtiendrez de belles descriptions pour les options comme Copier!

À utiliser (version Classic Cruft)

Vous pouvez également utiliser Cruft, ce qui ajoute la mise à jour de la capacité aux projets Cookietter. Installez avec pipx install cruft (ou prend pipx run vers la commande ci-dessous et sautez l'installation). Puis courez:

cruft create gh:scientific-python/cookie

Post-génération

Vérifiez les fichiers de configuration de la clé, pyproject.toml et éventuellement setup.cfg et setup.py (exemple pybind11). Mettre à jour README.md . Mettez également à jour et ajoutez également les documents aux docs/ .

Il y a quelques exemples de dépendances et une version Python minimale de 3.9, n'hésitez pas à la modifier en tout ce dont vous avez réellement besoin. Il existe également une structure de bassin de base avec un petit exemple de dactylographie.

Composants contenus:

GitHub Actions exécute des tests pour la génération elle-même
- Utilise NOx pour que le développement des cookies puisse être vérifié localement
Déploiement des actions github
- Les backends C ++ incluent la roue cibuild pour les constructions de roues
- Utilise le déploiement de l'éditeur de confiance PYPI
Depenabot maintient les actions à jour périodiquement, grâce à des demandes de traction utiles
Formatage géré par pré-engagement
- Aucune raison de ne pas être stricte sur un nouveau projet; supprimer ce que vous ne voulez pas.
- Comprend MyPy - Typage statique
- Comprend Ruff - Formatage standard, libellé et autofixes
  - Remplace Flake8, Isort, Pyupgrade, Yesqa, Pycln et des dizaines de plugins
- Comprend la vérification des orthographes
Une cible Pylint NOX peut être utilisée pour exécuter Pylint, qui a intégré des annotations GHA
Un dossier Docs Sphinx Docs ReadTheDoCs et [docs] Extra
Un dossier de test et pytest [test] supplémentaire
Un Noxfile est inclus avec quelques cibles communes

Pour les développeurs:

Vous pouvez tester localement avec 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

Si vous n'avez pas nox localement, vous pouvez utiliser PIPX, comme pipx run nox à la place.

Autres projets similaires

Hypermodern-Python est un autre projet qui mérite d'être consulté avec de nombreuses similitudes, comme une excellente documentation pour chaque fonctionnalité et bon nombre des mêmes outils utilisés. Il a un ensemble de fonctionnalités légèrement différent et a une concentration plus forte sur les actions GitHub - la plupart de notre guide pourrait être adapté à un système CI différent assez facilement si vous ne voulez pas utiliser le GHA. Il oblige également l'utilisation de la poésie (au lieu d'avoir une sélection backend) et ne prend pas en charge les projets compilés. Il déverse actuellement toutes les dépendances de développement dans un environnement partagé, provoquant de longs temps de résolution et des chances élevées de conflits. Il n'utilise pas non plus de pré-engagement comme il était destiné à être utilisé. Il a également un peu de code personnalisé.

Histoire

Une grande partie du guide, de la cuisine et de la révision a commencé dans le cadre de Scikit-Hep. Ces projets ont été fusionnés, généralisés et combinés avec le guide NSLS-II lors du Sommet des développeurs scientifiques-python 2023.

SP-Repo-Review

sp-repo-review fournit des vérifications basées sur le guide de développement scientifique-python à Scientific-Python / Cookie pour Repo-Review.

Cet outil peut vérifier le style d'un référentiel. Utilisez comme ceci:

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

Cela produira une liste de résultats - les marques de contrôle vertes signifient que cette règle est suivie, la moyenne de la règle de Red X n'est pas. Un panneau d'avertissement jaune signifie que le chèque a été sauté car un chèque requis précédent a échoué. Certains chèques échoueront, ce n'est pas grave - l'objectif est de porter tous les problèmes possibles à votre attention, de ne pas forcer la conformité aux chèques arbitraires. Finalement, il pourrait y avoir un moyen de marquer les chèques comme ignorés.

Par exemple, GH101 s'attend à ce que tous vos fichiers d'action aient un joli name: champ. Si vous êtes satisfait des noms basés sur des fichiers que vous voyez dans CI, vous devez vous sentir libre d'ignorer simplement ce chèque (il suffit de l'ignorer visuellement pour le moment, un moyen de spécifier des chèques ignorés sera probablement ajouté finalement).

Tous les vérifications sont mentionnées au moins d'une manière ou d'une autre dans le guide de développement scientifique-python. Vous devez le lire d'abord - si vous n'essayez pas de les suivre, certains chèques pourraient ne pas fonctionner. Par exemple, les lignes directrices spécifient la configuration de Pytest être placée dans pyproject.toml . Si vous le placez ailleurs, tous les chèques de Pytest seront ignorés.

Cela a été initialement développé pour Scikit-Hep avant de passer à Scientific Python.

D'autres façons d'utiliser

Vous pouvez également utiliser des actions GitHub:

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

Ou pré-engagement:

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

Si vous utilisez additional_dependencies pour ajouter plus de plugins, comme validate-pyproject , vous devez également inclure "repo-review[cli]" pour vous assurer que les exigences CLI sont incluses.

Liste de chèques

Général

PY001 : a un pyproject.toml
PY002 : a un fichier Readme. (MD | RST)
PY003 : a un fichier de licence *
PY004 : a le dossier des documents
PY005 : a un dossier de tests
PY006 : a une configuration de pré-engagement
PY007 : prend en charge un coureur de tâche facile (NOx, Tox, Pixi, etc.)

Pyproject

PP002 : a une table de système de construction appropriée
PP003 : ne répertorie pas la roue comme une build-dep
PP004 : ne nécessite pas le python supérieur
PP301 : a pytest dans pyproject
PP302 : définit un pytest minimum à au moins 6
PP303 : définit les chemins de test
PP304 : Définit le niveau de journal dans PyTest
PP305 : spécifie xfail_strict
PP306 : spécifie la configuration stricte
PP307 : spécifie des marqueurs stricts
PP308 : Spécifie le résumé utile de Pytest
PP309 : avertissements de filtre spécifié

Documentation

RTD100 : utilise ReadTheDocs (config Pyproject)
RTD101 : vous devez définir le numéro de version RTD sur 2
RTD102 : Vous devez définir l'image RTD Build
RTD103 : Vous devez définir la version RTD Python

Actions github

GH100 : a la configuration des actions github
GH101 : a de beaux noms
GH102 : Auto-condenson sur PRS répété
GH103 : au moins un flux de travail avec déclencheur de répartition manuelle
GH104 : Utilisez des noms uniques pour le téléchargement artifact
GH200 : maintenu par Detenabot
GH210 : maintient les versions d'action GitHub avec Detenabot
GH211 : Ne comptez pas les actions de base comme versions majeures
GH212 : nécessite le groupe de mise à jour GHA

Mypy

MY100 : utilise mypy (pyproject config)
MY101 : mode strict mypy
MY102 : mypy show_error_codes déprécié
MY103 : mypy avertit inaccessible
MY104 : mypy permet d'ignorer avec le code
MY105 : mypy permet de redondant-expr
MY106 : mypy active la vérité-bol

Pré-engager

PC100 : a des pré-comités
PC110 : utilise le noir ou le format de rouff
PC111 : utilise des Blacken-Docs
PC140 : utilise un vérificateur de type
PC160 : utilise un vérificateur orthographique
PC170 : utilise des crochets Pygrep (uniquement nécessaires si le premier présent)
PC180 : utilise un formateur de marque
PC190 : utilise Ruff
PC191 : Ruff Show Correses Si les correctifs activés
PC901 : Message CI pré-engagement personnalisé