Curso de Python / Crear herramientas de línea de comandos con argparse

argparse define los parámetros de una herramienta de línea de comandos y genera ayuda y errores de uso. Separa la interpretación de argumentos de los cálculos para poder reutilizar y probar el comportamiento sin depender de una terminal concreta.

Distinguir argumentos posicionales y opciones

Los argumentos posicionales se identifican por su orden. Una opción como --currency tiene nombre. nargs="+" exige uno o más valores; type selecciona una función de conversión y choices limita las alternativas aceptadas.

Cuando una ruta contiene espacios, rodéala con comillas para que el intérprete de comandos la entregue como un único argumento. Evita pasar contraseñas y tokens por esta interfaz: pueden aparecer en el historial o en la lista de procesos. Necesitan un mecanismo de entrada o gestión de secretos apropiado.

Construir un comando completo de suma

Guarda el programa como sum_cli.py y ejecuta python sum_cli.py 3500 8000 2500 en el entorno del proyecto. No necesita paquetes externos.

import argparse

def nonnegative(text):
    try:
        value = int(text)
    except ValueError as error:
        raise argparse.ArgumentTypeError("expected an integer") from error
    if value < 0:
        raise argparse.ArgumentTypeError("expected a nonnegative amount")
    return value

def main():
    parser = argparse.ArgumentParser(description="Sum expense amounts")
    parser.add_argument("amounts", type=nonnegative, nargs="+")
    parser.add_argument("--currency", choices=["KRW", "USD"], default="KRW", help="Output unit label; no currency conversion")
    args = parser.parse_args()
    print(f"{sum(args.amounts):,} {args.currency}")

if __name__ == "__main__":
    main()

14,000 KRW

La función nonnegative convierte el texto a entero y rechaza valores negativos con ArgumentTypeError. Esa excepción permite a argparse presentar el problema como un error de argumento. El cálculo recibe los valores ya convertidos, sin interpretar directamente sys.argv.

Inspeccionar ayuda, validación y estado de salida

python sum_cli.py --help
python sum_cli.py 0 500 --currency KRW

El primer comando muestra la ayuda aunque no se proporcionen importes. El segundo devuelve 500 KRW. Una moneda EUR falla la comprobación de alternativas; un importe negativo o no numérico falla su conversión. Los errores de uso ordinarios de argparse terminan con código dos.

Consulta el estado inmediatamente después de ejecutar: $LASTEXITCODE en PowerShell o echo $? en un intérprete habitual de macOS o Ubuntu. Una automatización puede utilizarlo para distinguir un resultado correcto de una invocación inválida. La presentación de la ayuda puede variar entre versiones, por lo que interesa verificar sus opciones y significado.

--currency elige únicamente una etiqueta. Mostrar 14,000 USD no convierte 14000 KRW a dólares. Los números de entrada deben estar ya expresados en la unidad seleccionada. Una conversión real necesitaría otra regla, una fuente de tipos de cambio y una política de redondeo.

Ampliar la interfaz conservando responsabilidades

Para varias operaciones puedes utilizar subcomandos como init, add y list. Pasa los valores necesarios a funciones con parámetros y retorno en lugar de hacer que todo el cálculo dependa de un objeto Namespace.

1. Comprueba que cero está permitido.
2. Prueba un importe negativo, la ausencia de argumentos y una moneda inválida.
3. Inspecciona los estados de salida y restaura una invocación correcta.

El gestor de gastos combina subcomandos y persistencia manteniendo un contrato explícito. La referencia de argparse explica las opciones del analizador y la organización de interfaces más amplias.