argparse

argparse es el analizador de CLI de la biblioteca estándar de Python. Genera --help, valida tipos y admite subcomandos sin dependencias de terceros.

Receta

import argparse
 
def main():
    parser = argparse.ArgumentParser(prog="invoice", description="Administrar facturas")
    parser.add_argument("--format", choices=["json", "csv"], default="json")
    parser.add_argument("id", type=int, nargs="?", help="ID de factura")
    args = parser.parse_args()
    print(args)
 
if __name__ == "__main__":
    main()

Cuándo usar esto:

• CLI sin dependencias externas
• Scripts que necesitan --help y validación de tipos
• Herramientas donde solo la biblioteca estándar es un requisito

Ejemplo funcional

import argparse
import sys
 
def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="deploy",
        description="Desplegar aplicación a entornos",
    )
    parser.add_argument("--verbose", "-v", action="count", default=0)
    sub = parser.add_subparsers(dest="env", required=True)
 
    for name in ("staging", "production"):
        p = sub.add_parser(name, help=f"Desplegar a {name}")
        p.add_argument("--dry-run", action="store_true")
        p.add_argument("--tag", required=True, help="Etiqueta de imagen Docker")
    return parser
 
def main(argv: list[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    if args.verbose:
        print(f"Desplegando {args.tag} a {args.env}", file=sys.stderr)
    if args.dry_run:
        print("Ejecución de prueba - no se realizaron cambios")
        return 0
    # lógica de despliegue aquí
    return 0
 
if __name__ == "__main__":
    raise SystemExit(main())

Lo que esto demuestra:

• Subanalizadores para deploy staging / deploy production
• action="count" para verbosidad -v, -vv
• parse_args(argv) permite probar sin subprocesos
• raise SystemExit(main()) para códigos de salida correctos

Inmersión profunda

Argumentos comunes

Trampas

• Olvidar required=True en subanalizadores - no se ejecuta ningún comando. Solución: required=True (Python 3.7+).
• No se puede probar - solo parse_args() sin argv. Solución: pasar la lista argv en las pruebas.
• Texto de ayuda como ocurrencia tardía - los usuarios se confunden. Solución: help= en cada argumento.
• Imprimir secretos en los valores predeterminados de argparse - visibles en --help. Solución: cargar secretos desde el entorno en tiempo de ejecución.
• argparse para comandos anidados complejos - verboso. Solución: considerar Click o Typer con 5 o más subcomandos.

Alternativas

Preguntas frecuentes

Relacionado

• Fundamentos de la CLI - Fundamentos de la CLI
• Click - alternativa de decorador
• Configuración y Entorno - capas de configuración
• Mejores prácticas de CLI - reglas de diseño

Versiones de la pila: Esta página fue escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.