Saltearse al contenido

Herramientas mínimas

La tentación es instalar veinte herramientas y configurar un pipeline de doscientas líneas. Funciona una semana y luego nadie lo mantiene. Este capítulo propone el mínimo que resuelve la mayoría de los problemas, y el orden en que se adopta.

Entorno virtual, formateador, linter, tipos y depurador. Todo lo demás es opcional.

Herramienta Para qué Comando
venv (o uv) Aislar dependencias python -m venv .venv
ruff format Formato uniforme ruff format .
ruff check Errores y código muerto ruff check . --fix
mypy Contratos de tipos mypy src
pytest Comportamiento pytest -q
pdb / py-spy Depurar breakpoint()

ruff hace las veces de dos herramientas (formato y lint) en un binario escrito en Rust, y sustituye a flake8, isort, black y pyupgrade a la vez. Es la razón de que esté en la lista y los otros no.

  1. Entorno virtual por proyecto. Sin él, todo lo demás es irrelevante: dos proyectos con versiones distintas de la misma biblioteca son un bug garantizado.
  2. Formateador. Elimina discusiones de estilo y no discute: aplica y ya.
  3. Linter. Detecta variables sin usar, imports muertos y errores comunes. Se aplica con --fix y se revisa lo que queda.
  4. Tipos, en el código nuevo. mypy sobre un proyecto heredado sin anotaciones produce mil errores y se abandona. Empieza por los módulos que escribes hoy.
  5. Tests. El capítulo 03 de la Parte VII.
  6. Depurador. Cuando haga falta; no se instala, viene con Python.
[tool.ruff]
line-length = 100
target-version = "py311"
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B"]
[tool.mypy]
python_version = "3.11"
warn_unused_ignores = true
disallow_untyped_defs = true
[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-q"

Todo en pyproject.toml, un archivo por proyecto, nada escondido en .flake8, setup.cfg y mypy.ini a la vez.

  • Un script de veinte líneas. Ni mypy ni pytest.
  • Un notebook de análisis. El entorno del notebook ya trae lo necesario.
  • En un equipo sin CI. Las herramientas locales no se ejecutan solas; primero el CI (Parte VII, capítulo 08).

Un equipo nuevo quiere montar un proyecto desde cero. Ordena estas tareas y explica por qué ese orden: (a) configurar mypy estricto, (b) crear el entorno virtual, (c) añadir ruff al editor, (d) escribir el primer test, (e) configurar el CI.

Solución
  1. (b) Entorno virtual. Sin él, nada de lo demás es reproducible.
  2. (c) ruff en el editor. Se adopta sin fricción y desde el primer archivo, para que el formato no haya que corregirlo después en masa.
  3. (d) El primer test. Antes del CI, para que haya algo que ejecutar; y antes de mypy, porque el test documenta el comportamiento que el tipo debe respetar.
  4. (e) El CI. Automatiza lo anterior en cada push. Es lo que hace que las herramientas se usen.
  5. (a) mypy estricto. El último, y sólo sobre el código nuevo. Configurarlo primero, sin código, lleva a discusiones sobre reglas que aún no se han necesitado.

El criterio del orden: cada paso debe ser ejecutable y útil por sí solo, y el más costoso de mantener va al final, cuando ya hay evidencia de que hace falta.

  • Lott, S. F. Modern Python Cookbook, 3ª ed. Capítulos 16 y 17.
  • Ramalho, L. Fluent Python, 2ª ed. Capítulo 8.
  • Documentación de ruff, mypy, pytest y uv.
  • 02 · El intérprete: qué ejecutan estas herramientas.
  • 08 · CI y calidad (Parte VII): dónde se automatizan.
  • 03 · Testing (Parte VII): qué escribir primero.