Cómo crear una herramienta de línea de comandos en Python con argparse

·

Un script deja de ser cómodo cuando necesitas abrirlo cada vez que quieres cambiar una ruta, activar una opción o seleccionar la operación que debe ejecutar. Una interfaz de línea de comandos evita ese problema: los datos variables llegan desde la terminal y el código conserva la lógica que quieres reutilizar.

Vamos a crear una utilidad llamada archivo_cli.py con dos subcomandos: uno para analizar los archivos de un directorio y otro para clasificar un archivo según su extensión. La estructura puede adaptarse después a conversores, copias de seguridad, organizadores de archivos o herramientas de administración.

La solución utiliza argparse para interpretar la línea de comandos y pathlib para representar rutas. Ambos módulos pertenecen a la biblioteca estándar. La documentación oficial de argparse explica que ArgumentParser reúne las especificaciones de los argumentos, genera ayuda y detecta invocaciones no válidas. Por su parte, pathlib ofrece objetos para trabajar con rutas de acuerdo con el sistema donde se ejecuta el programa.

Diseñar el comando antes de programarlo

Antes de llamar a add_argument(), conviene definir el contrato de la herramienta: qué operaciones ofrece, qué datos son imprescindibles, qué opciones modifican el comportamiento y qué resultado produce.

python archivo_cli.py analizar ./documentos
python archivo_cli.py analizar ./documentos --recursive
python archivo_cli.py analizar ./documentos --extension pdf --json
python archivo_cli.py clasificar ./documentos/informe.pdf
  • Programa: archivo_cli.py.
  • Subcomando: analizar o clasificar.
  • Argumento posicional: la ruta necesaria para ejecutar la operación.
  • Opciones: --recursive, --extension y --json.

Qué elemento utilizar en cada caso

NecesidadElementoEjemploConsecuencia
Dato imprescindible y fácil de identificarArgumento posicionalanalizar DIRECTORIOLa orden es corta, pero la posición importa.
Valor opcional o configurableOpción con valor--extension pdfEl nombre explica qué representa el valor.
Activar un comportamientoFlag--recursiveNo necesita recibir un texto adicional.
Elegir entre operaciones diferentesSubcomandoanalizar o clasificarCada operación dispone de sus propios argumentos.

No conviene convertir todos los datos en posiciones. Una orden como programa carpeta pdf true obliga a recordar qué significa cada valor. programa analizar carpeta --extension pdf --recursive es más larga, pero también más comprensible.

Herramienta completa con argparse y pathlib

Crea un archivo llamado archivo_cli.py con este contenido:

import argparse
import json
import sys
from collections import Counter
from pathlib import Path

CATEGORIES = {
    ".jpg": "imagenes",
    ".jpeg": "imagenes",
    ".png": "imagenes",
    ".gif": "imagenes",
    ".pdf": "documentos",
    ".txt": "documentos",
    ".docx": "documentos",
    ".xlsx": "documentos",
    ".csv": "datos",
    ".json": "datos",
    ".py": "codigo",
    ".js": "codigo",
    ".html": "codigo",
    ".css": "codigo",
    ".zip": "comprimidos",
    ".tar": "comprimidos",
    ".gz": "comprimidos",
}


def checked_path(value: str, expected: str) -> Path:
    path = Path(value).expanduser()

    try:
        if not path.exists():
            raise argparse.ArgumentTypeError(
                f"la ruta no existe: {path}"
            )
        if expected == "file" and not path.is_file():
            raise argparse.ArgumentTypeError(
                f"la ruta no es un archivo: {path}"
            )
        if expected == "directory" and not path.is_dir():
            raise argparse.ArgumentTypeError(
                f"la ruta no es un directorio: {path}"
            )
    except OSError as error:
        raise argparse.ArgumentTypeError(
            f"no se puede consultar la ruta {path}: {error}"
        ) from error

    return path


def existing_file(value: str) -> Path:
    return checked_path(value, "file")


