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 hace las veces de documentación, códigos de salida estructurados y flujos limpios.

Requisitos previos

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

Pasos

1. Escribe def main(argv: list[str] | None = None) -> int que construya el parser, parsee argv (recurriendo a sys.argv[1:] si no se proporciona) y devuelva un código de salida. Regístrala como [project.scripts] tool = "pkg.cli:main" y añade if __name__ == "__main__": sys.exit(main()). Las pruebas pueden entonces llamar a main(["--flag", "x"]) y comprobar el valor devuelto y la salida capturada.
2. Construye el parser con prog, description y un epilog con ejemplos. Usa 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 subcomandos.
3. Sigue la convención que describe la documentación de sys.exit: los programas Unix suelen usar 2 para errores de sintaxis de línea de comandos y 1 para cualquier otro error, siendo 0 el éxito. argparse ya termina con el estado 2 ante argumentos inválidos. Adopta códigos adicionales de sysexits.h (EX_USAGE 64, EX_NOINPUT 66, EX_UNAVAILABLE 69, EX_TEMPFAIL 75) solo si --help los documenta.
4. Escribe los resultados en stdout y los diagnósticos en stderr. Ofrece --json cuando otros programas consuman la salida, y --verbose/--quiet que ajusten el nivel de logging en lugar de esparcir llamadas a print.
5. Captura en main los fallos esperados (FileNotFoundError, errores de conexión, excepciones del dominio), imprime una línea en stderr y devuelve el código documentado; deja que las excepciones inesperadas se propaguen para que se conserven el traceback y el código de salida 1.
6. Gestiona KeyboardInterrupt limpiando y devolviendo 130, de acuerdo con la convención de shell de 128 más el número de señal, y absorbe BrokenPipeError en stdout para que tool | head termine sin ruido.
7. Mantén la ayuda honesta: metavar para marcadores de posición legibles, ArgumentDefaultsHelpFormatter para que aparezcan los valores por defecto, y una prueba que compruebe que --help termina 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 invoque la herramienta puede ramificar según el código sin necesidad de 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 por encima chocan con la codificación de señales de la shell. exit_on_error=False hace que el parser lance ArgumentError en lugar de terminar el proceso, lo cual conviene si se está embebiendo, pero necesita su propio manejo de errores. Las convenciones siguen la documentación citada; no se afirma ninguna medición de usabilidad.

Terminar el proceso después de Ctrl-C

Una shell decide si una interrupción también debe detener el script que la envuelve comprobando si el hijo murió por SIGINT, no leyendo el código de salida. Por eso, una herramienta que captura KeyboardInterrupt y devuelve 130 parece una salida normal, y for f in *; do tool "$f"; done continúa con el siguiente archivo después de cada Ctrl-C. Haz la limpieza y después termina el proceso de la misma manera en que lo haría una interrupción no gestionada (Python lo hace así por sí mismo desde la versión 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 (wait) sobre el proceso ve una muerte por señal. Reserva return 130 para los casos en los que se sabe que quien invoca solo lee códigos.