Hatch reúne entornos, scripts, versionado y build de proyectos Python. La configuración vive en pyproject.toml, por lo que las tareas quedan documentadas y versionadas.

Configurar un entorno

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "ejemplo-app"
version = "0.1.0"
requires-python = ">=3.12"

[tool.hatch.envs.test]
dependencies = ["pytest"]

[tool.hatch.envs.test.scripts]
run = "pytest -q {args:tests}"

Después de instalar Hatch como herramienta, ejecuta hatch run test:run. El entorno se crea aislado y acepta argumentos desde la línea de comandos.

Separar responsabilidades

Hatchling construye distribuciones; el CLI Hatch orquesta tareas. Así un paquete puede usar Hatchling sin obligar a sus consumidores a instalar Hatch. Antes de publicar, ejecuta hatch build, inspecciona wheel y sdist e instala los artefactos en un entorno limpio.

La guía de pyproject.toml explica metadatos, y uv para Python propone otro flujo. No combines herramientas solapadas sin decidir quién controla lock, entornos y build.

La documentación oficial de Hatch, consultada el 22 de julio de 2026, cubre entornos, scripts y build. Fija herramientas en CI y protege credenciales de publicación.

Separar Hatch de Hatchling

Hatch es la herramienta de proyecto que crea entornos, ejecuta scripts, actualiza versiones e inicia builds. Hatchling es un backend compatible con los estándares de empaquetado. build-backend = "hatchling.build" indica a herramientas como python -m build cómo producir wheel y sdist; no obliga a colaboradores o consumidores a usar hatch.

La distinción evita acoplamiento innecesario. Un equipo puede estandarizar tareas con Hatch y producir artefactos instalables por pip. También puede usar Hatchling con otra herramienta de entornos. Asigna un responsable a cada función y documenta la elección.

Declarar metadatos y estructura

Para una biblioteca guardada en src/ejemplo, declara los paquetes del wheel:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "ejemplo-utils"
version = "0.1.0"
description = "Utilidades para el proyecto Ejemplo"
readme = "README.md"
requires-python = ">=3.11"
dependencies = ["httpx>=0.27,<1"]

[tool.hatch.build.targets.wheel]
packages = ["src/ejemplo"]

El nombre de distribución puede contener guion, mientras el paquete importable usa un identificador Python. Comprueba que el wheel contiene módulos, información de tipos y datos necesarios. No incluyas pruebas, secretos o archivos locales por accidente.

Organizar entornos por finalidad

Los entornos independientes impiden que herramientas de documentación entren en la ejecución principal:

[tool.hatch.envs.test]
dependencies = [
  "pytest",
  "pytest-cov",
]

[tool.hatch.envs.test.scripts]
run = "pytest {args:tests}"
cov = "pytest --cov=ejemplo --cov-report=term-missing {args:tests}"

[tool.hatch.envs.docs]
dependencies = ["sphinx"]

[tool.hatch.envs.docs.scripts]
build = "sphinx-build -W docs build/docs"

Ejecuta hatch run test:run y pasa una ruta si hace falta. Los scripts cortos ofrecen una interfaz estable al equipo y CI. No escondas lógica compleja en una línea TOML; mueve flujos largos a un módulo Python comprobable.

Probar varias versiones de Python

Las matrices verifican la compatibilidad declarada:

[tool.hatch.envs.test]
matrix-name-format = "py{value}"

[[tool.hatch.envs.test.matrix]]
python = ["3.11", "3.12", "3.13"]

Ejecuta solo versiones soportadas. Si falta un intérprete, instálalo conscientemente o configura un proveedor adecuado. Una ejecución omitida no demuestra compatibilidad. Mantén visible la matriz de CI para identificar la versión que falla.

Gestionar la versión desde una fuente

Hatch puede leer la versión desde un archivo o fuente configurada. Una única fuente evita divergencias entre código, metadatos y documentación. Antes de automatizar incrementos, decide si el proyecto sigue versionado semántico y quién autoriza releases.

No derives versiones del estado Git sin considerar builds fuera del repositorio. Los artefactos necesitan versiones deterministas, y repetir el build del mismo commit debe producir metadatos equivalentes.

Construir e inspeccionar artefactos

hatch build crea wheel y sdist en dist/. No publiques de inmediato. Lista el contenido del wheel, extrae el sdist en un directorio temporal e instala ambos en entornos limpios. Prueba al menos un import y --help si existe CLI.

hatch build
python -m pip install dist/ejemplo_utils-0.1.0-py3-none-any.whl
python -c "import ejemplo; print(ejemplo.__name__)"

El nombre exacto depende de los metadatos. En automatización, descubre el artefacto de forma controlada y falla si aparecen cero o varios candidatos inesperados.

Proteger la publicación

Construir y publicar son etapas distintas. La primera puede ejecutarse en cada pull request; la segunda debe requerir una etiqueta protegida o aprobación. Usa tokens con privilegios mínimos y publicación confiable si el índice la admite. Nunca muestres credenciales en logs.

Empieza con un índice de prueba al validar el flujo. Comprueba nombre, versión, descripción, archivos y dependencias. Los índices normalmente no permiten reemplazar una versión existente, por lo que un error exige otra versión según su política.

Adoptar Hatch sin confundir al equipo

Documenta en el README los comandos esenciales para pruebas, documentación y build. Haz que CI llame los mismos scripts. Fija la versión de Hatch usada por la automatización o define una política de actualización.

Hatch aporta valor cuando sustituye scripts divergentes por configuración comprensible. No elimina la revisión de dependencias, las pruebas de artefactos ni la protección de releases. Un proyecto predecible aclara qué herramienta resuelve dependencias, cuál crea entornos, cuál construye y quién puede publicar.