def existing_directory(value: str) -> Path:
    return checked_path(value, "directory")


def extension_value(value: str) -> str:
    cleaned = value.strip().lower()
    if not cleaned:
        raise argparse.ArgumentTypeError(
            "la extensión no puede estar vacía"
        )
    return cleaned if cleaned.startswith(".") else f".{cleaned}"


def classify(path: Path) -> str:
    suffix = path.suffix.lower()
    if not suffix:
        return "sin_extension"
    return CATEGORIES.get(suffix, "otros")


def iter_files(directory: Path, recursive: bool):
    candidates = directory.rglob("*") if recursive else directory.iterdir()
    for candidate in candidates:
        if candidate.is_file():
            yield candidate


def run_classify(args: argparse.Namespace) -> int:
    result = {
        "archivo": str(args.file),
        "extension": args.file.suffix.lower() or None,
        "categoria": classify(args.file),
    }

    if args.json:
        print(json.dumps(result, ensure_ascii=False, indent=2))
    else:
        print(f"Archivo: {result['archivo']}")
        print(f"Extensión: {result['extension'] or 'ninguna'}")
        print(f"Categoría: {result['categoria']}")

    return 0


def run_analyze(args: argparse.Namespace) -> int:
    files = []

    for path in iter_files(args.directory, args.recursive):
        if args.extension and path.suffix.lower() != args.extension:
            continue
        files.append(path)

    extension_counts = Counter(
        path.suffix.lower() or "sin_extension" for path in files
    )
    category_counts = Counter(classify(path) for path in files)
    total_bytes = sum(path.stat().st_size for path in files)

    result = {
        "directorio": str(args.directory),
        "recursivo": args.recursive,
        "filtro_extension": args.extension,
        "numero_archivos": len(files),
        "tamano_total_bytes": total_bytes,
        "por_extension": dict(sorted(extension_counts.items())),
        "por_categoria": dict(sorted(category_counts.items())),
    }

    if args.json:
        print(json.dumps(result, ensure_ascii=False, indent=2))
    else:
        print(f"Directorio: {result['directorio']}")
        print(f"Archivos encontrados: {result['numero_archivos']}")
        print(f"Tamaño total: {result['tamano_total_bytes']} bytes")
        print("Categorías:")
        for category, amount in result["por_categoria"].items():
            print(f"  {category}: {amount}")

    return 0


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="archivo_cli.py",
        description=(
            "Analiza un directorio o clasifica un archivo "
            "según su extensión."
        ),
    )

    subparsers = parser.add_subparsers(
        dest="command",
        required=True,
        metavar="COMANDO",
    )

    analyze_parser = subparsers.add_parser(
        "analizar",
        help="resume los archivos de un directorio",
        description="Cuenta y agrupa los archivos de un directorio.",
    )
    analyze_parser.add_argument(
        "directory",
        metavar="DIRECTORIO",
        type=existing_directory,
        help="directorio que se quiere analizar",
    )
    analyze_parser.add_argument(
        "-r", "--recursive",
        action="store_true",
        help="incluye el contenido de los subdirectorios",
    )
    analyze_parser.add_argument(
        "-e", "--extension",
        type=extension_value,
        help="limita el análisis a una extensión, por ejemplo pdf",
    )
    analyze_parser.add_argument(
        "--json",
        action="store_true",
        help="devuelve el resultado en formato JSON",
    )
    analyze_parser.set_defaults(handler=run_analyze)

    classify_parser = subparsers.add_parser(
        "clasificar",
        help="clasifica un archivo según su extensión",
        description="Asigna una categoría orientativa a un archivo.",
    )
    classify_parser.add_argument(
        "file",
        metavar="ARCHIVO",
        type=existing_file,
        help="archivo que se quiere clasificar",
    )
    classify_parser.add_argument(
        "--json",
        action="store_true",
        help="devuelve el resultado en formato JSON",
    )
    classify_parser.set_defaults(handler=run_classify)

    return parser


