🧰 Scripts Python con argparse: CLIs claras y útiles

por
Shared post

Si tu script acepta rutas, flags o modos, argparse evita hardcodear y documenta el uso solo.

Más allá del comando suelto, lo importante es el contexto: cuándo aplicarlo, cómo validar el resultado y qué efectos secundarios puede tener en producción.

A continuación verás el porqué, ejemplos concretos con explicación, un flujo paso a paso, errores típicos y buenas prácticas para usarlo con confianza.

💡 Por qué argparse

  • Ayuda automática con --help
  • Validación básica de tipos
  • Misma interfaz para humanos y cron
  • Tener un procedimiento repetible reduce el tiempo de incidente
  • Documentar el enfoque ayuda al resto del equipo a operar igual de bien

🚀 Comandos y ejemplos

Esqueleto:

import argparse

p = argparse.ArgumentParser(description="Mi herramienta")
p.add_argument("path", help="Fichero de entrada")
p.add_argument("--dry-run", action="store_true")
args = p.parse_args()

Adapta este ejemplo a tus paths y nombres reales antes de usarlo en producción.

Argumento tipado:

p.add_argument("--workers", type=int, default=2)

argparse convierte y valida; fallará pronto si pasas texto.

Opciones excluyentes:

g = p.add_mutually_exclusive_group()
g.add_argument("--json", action="store_true")
g.add_argument("--csv", action="store_true")

Evita combinaciones de flags que no tienen sentido juntas.

🔧 Ejemplo práctico paso a paso

1. Sustituye sys.argv a mano por un parser

Caso: script de backup que recibe origen y –dry-run.

import argparse
p = argparse.ArgumentParser(description="Copia directorios")
p.add_argument("src")
p.add_argument("dst")
p.add_argument("--dry-run", action="store_true")
args = p.parse_args()

2. Implementa la rama dry-run

Si args.dry_run, solo lista lo que harías (print(f"copy {src} -> {dst}")). Si no, ejecuta la copia real. Así puedes enseñar el CLI sin miedo.

3. Prueba la ayuda y los errores

Ejecuta python backup.py -h y python backup.py sin args: debe fallar con mensaje claro, no con IndexError.

4. Documéntalo en la cabecera del README

Copia 2–3 ejemplos de invocación real (cron incluido). El –help es la doc viva; el README es para el equipo.

⚠️ Errores frecuentes

Flags destructivos sin dry-run. Un –delete o wipe sin ensayo es incidente asegurado. Para acciones peligrosas, dry-run por defecto o confirmación.

No tipar enteros/paths. type=int o Path evita fallar en mitad del script con datos basura.

Mensajes de error opacos. Si el path no existe, dilo; no dejes que traceback sea la UX del CLI.

💡 Buenas prácticas

  1. Nombres de flags cortos y largos consistentes.
  2. Defaults seguros (dry-run cuando el cambio es destructivo).
  3. Mensajes de error accionables.
  4. Prefiere cambios reversibles y con rollback claro.
  5. Corrrelaciona siempre con logs y, si puedes, con una métrica simple.
  6. Si el procedimiento se repite, conviértelo en script versionado.

📝 Conclusión

Un buen CLI hace que tu script deje de ser un apunte personal y pase a ser herramienta de equipo.

Si practicas este flujo con calma en staging, en producción te saldrá casi automático. Guarda tus variantes locales (paths, unidades, convenciones del equipo) junto a estos ejemplos.


Shared post