Una herramienta de línea de comandos no solo debe ejecutar acciones correctamente; también debe ayudar al usuario cuando algo sale mal. Un error de escritura pequeño puede convertir una tarea sencilla en una búsqueda innecesaria por la documentación. La opción suggest_on_error de argparse mejora esa experiencia porque puede sugerir una alternativa válida cuando el usuario escribe una opción textual incorrecta. En esta guía aprenderás a usarla, mantener compatibilidad entre versiones y combinarla con validaciones seguras.
Qué hace suggest_on_error
argparse es el módulo estándar de Python para interpretar argumentos de línea de comandos. Cuando una entrada no pertenece a las opciones permitidas, el parser muestra un error. Al activar suggest_on_error=True, también puede comparar el texto incorrecto con las opciones conocidas y presentar una coincidencia cercana.
import argparse
parser = argparse.ArgumentParser(suggest_on_error=True)
parser.add_argument("action", choices=["start", "stop", "restart"])
args = parser.parse_args()
print(args.action)
Si el usuario escribe restar, la salida puede sugerir restart. El parser sigue rechazando la entrada original; no la corrige ni la ejecuta automáticamente. Esa distinción mantiene el comportamiento predecible.
Por qué importan los errores claros
Las CLI se utilizan en servidores, automatizaciones, pipelines, tareas programadas y entornos sin interfaz gráfica. En esos contextos, el mensaje de error forma parte de la experiencia del producto. Una sugerencia útil reduce repeticiones, consultas al manual y solicitudes de soporte.
Este principio se relaciona con otras prácticas de diseño en Python. Puedes consultar contextlib.ExitStack en Python para administrar recursos dinámicos, typing.override en Python para contratos de herencia, string.Template en Python para mensajes configurables y TopologicalSorter en Python para flujos con dependencias.
Compatibilidad entre versiones
suggest_on_error es una incorporación reciente. Si pasas el argumento directamente en una versión anterior de Python, puedes recibir un TypeError. En aplicaciones donde controlas el entorno, basta con declarar la versión mínima requerida. En bibliotecas o herramientas distribuidas, conviene detectar la capacidad.
import argparse
parser = argparse.ArgumentParser()
if hasattr(parser, "suggest_on_error"):
parser.suggest_on_error = True
La detección con hasattr verifica la capacidad real del intérprete y evita depender únicamente de comparaciones de versiones. Documenta siempre las versiones soportadas y pruébalas en integración continua.
Uso con choices
El caso más directo utiliza argumentos con choices:
parser = argparse.ArgumentParser(suggest_on_error=True)
parser.add_argument(
"environment",
choices=["development", "staging", "production"]
)
Una entrada como prodution es lo bastante parecida a production para generar una recomendación útil. El mecanismo funciona mejor con cadenas legibles. Números, identificadores opacos y objetos personalizados no suelen beneficiarse de la comparación textual.
Subcomandos y organización
Las herramientas grandes suelen dividirse en subcomandos como deploy, rollback, status y logs. Las sugerencias ayudan con errores pequeños, pero no reparan una arquitectura confusa. Mantén un patrón consistente: usa verbos para acciones, evita abreviaturas inesperadas y agrupa operaciones relacionadas.
parser = argparse.ArgumentParser(suggest_on_error=True)
subparsers = parser.add_subparsers(dest="command", required=True)
subparsers.add_parser("deploy")
subparsers.add_parser("rollback")
subparsers.add_parser("status")
El nombre de cada comando debe ser fácil de anticipar. La sugerencia es una red de seguridad, no un sustituto del diseño.
Ayuda y validación personalizada
Añade textos help claros, una descripción general y ejemplos en el epílogo. Cuando una regla depende del dominio, crea una función de tipo que lance argparse.ArgumentTypeError.
from pathlib import Path
import argparse
def existing_file(value: str) -> Path:
path = Path(value)
if not path.is_file():
raise argparse.ArgumentTypeError(f"Archivo no encontrado: {value}")
return path
parser = argparse.ArgumentParser(suggest_on_error=True)
parser.add_argument("--config", type=existing_file)
En este caso, la sugerencia de texto y la validación del archivo resuelven problemas distintos. Una compara opciones conocidas; la otra comprueba una condición real del sistema.
Cómo probar las sugerencias
Los mensajes de error son parte de la interfaz pública. Con pytest, ejecuta el parser con una entrada inválida, captura SystemExit e inspecciona la salida de error.
import pytest
def test_invalid_choice(parser, capsys):
with pytest.raises(SystemExit):
parser.parse_args(["prodution"])
captured = capsys.readouterr()
assert "production" in captured.err
Evita comprobar toda la frase exacta si necesitas soportar varias versiones, ya que la puntuación o el formato pueden cambiar. Comprueba los elementos esenciales: valor rechazado, alternativa esperada y código de salida.
Seguridad
Nunca ejecutes automáticamente el valor sugerido. Una coincidencia aproximada es una ayuda de usabilidad, no una confirmación de intención. Esto resulta crítico en comandos que eliminan archivos, modifican bases de datos, despliegan infraestructura o realizan operaciones financieras.
Mantén la entrada inválida como inválida. Para acciones sensibles, incorpora confirmación explícita, modo de simulación, registro de auditoría, privilegios mínimos y un resumen previo. La documentación oficial de argparse explica el comportamiento del parser, y la sección Novedades de Python permite verificar la disponibilidad de funciones recientes.
Cuándo activarlo
suggest_on_error aporta más valor en herramientas con muchas opciones textuales, varios subcomandos o usuarios que no conocen de memoria todos los nombres. Es adecuado para utilidades de despliegue, generadores de código, administradores de sistemas, herramientas de datos y comandos internos de equipos.
El beneficio es menor cuando la mayoría de las entradas son números, rutas, UUID, fechas o texto libre. Esos datos necesitan validadores, ejemplos y mensajes específicos.
Errores de diseño comunes
No crees demasiadas opciones casi idénticas, porque las sugerencias pueden volverse ambiguas. No uses la función como sustituto de la documentación. No ocultes la versión mínima de Python. Tampoco mezcles el parsing con la lógica principal: interpreta y valida en el borde de la aplicación, y pasa valores limpios a funciones fáciles de probar.
Lista práctica
Elige nombres coherentes, declara choices cuando el dominio sea cerrado, activa sugerencias en versiones compatibles, añade una ruta de compatibilidad si es necesaria, escribe ayuda útil, valida reglas del dominio por separado y prueba entradas incorrectas. En operaciones destructivas, exige siempre una confirmación explícita.
Conclusión
argparse suggest_on_error es una mejora pequeña con impacto real. Permite que el usuario se recupere de errores de escritura sin relajar la validación. Combinada con nombres consistentes, documentación clara, pruebas y controles de seguridad, ayuda a construir interfaces de línea de comandos más profesionales, accesibles y confiables.
