¡Para principiantes! Cómo manejar argumentos de línea de comandos con el módulo sys de Python

Para ejecutar Python desde el símbolo del sistema o PowerShell en tu PC, necesitas descargar e instalar Python.
Si aún no lo has hecho, consulta el artículo Instalación de Python y configuración del entorno de desarrollo para instalar Python.

"Esa pantalla negra (la terminal) parece un poco intimidante..." "Entiendo que es cosa de programadores, pero ¿es relevante para mí?"

¡Hola! Hace solo unos meses, era un completo novato sin ningún conocimiento de programación, pensando exactamente lo mismo que tú. Con la ayuda de la IA, logré lanzar dos sitios web por mi cuenta (buyonjapan.com, copicode.com).

En este sitio, comparto los puntos en los que realmente me quedé atascado y los momentos de "¡así es como funcionó!", todo desde la perspectiva de un compañero principiante.

Esta vez, cubriremos cómo procesar argumentos de línea de comandos usando `sys.argv` de Python. Una vez que puedas usar esto, podrás cambiar el comportamiento de tu programa con un solo comando, ¡como un mago! Puede sonar difícil, ¡pero no te preocupes! Con solo copiar y pegar el código de este artículo, podrás experimentar esa sensación de "¡Funciona!". ¡Vamos a ello!

Para empezar, ¿qué son los "argumentos de línea de comandos"? 🤔

Antes de entrar en el tema principal, tomemos un pequeño desvío. Muchos de ustedes quizás no estén familiarizados con el término "argumentos de línea de comandos".

Normalmente, operamos las computadoras haciendo clic en iconos o presionando botones con el ratón. Esto es la GUI (Interfaz Gráfica de Usuario).

Por otro lado, escribir comandos en una pantalla negra para dar instrucciones es la CUI (Interfaz de Usuario de Caracteres), también conocida como la "línea de comandos".

Y los argumentos de línea de comandos son información adicional que le pasas a un programa cuando lo ejecutas desde la CUI, básicamente diciendo: "¡Oye programa, por favor, usa esta configuración para esta ejecución!". Piensa en ellos como un "conjunto de instrucciones" u "opciones" para tu programa.

¡Usarlos es increíblemente conveniente porque puedes cambiar el comportamiento de un programa en cada ejecución sin tener que reescribir el código cada vez!

El primer paso para recibir argumentos en Python: `sys.argv`

La forma más básica de recibir argumentos de línea de comandos en Python es usando `argv`, que es parte del módulo `sys`.

El módulo `sys` viene de serie con Python (consulta la documentación oficial), así que no necesitas instalar nada extra. ¡Puedes usarlo de inmediato!

Primero, veamos qué forma toman los argumentos de línea de comandos cuando se pasan al programa. Guarda el siguiente código como `show_args.py`.

<!-- show_args.py -->
import sys

print("--- Argumentos pasados al programa ---")
print(sys.argv)
print(f"El tipo de dato es {type(sys.argv)}.")

Una vez guardado, abre tu terminal (o Símbolo del sistema/PowerShell en Windows), navega al directorio donde guardaste el archivo y ejecútalo así:

# Comando para ejecutar en la terminal
python show_args.py primer-arg segundo 333

Deberías ver una salida como esta:

--- Argumentos pasados al programa ---
['show_args.py', 'primer-arg', 'segundo', '333']
El tipo de dato es <class 'list'>.

Viendo el resultado, puedes ver lo que `sys.argv` es en realidad. ¡Exacto, es una lista (list)!

`sys.argv[0]`: Esto es siempre el nombre del archivo de script que ejecutaste (`show_args.py`). Así es como funciona.
`sys.argv[1]` en adelante: Los argumentos (`primer-arg`, `segundo`, `333`) que escribiste después del nombre del script en la terminal, separados por espacios, se almacenan en orden.

Como es una lista, puedes acceder a los argumentos individuales usando sus números de índice, como `sys.argv[1]`, `sys.argv[2]`, y así sucesivamente.

Errores comunes y cómo solucionarlos 🚨

Aunque `sys.argv` es simple y útil, hay dos trampas comunes para los principiantes. ¡Yo mismo caí en ellas! Pero no te preocupes, no dan miedo una vez que sabes cómo manejarlas.

Punto 1: La falta de argumentos causa un error (`IndexError`)

Por ejemplo, digamos que escribes un programa que toma un argumento —un nombre— e imprime un saludo.

<!-- greet.py -->
import sys

# Obtener el primer argumento como un nombre
name = sys.argv[1]

print(f"¡Hola, {name}!")

