Descarga cookie - Descargar código fuente cookie

cookie

Código Fuente de IA

2024.08.19

Descargar

Científica Python: Guía, galletas y SP-Repo-Review

Galleta

Una plantilla de copiadora/cocinera para nuevos proyectos de Python basados en la Guía de desarrolladores de Python Scientific. ¿Qué hace que esto sea diferente de otras plantillas para los paquetes de Python?

Vive con la Guía de Desarrollo de Python Scientific: cada decisión está claramente documentada y cada herramienta descrita, y todo se mantiene sincronizado.
Nueve backends diferentes para elegir para paquetes de construcción.
Versiones de VCS opcionales para la mayoría de los backends.
Generación de plantilla probada en acciones de GitHub usando NOX.
Admite la generación con copiadores, cocinero y cruft.
Admite acciones de GitHub si se dirige a una URL github.com (el valor predeterminado), y agrega soporte experimental de GITLAB CI de lo contrario.
Incluye varios backends compilados usando Pybind11, con ruedas producidas para todas las plataformas que usan Cibuildwheel.
Proporciona sp-repo-review para evaluar los Repos existentes con las pautas, con una versión de WebAssembly integrada con la guía. Todos los cheques reticulados.
Sigue las mejores prácticas de PYPA y se actualiza regularmente.

Asegúrese de haber leído primero la Guía de Desarrollo de Python Scientific, y posiblemente los haya usado en un proyecto o dos. Este no es un ejemplo o tutorial mínimo. Es una colección de herramientas útiles para comenzar un nuevo proyecto usando Cookiecutter, o para copiar en archivos individuales para un proyecto existente (a mano, de {{cookiecutter.project_name}}/ ).

Durante la generación, puede seleccionar entre los siguientes backends para su paquete:

Hatch: Esto usa Hatchling, un constructor moderno con buena inclusión de archivos, extensible a través de complementos y buenos mensajes de error. (Recomendado para proyectos puros de Python)
Flit: un sistema de compilación PEP 621 moderno y liviano para proyectos puros de Python. Reemplaza setupTools, no manifest.in, setup.py o setup.cfg. Curva baja de aprendizaje. Fácil de arranque en nuevas distribuciones. Difícil de incluir los archivos correctos, pequeño soporte de metadatos dinámicos.
PDM: una solución todo en uno moderna y menos obstinada para proyectos de Python puro que respaldan los estándares. Reemplaza SetupTools, Venv/Pipenv, Pip, Wheel y Twine. Admite PEP 621.
Poesía: una solución todo en uno para los proyectos de Python Pure. Reemplaza SetupTools, Venv/Pipenv, Pip, Wheel y Twine. Curva de aprendizaje superior, pero es todo en uno. Hace algunos supuestos predeterminados para bibliotecas. El único con una configuración PyProject.toml no estándar.
SetupTools: el clásico sistema de compilación, pero con la nueva configuración estandarizada.
Pybind11: Esto es SetupTools pero con una extensión C ++ escrita en Pybind11 y ruedas generadas por Cibuildwheel.
Scikit-Build: un proyecto Scikit-Build (CMake) que también usa Pybind11, utilizando scikit-build-core. (Recomendado para proyectos C ++)
Meson-Python: un proyecto Meson también usando Pybind11. (Sin versiones de VCS)
Maturina: un constructor PEP 621 para extensiones binarias de óxido. (Sin versiones de VCS) (recomendado para proyectos de óxido)

Actualmente, la mejor opción es probablemente Hatch para Pure Python Projects, y Scikit-Build (como la elección scikit-build-core + pybind11) para proyectos binarios.

Para usar (versión de copiadora moderna)

Instale copier y copier-templates-extensions . Usando Pipx, eso es:

pipx install copier
pipx inject copier copier-templates-extensions

Ahora, ejecute Copier para generar su proyecto:

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

( <pkg> es el camino para poner el nuevo proyecto. Si la copiadora es antigua, use --UNSAFE en lugar de --trust )

Obtendrá una mejor experiencia de CLI con la validación de respuestas. También obtendrá un archivo .copier-answers.yml , que le permitirá realizar actualizaciones en el futuro.

NOTA: Agregar --vcs-ref=HEAD para obtener la última versión en lugar de la última versión etiquetada; La cabeza siempre pasa pruebas (y es lo que usa Cookiecutter).

Para usar (versión clásica de CookiCutter)

Instale CookieCutter, idealmente con brew install cookiecutter si usa cerveza, de lo contrario con pipx install cookiecutter (o prepender pipx run al comando a continuación y omita la instalación). Luego corre:

cookiecutter gh:scientific-python/cookie

Si está utilizando Cookiecutter 2.2.3+, ¡obtendrá buenas descripciones para las opciones como Copier!