def main(argv=None) -> int:
    parser = build_parser()

    try:
        args = parser.parse_args(argv)
    except SystemExit as error:
        return int(error.code)

    try:
        return args.handler(args)
    except PermissionError as error:
        print(f"Error de permisos: {error}", file=sys.stderr)
        return 3
    except OSError as error:
        print(f"Error del sistema de archivos: {error}", file=sys.stderr)
        return 4


if __name__ == "__main__":
    raise SystemExit(main())

El ejemplo solo consulta información. No mueve, renombra ni elimina archivos. clasificar utiliza la extensión para devolver una categoría orientativa, por lo que no identifica el contenido real del fichero.

Cómo funcionan ArgumentParser y add_argument

build_parser() concentra la definición de la interfaz. El objeto ArgumentParser recibe el nombre mostrado en la ayuda y una descripción general. Cada llamada a add_argument() añade una especificación. La referencia oficial de add_argument() documenta propiedades como type, action, choices, default, help y metavar.

Argumentos posicionales

directory y file no empiezan por guiones, así que son argumentos posicionales. El usuario debe proporcionarlos en el lugar previsto. Si faltan, el parser muestra el uso esperado y no ejecuta la operación.

python archivo_cli.py analizar
python archivo_cli.py clasificar

Opciones que reciben valores

--extension necesita un dato adicional. La función extension_value() transforma tanto pdf como .PDF en .pdf, de modo que la operación principal recibe un valor normalizado.

python archivo_cli.py analizar ./documentos --extension pdf

Flags con action="store_true"

--recursive y --json funcionan como interruptores. Cuando aparecen, su valor es verdadero; cuando se omiten, es falso. No deben escribirse como --recursive true.

python archivo_cli.py analizar ./documentos --recursive --json

Separar operaciones mediante subcomandos

Cuando una utilidad realiza acciones distintas, acumular flags produce combinaciones difíciles de entender. Los subcomandos permiten que cada operación tenga su propia ayuda y sus propios argumentos:

  • analizar exige un directorio y admite recursividad, filtro de extensión y salida JSON.
  • clasificar exige un archivo y admite salida JSON.

add_subparsers() crea el espacio para los comandos y cada llamada a add_parser() define uno. Con set_defaults(handler=...), cada subcomando queda asociado a su función. main() puede ejecutar args.handler(args) sin mantener una cadena creciente de condicionales.

Validar archivos y directorios con pathlib

Utilizar únicamente type=Path convertiría el texto en una ruta, pero no comprobaría que existe ni que representa el elemento esperado. Por eso el ejemplo utiliza existing_file() y existing_directory().

  1. Se construye un objeto Path.
  2. Se expande una posible referencia al directorio personal.
  3. Se comprueba la existencia de la ruta.
  4. Se distingue entre archivo y directorio con is_file() e is_dir().
  5. Un fallo al consultar la ruta se convierte en ArgumentTypeError.

La documentación de consulta de tipo y estado de pathlib recoge estas operaciones. Si la validación falla, el problema se presenta como un error del argumento en lugar de dejar que aparezca un traceback.

Esta comprobación inicial tiene un límite: no garantiza que el elemento continúe accesible durante toda la ejecución. Otro proceso podría borrar un archivo, modificar sus permisos o desconectar la unidad después de validarlo. Por eso main() también trata errores que se produzcan durante el recorrido o al consultar el tamaño de los archivos.

Crear mensajes de ayuda útiles

Una herramienta reutilizable debe explicar su uso sin obligar a consultar el código:

python archivo_cli.py --help
python archivo_cli.py analizar --help
python archivo_cli.py clasificar --help

La primera orden muestra los subcomandos disponibles. Las otras dos presentan los argumentos de la operación elegida. Los campos más importantes son:

  • description, para explicar el propósito del programa o subcomando.
  • help, para resumir cada argumento.
  • metavar, para mostrar etiquetas comprensibles como DIRECTORIO.
  • prog, para controlar el nombre que aparece en la línea de uso.