Si ejecutas este programa correctamente pasándole un nombre...

# Ejemplo de ejecución correcta
python greet.py García
# Salida
# ¡Hola, García!

¡Funciona perfectamente! Pero, ¿qué pasa si accidentalmente olvidas pasar un argumento?

# Ejemplo olvidando un argumento
python greet.py
# Salida
# Traceback (most recent call last):
#   File "greet.py", line 4, in <module>
#     name = sys.argv[1]
# IndexError: list index out of range

Obtienes un `IndexError: list index out of range`. Este error significa "¡Intentaste acceder a un índice que está fuera del rango de la lista!". Como no pasaste ningún argumento, `sys.argv` solo contiene `['greet.py']`. Eso significa que el índice `1` no existe, por lo que el programa se queja cuando intentas acceder a `sys.argv[1]`.

【Solución】Al principio de tu programa, comprueba si tienes el número esperado de argumentos. Puedes obtener el número de elementos en una lista con `len()`.

<!-- greet_safe.py (versión segura) -->
import sys

# El número de elementos en sys.argv es "nombre del script + número de argumentos"
# Queremos 1 argumento, por lo que len(sys.argv) debería ser 2
if len(sys.argv) != 2:
    print("Error: Por favor, especifica un nombre.")
    print("Uso: python greet_safe.py [Tu Nombre]")
    sys.exit() # Salir del programa aquí

# Si llegamos a esta línea, el argumento se pasó correctamente
name = sys.argv[1]

print(f"¡Hola, {name}!")

Punto 2: Todos los argumentos se tratan como cadenas de texto

Otro punto crucial es que todos los argumentos en `sys.argv`, incluso si parecen números, se tratan como cadenas de texto (strings).

Por ejemplo, consideremos un programa que toma dos números como argumentos y los suma.

<!-- add_wrong.py (Ejemplo incorrecto) -->
import sys

num1 = sys.argv[1] # La cadena de texto '100'
num2 = sys.argv[2] # La cadena de texto '50'

result = num1 + num2 # Esto concatenará las cadenas

print(f"{num1} + {num2} = {result}")

Ejecutar esto te dará un resultado inesperado.

# Ejemplo de ejecución
python add_wrong.py 100 50

# Salida
# 100 + 50 = 10050

En lugar de `150`, obtienes `10050`. Esto se debe a que las cadenas `'100'` y `'50'` simplemente se unieron.

【Solución】Si quieres tratar los argumentos como números para hacer cálculos, necesitas convertir su tipo de cadena a un número (entero o flotante) usando `int()` o `float()`. También es una buena práctica usar un bloque `try-except` para manejar los casos en los que se introducen caracteres no numéricos.

<!-- add_correct.py (Ejemplo correcto) -->
import sys

# Comprobar el número de argumentos
if len(sys.argv) != 3:
    print("Error: Por favor, especifica dos números.")
    print("Uso: python add_correct.py [número1] [número2]")
    sys.exit()

try:
    # Convertir cadenas a enteros usando int()
    num1 = int(sys.argv[1])
    num2 = int(sys.argv[2])
    
    result = num1 + num2
    print(f"{num1} + {num2} = {result}")

except ValueError:
    # Ocurre un ValueError si int() no puede convertir
    print("Error: Los argumentos deben ser números enteros.")

【Avanzado】¡Copia, pega y listo! Genera archivos HTML automáticamente con argumentos ✨

Muy bien, ¡llegó el momento estelar! Usemos lo que hemos aprendido para crear un programa práctico que es perfecto para ti, un creador web.

Este es un programa que "toma un 'nombre' y un 'color favorito' como argumentos de línea de comandos y genera automáticamente un archivo HTML con un mensaje de saludo especial solo para esa persona".

Guarda el siguiente código como `create_html.py`. ¡Puedes simplemente copiar y pegar todo el bloque!

<!-- create_html.py -->
import sys
import os

# --- 1. Comprobar argumentos ---
# Necesitamos 2 argumentos: "nombre" y "color favorito"
if len(sys.argv) != 3:
    print("[Error] Número de argumentos incorrecto.")
    print("[Uso] python create_html.py [Nombre] [código_de_color_o_nombre]")
    print("[Ejemplo] python create_html.py García hotpink")
    sys.exit()

# --- 2. Poner los argumentos en variables descriptivas ---
user_name = sys.argv[1]
fav_color = sys.argv[2]