Para usar (versión clásica de Cruft)

También puede usar Cruft, lo que agrega la actualización de habilidad a los proyectos de CookieCutter. Instale con pipx install cruft (o Prepend pipx run al comando a continuación y omita la instalación). Luego corre:

cruft create gh:scientific-python/cookie

Post generación

Verifique los archivos de configuración de clave, pyproject.toml y posiblemente setup.cfg y setup.py (ejemplo pybind11). Actualizar README.md . También actualice y agregue documentos a docs/ .

Hay algunas dependencias de ejemplo y una versión mínima de Python de 3.9, no dude en cambiarlo a lo que realmente necesite/desee. También hay una estructura básica de backports con un pequeño ejemplo de tipificación.

Componentes contenidos:

Las acciones de GitHub ejecutan pruebas para la generación misma
- Utiliza NOX para que el desarrollo de cookies se pueda verificar localmente
Implementar acciones de github
- Los backends de C ++ incluyen cibuildwheel para construcciones de ruedas
- Utiliza la implementación del editor de confianza PYPI
Dependabot mantiene las acciones actualizadas periódicamente, a través de solicitudes de extracción útiles
Formato manejado por pre-compromiso
- No hay razón para no ser estricto en un nuevo proyecto; Elimina lo que no quieres.
- Incluye mypy - tipificación estática
- Incluye Ruff: formato estándar, pelusas y autofixes
  - Reemplaza a Flake8, Isort, Pyupgrade, Yesqa, Pycln y docenas de complementos
- Incluye la comprobación de hechizos
Se puede usar un objetivo de Pylint NOx para ejecutar Pylint, que integró anotaciones de GHA
Una carpeta Sphinx Docs de ReadThedocs lista y [docs] Extra
Una carpeta de prueba y pytest [test] extra
Se incluye un noxfile con algunos objetivos comunes

Para los desarrolladores:

Puede probar localmente con 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 no tiene nox localmente, puede usar PIPX, como pipx run nox .

Otros proyectos similares

Hypermodern-Python es otro proyecto que vale la pena ver con muchas similitudes, como una gran documentación para cada característica y muchas de las mismas herramientas utilizadas. Tiene un conjunto de características ligeramente diferentes y tiene un enfoque más fuerte en las acciones de GitHub; la mayoría de nuestra guía podría adaptarse a un sistema CI diferente con bastante facilidad si no desea usar GHA. También obliga al uso de la poesía (en lugar de tener una selección de backend), y no admite proyectos compilados. Actualmente arroja todas las dependencias de desarrollo en un entorno compartido, causando largos tiempos de resolución y altas posibilidades de conflictos. Tampoco usa pre-compromiso de la forma en que se pretendía ser utilizada. También tiene bastante código personalizado.

Historia

Gran parte de la guía, CookieCutter y Repo-Review comenzaron como parte de Scikit-Hep. Estos proyectos se fusionaron, generalizaron y se combinaron con la Guía NSLS-II durante la Cumbre de Desarrolladores de Python de Python 2023.

SP-Repo-Review

sp-repo-review proporciona cheques basados en la Guía de Desarrollo de Python Scientific en Scientific-Python/Cookie para Repo-Review.

Esta herramienta puede verificar el estilo de un repositorio. Use así:

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

Esto producirá una lista de resultados: las marcas de verificación verdes significan que esta regla se sigue, la Red X significa que la regla no lo es. Una señal de advertencia amarilla significa que el cheque se omitió porque falló un cheque previo requerido. Algunos cheques fallarán, está bien: el objetivo es atraer todos los problemas posibles a su atención, no para forzar el cumplimiento de los controles arbitrarios. Finalmente, podría haber una manera de marcar las verificaciones como se ignoran.

Por ejemplo, GH101 espera que todos sus archivos de acción tengan un buen name: campo. Si está satisfecho con los nombres basados en archivos que ve en CI, debe sentirse libre de simplemente ignorar este cheque (solo ignorarlo visualmente por el momento, es probable que se agregue una forma de especificar cheques ignorados).

Todos los controles se mencionan al menos de alguna manera en la Guía de Desarrollo de Python Scientific. Debería leer eso primero: si no está intentando seguirlos, algunos de los cheques podrían no funcionar. Por ejemplo, las pautas especifican la configuración de Pytest se colocan en pyproject.toml . Si lo coloca en otro lugar, se omitirán todas las verificaciones de Pytest.

Esto se desarrolló originalmente para Scikit-Hep antes de mudarse a la Python científica.

Otras formas de usar

También puede usar acciones de GitHub:

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

O pre-compromiso:

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

Si usa additional_dependencies para agregar más complementos, como validate-pyproject , también debe incluir "repo-review[cli]" para garantizar que se incluyan los requisitos de la CLI.