En este caso, prog="archivo_cli.py" coincide con la forma de invocación utilizada en la guía. Si más adelante empaquetas el proyecto como un comando instalable, podrás cambiarlo por el nombre definitivo del ejecutable.

Separar la interfaz de la lógica

La herramienta reparte sus responsabilidades entre funciones pequeñas:

  • build_parser() define la interfaz.
  • checked_path() y extension_value() validan entradas.
  • classify() contiene la regla de clasificación.
  • iter_files() localiza los archivos.
  • run_analyze() y run_classify() ejecutan los casos de uso.
  • main() coordina la ejecución y traduce fallos en estados de salida.

Esta separación permite probar classify(Path("foto.jpg")) sin simular una terminal. El parser queda como una capa de entrada y la lógica puede reutilizarse desde otros módulos.

Mensajes de error y códigos de salida

Un mensaje explica el problema a una persona. Un código de salida permite que otro programa decida qué hacer. La implementación propone este contrato:

CódigoSignificado en esta herramientaCaso
0La operación terminó correctamente o se mostró la ayuda solicitada.Analizar un directorio accesible.
2El parser rechazó la invocación.Omitir una ruta o proporcionar una ruta inválida.
3Se produjo un problema de permisos durante la operación.Perder acceso mientras se recorre un directorio.
4Apareció otro error del sistema de archivos durante la operación.La unidad deja de estar disponible durante el análisis.

Los códigos 3 y 4 son decisiones propias de esta utilidad, no categorías universales. Si otro script empieza a depender de ellos, deberán documentarse y conservar su significado.

El bloque que captura SystemExit conserva el código generado por el parser. Cuando se ejecuta el archivo directamente, raise SystemExit(main()) entrega el valor final al sistema operativo.

En Bash y terminales habituales de Linux o macOS:

python archivo_cli.py analizar ./documentos
echo $?

En PowerShell:

python archivo_cli.py analizar .\documentos
$LASTEXITCODE

Salida para personas y salida para scripts

El formato predeterminado está pensado para leerse en la terminal. La opción --json devuelve una representación estructurada que otro programa puede procesar:

python archivo_cli.py analizar ./documentos --recursive --json
python archivo_cli.py analizar ./documentos --json > informe.json

La salida JSON debe mantenerse limpia. Si el programa imprime antes mensajes como “Procesando archivos”, el resultado deja de poder analizarse directamente. Los avisos y errores pueden enviarse a la salida de error con file=sys.stderr.

Incorporar JSON también crea un contrato. Cambiar claves como numero_archivos o modificar sus tipos podría romper scripts que consuman el resultado.

Pruebas manuales paso a paso

Prepara una carpeta con esta estructura:

prueba_cli/
├── README
├── datos.csv
├── foto.jpg
├── informe.pdf
├── notas.txt
└── subcarpeta/
    └── programa.py
  1. Ejecuta python archivo_cli.py --help y comprueba que aparecen los dos subcomandos.
  2. Consulta python archivo_cli.py analizar --help y revisa las opciones disponibles.
  3. Analiza prueba_cli sin recursividad. programa.py no debería aparecer en el recuento.
  4. Repite la orden con --recursive y comprueba que se incluye el archivo de la subcarpeta.
  5. Utiliza --extension pdf y verifica que el filtro solo contabiliza el PDF.
  6. Ejecuta python archivo_cli.py clasificar prueba_cli/README para comprobar el caso sin extensión.
  7. Solicita JSON y comprueba que puede guardarse en un archivo.
  8. Proporciona una ruta inexistente y consulta el código de salida.
  9. Entrega un archivo a analizar y un directorio a clasificar.
  10. Compara el estado de una ejecución correcta con el de una invocación inválida.

Si trabajas en Windows, puedes aislar el proyecto siguiendo la guía para crear un entorno virtual de Python en Windows. La utilidad no necesita paquetes externos, pero el entorno resulta útil si posteriormente añades herramientas de pruebas o empaquetado.

