Diseñar una herramienta de línea de comandos en Python: argparse, main() y códigos de salida

Objetivo

Construir una herramienta de línea de comandos que scripts de shell, trabajos de CI y agentes puedan manejar: argumentos predecibles, un texto de ayuda que sea la documentación, códigos de salida estructurados y flujos limpios.

Requisitos previos

Un paquete con un pyproject.toml (véase el artículo sobre empaquetado) cuya lógica resida en funciones importables, separadas del manejo de argumentos.

Pasos

1. Escribir def main(argv: list[str] | None = None) -> int que construya el parser, analice argv (recurriendo a sys.argv[1:] si falta) y devuelva un código de salida. Registrarla como [project.scripts] tool = "pkg.cli:main" y añadir if __name__ == "__main__": sys.exit(main()). Las pruebas entonces llaman a main(["--flag", "x"]) y verifican el valor devuelto y la salida capturada.
2. Construir el parser con prog, description y un epilog de ejemplos. Usar conversores type= (int, pathlib.Path, o una función que lance ArgumentTypeError) para que los valores incorrectos se reporten como errores de uso, choices= para conjuntos cerrados, y add_subparsers(dest="command", required=True) para herramientas con varios comandos.
3. Seguir la convención que describe la documentación de sys.exit: los programas Unix generalmente usan 2 para errores de sintaxis de línea de comandos y 1 para el resto de errores, y 0 es éxito. argparse ya sale con el estado 2 ante argumentos inválidos. Adoptar códigos adicionales de sysexits.h (EX_USAGE 64, EX_NOINPUT 66, EX_UNAVAILABLE 69, EX_TEMPFAIL 75) solo si --help los documenta.
4. Escribir los resultados en stdout y los diagnósticos en stderr. Ofrecer --json cuando otros programas consuman la salida, y --verbose/--quiet que ajusten el nivel de logging en lugar de sembrar print por el código.
5. Capturar en main los fallos esperados (FileNotFoundError, errores de conexión, excepciones de dominio), imprimir una línea en stderr y devolver el código documentado; dejar que las excepciones inesperadas se propaguen para que se conserven el traceback y el código de salida 1.
6. Gestionar KeyboardInterrupt limpiando y devolviendo 130, en línea con la convención del shell de 128 más el número de señal, y silenciar BrokenPipeError en stdout para que tool | head termine sin ruido.
7. Mantener la ayuda honesta: metavar para marcadores de posición legibles, ArgumentDefaultsHelpFormatter para que aparezcan los valores por defecto, y una prueba de que --help sale con 0.

Resultado esperado

tool --help documenta toda la interfaz; tool --bad; echo $? imprime 2; un problema de entrada imprime una línea en stderr y un código documentado; quien llama puede bifurcar según el código sin analizar texto.

Límites y base de verificación

La documentación de sys.exit señala que la mayoría de los sistemas exigen códigos de salida en el rango de 0 a 127; los valores superiores chocan con la codificación de señales del shell. exit_on_error=False hace que el parser lance ArgumentError en lugar de salir, lo cual conviene para incrustarlo pero necesita su propio manejo de errores. Las convenciones siguen la documentación citada; no se afirma ninguna medición de usabilidad.

Salir después de Ctrl-C

Un shell decide si una interrupción también debe detener el script que la contiene comprobando si el proceso hijo murió por SIGINT, no leyendo el código de salida. Una herramienta que captura KeyboardInterrupt y devuelve 130 parece entonces una salida normal, y for f in *; do tool "$f"; done continúa con el siguiente archivo después de cada Ctrl-C. Hacer la limpieza y luego terminar el proceso como lo haría una interrupción no gestionada (Python lo hace así por sí mismo desde la 3.8):

except KeyboardInterrupt:
    cleanup()
    signal.signal(signal.SIGINT, signal.SIG_DFL)
    os.kill(os.getpid(), signal.SIGINT)

$? sigue leyendo 130, y un proceso padre que espera al hijo ve una muerte por señal. Reservar return 130 para quienes llaman y de quienes se sabe que solo leen códigos.