# --- 3. Generar el contenido para escribir en el archivo HTML ---
# ¡Las f-strings son útiles para incrustar variables en una cadena!
# Un código completo de HTML/CSS/JS
html_content = f"""
<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Un mensaje especial para {user_name}</title>
    <style>
        body {{
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
            display: flex;
            justify-content: center;
            align-items: center;
            height: 100vh;
            margin: 0;
            background-color: #121212;
            color: #ffffff;
        }}
        .card {{
            padding: 40px 60px;
            border-radius: 15px;
            text-align: center;
            border: 2px solid {fav_color};
            box-shadow: 0 10px 25px rgba(0, 0, 0, 0.5);
            background-color: #1e1e1e;
        }}
        h1 {{
            margin: 0;
            font-size: 2.5em;
            /* Color aplicado vía JavaScript */
        }}
        p {{
            margin-top: 10px;
            font-size: 1.2em;
            color: #cccccc;
        }}
    </style>
</head>
<body>
    <div class="card">
        <h1 id="greeting">¡Hola, {user_name}!</h1>
        <p>Tu color favorito es <strong style="color: {fav_color};">{fav_color}</strong>, ¿verdad?</p>
    </div>

    <script>
        // Un pequeño toque divertido, aplicando un degradado al color del texto
        const greeting = document.getElementById('greeting');
        greeting.style.background = `linear-gradient(45deg, {fav_color}, #ffffff)`;
        greeting.style.webkitBackgroundClip = 'text';
        greeting.style.color = 'transparent';
    </script>
</body>
</html>
"""

# --- 4. Escribir el archivo ---
# El nombre del archivo será algo como "greet_Nombre.html"
file_name = f"greet_{user_name}.html"

try:
    with open(file_name, "w", encoding="utf-8") as f:
        f.write(html_content)
    
    # Mostrar un mensaje de éxito
    # os.path.abspath() obtiene la ruta completa del archivo
    full_path = os.path.abspath(file_name)
    print("🎉 ¡Archivo HTML generado con éxito!")
    print(f"Nombre del archivo: {file_name}")
    print(f"Guardado en: {full_path}")
    print("¡Ábrelo en tu navegador para comprobarlo!")

except IOError as e:
    print(f"[Error] No se pudo escribir el archivo: {e}")
    sys.exit()

¿Listo? En tu terminal, ¡ejecuta el script con tu nombre y tu color favorito (cualquier nombre de color de CSS o código funcionará) como argumentos!

# Ejemplo (¡pruébalo con tu propio nombre!)
python create_html.py Rodríguez "rgb(102, 157, 246)"

Después de ejecutarlo, aparecerá un mensaje de éxito en la terminal.

🎉 ¡Archivo HTML generado con éxito!
Nombre del archivo: greet_Rodríguez.html
Guardado en: /Users/yourname/path/to/greet_Rodríguez.html
¡Ábrelo en tu navegador para comprobarlo!

Y ahora, un nuevo archivo como `greet_Rodríguez.html` debería haberse creado en la misma carpeta. ¡Haz doble clic en este archivo HTML para abrirlo en tu navegador!

Ejemplo del archivo HTML generado mostrado en un navegador. Hay una tarjeta en el centro con un encabezado en degradado que dice '¡Hola, Rodríguez!' y texto sobre el color especificado.

¿Qué te parece? ¡Con un solo comando, se creó una página web solo para ti! Este es el poder de los argumentos de línea de comandos. Si tienes una plantilla de archivo, puedes producir en masa instantáneamente archivos similares cambiando el nombre, el color, el mensaje y más. ¿No es asombroso?

Resumen: La pantalla negra puede ser tu aliada

En este artículo, cubrimos cómo manejar argumentos de línea de comandos usando `sys.argv` de Python, con algunas de mis propias historias de tropiezos incluidas.

sys.argv almacena los argumentos como una lista.
sys.argv[0] es el nombre del script. Los argumentos reales comienzan desde [1].
Todos los argumentos son cadenas de texto, así que conviértelos con `int()` si necesitas números.
No comprobar el número de argumentos con `len()` puede llevar a un IndexError.
¡Combinando estas habilidades puedes construir herramientas potentes que automatizan tareas repetitivas!

La línea de comandos puede parecer intimidante al principio, pero una vez que te familiarizas con ella, se convertirá en tu mejor aliada, mejorando drásticamente tu flujo de trabajo. Espero que este artículo te sirva de trampolín para dar tu primer salto al mundo de la pantalla negra.

Hacia el siguiente paso

Si te interesa la automatización de programas, intenta controlar los tiempos de los procesos a continuación. Con el módulo `time` de Python, puedes hacer que un programa espere un cierto período (sleep) o medir con precisión cuánto tiempo tarda un proceso.

➡️ Cómo retrasar y medir el tiempo con el módulo time