Automatizar las comprobaciones con unittest

Crea test_archivo_cli.py junto al programa:

import io
import json
import tempfile
import unittest
from contextlib import redirect_stderr, redirect_stdout
from pathlib import Path

from archivo_cli import classify, main


class ArchivoCliTests(unittest.TestCase):
    def test_classify_known_extension(self):
        self.assertEqual(classify(Path("foto.JPG")), "imagenes")

    def test_classify_without_extension(self):
        self.assertEqual(classify(Path("README")), "sin_extension")

    def test_classify_command_returns_json(self):
        with tempfile.TemporaryDirectory() as directory:
            file = Path(directory) / "informe.pdf"
            file.write_text("contenido", encoding="utf-8")

            output = io.StringIO()
            with redirect_stdout(output):
                code = main(["clasificar", str(file), "--json"])

            result = json.loads(output.getvalue())
            self.assertEqual(code, 0)
            self.assertEqual(result["categoria"], "documentos")

    def test_analyze_filters_extension(self):
        with tempfile.TemporaryDirectory() as directory:
            root = Path(directory)
            (root / "uno.txt").write_text("a", encoding="utf-8")
            (root / "dos.pdf").write_text("bb", encoding="utf-8")

            output = io.StringIO()
            with redirect_stdout(output):
                code = main([
                    "analizar",
                    str(root),
                    "--extension",
                    "pdf",
                    "--json",
                ])

            result = json.loads(output.getvalue())
            self.assertEqual(code, 0)
            self.assertEqual(result["numero_archivos"], 1)

    def test_missing_path_returns_usage_error(self):
        error_output = io.StringIO()
        with redirect_stderr(error_output):
            code = main(["clasificar", "archivo-inexistente.txt"])

        self.assertEqual(code, 2)
        self.assertIn("la ruta no existe", error_output.getvalue())


if __name__ == "__main__":
    unittest.main()

Ejecuta las pruebas con:

python -m unittest -v

TemporaryDirectory proporciona un espacio aislado para cada prueba. Además, cargar la salida con json.loads() comprueba que el resultado tiene formato JSON válido. La prueba de la ruta inexistente captura stderr para evitar ensuciar la salida de la suite y verificar el mensaje esperado.

Estas pruebas se ofrecen como un procedimiento reproducible, pero el resultado debe comprobarse en la versión y el entorno concretos donde vaya a utilizarse la herramienta.

También puedes comprobar el contrato desde Bash:

#!/usr/bin/env bash

set -u

tmp_dir="$(mktemp -d)"
trap 'rm -rf "$tmp_dir"' EXIT

printf 'ejemplo' > "$tmp_dir/informe.pdf"

python archivo_cli.py clasificar "$tmp_dir/informe.pdf" --json
if [ $? -ne 0 ]; then
    echo "La clasificación válida ha fallado" >&2
    exit 1
fi

python archivo_cli.py clasificar "$tmp_dir/no-existe.pdf"
if [ $? -ne 2 ]; then
    echo "Se esperaba el código 2 para una ruta inválida" >&2
    exit 1
fi

echo "Comprobaciones completadas"

Para practicar previamente operaciones con archivos desde la terminal, está disponible este laboratorio de Bash sobre archivos, búsquedas e informes.

Errores frecuentes al crear una CLI

Leer sys.argv en toda la aplicación

Acceder directamente a posiciones de sys.argv obliga a implementar conversiones, ayuda, opciones y mensajes de error. También acopla la lógica a la terminal. Es preferible que el parser entregue datos ya convertidos a funciones normales.

Confundir conversión con validación completa

Convertir un texto en Path no demuestra que la ruta exista, sea del tipo correcto o continúe accesible durante la operación. Las comprobaciones iniciales y el tratamiento de errores de acceso resuelven momentos diferentes.

Mezclar mensajes informativos con JSON

Si --json imprime primero una frase informativa y después un objeto, la salida deja de ser directamente procesable. Reserva stdout para el resultado estructurado y utiliza stderr para avisos y errores.

Añadir operaciones destructivas sin protección

Si amplías la herramienta para mover o borrar archivos, comienza con un modo de simulación que muestre el plan sin modificar nada. Después puedes exigir una confirmación explícita. Que una orden tenga una sintaxis válida no significa que su efecto sea seguro o deseado.

Cómo evolucionar la herramienta

  • Añade subcomandos cuando aparezcan operaciones claramente diferentes.
  • Mantén los nombres de las opciones si otros scripts pueden depender de ellos.
  • No cambies silenciosamente el significado de los códigos de salida.
  • Conserva las claves JSON o introduce una estrategia de versiones.
  • Añade una prueba para cada opción nueva y para sus errores previsibles.
  • Empaqueta el proyecto con un punto de entrada de consola cuando quieras invocarlo sin escribir python archivo_cli.py.

Si necesitas ejecutar la utilidad periódicamente en Windows, puedes combinarla con esta guía para programar tareas automáticas en Windows. Configura expresamente el intérprete, el script, los argumentos y el directorio de trabajo.

Checklist final para crear una CLI con argparse

  1. Define las operaciones y el resultado de cada una.
  2. Decide qué datos serán posicionales, opciones o flags.
  3. Utiliza subcomandos para acciones diferentes.
  4. Convierte y valida las entradas con funciones pequeñas.
  5. Representa archivos y directorios mediante Path.
  6. Separa la definición del parser de la lógica principal.
  7. Escribe ayudas que permitan usar el comando sin leer el código.
  8. Documenta los códigos de salida propios.
  9. Mantén limpia cualquier salida estructurada.
  10. Prueba casos correctos, límites, rutas inválidas y errores de acceso.

Esta estructura permite crear una herramienta de línea de comandos en Python con argparse sin convertir el programa en una colección de condicionales alrededor de sys.argv. El resultado es una interfaz comprensible para quien la ejecuta y una base que puede automatizarse, probarse y ampliar sin mezclar todas las responsabilidades.

Preguntas frecuentes

¿argparse necesita instalarse con pip?

No. argparse forma parte de la biblioteca estándar de Python. El ejemplo tampoco requiere dependencias externas.

¿Cuándo debo usar un argumento posicional?

Cuando el dato sea imprescindible, único y fácil de identificar por su posición. Si es opcional o modifica el comportamiento, suele encajar mejor como opción con nombre.

¿Para qué sirven los subcomandos?

Separan operaciones diferentes dentro de una utilidad. Cada subcomando puede tener sus propios argumentos, ayuda y función de ejecución.

¿Basta con comprobar que una ruta existe?

No. También hay que distinguir entre archivo y directorio y tratar los errores que puedan aparecer durante el acceso real.

¿Por qué devolver JSON además de texto?

El texto está pensado para una persona. JSON permite que otros programas consuman el resultado sin tener que interpretar frases.

¿Cómo se convierte el script en un comando instalable?

El proyecto puede empaquetarse y declarar un punto de entrada de consola. Conviene mantener una función main() que devuelva un entero y conservar la lógica separada del parser.

J_, marca de Julian Lopez Jimenez

Hola, encantado de conocerte.

Recibe cada domingo las 3 últimas entradas sobre informática práctica.

Sin spam. Puedes darte de baja cuando quieras. Recibirás un correo para confirmar el alta. Consulta la Política de privacidad.

Recibe nuevas entradas cada semana

Una seleccion de articulos, recursos y novedades sobre informatica, FP y tecnologia aplicada.

J_, marca de Julian Lopez Jimenez

Hola, encantado de conocerte.

Recibe cada domingo las 3 últimas entradas sobre informática práctica.

Sin spam. Puedes darte de baja cuando quieras. Recibirás un correo para confirmar el alta. Consulta la Política de privacidad.

Tambien te puede interesar