Los 5 errores de Python que debes conocer

Introducción

Python es un lenguaje diseñado para la legibilidad, pero eso no evita que aparezcan errores. Algunos son triviales y otros pueden confundir incluso a programadores con experiencia. Aquí repasamos los cinco errores que encontrarás con más frecuencia, explicando qué significan, por qué ocurren, cómo reproducirlos, cómo solucionarlos y cómo evitarlos en el futuro.

Índice rápido

• IndentationError
• SyntaxError
• IndexError
• ValueError
• AttributeError
• Mini-metodología de depuración
• Chequeos por rol
• Casos de prueba y criterios de aceptación
• Glosario rápido

5 IndentationError

Qué es (una línea): IndentationError ocurre cuando la sangría del código no corresponde a la estructura de bloques que Python espera.

Explicación extendida

En Python, los bloques de código (condicionales, bucles, funciones, clases) se determinan mediante la sangría, no con llaves. Todas las sentencias dentro de un mismo bloque deben mantener el mismo nivel de sangría. Un cambio inesperado en la sangría indica al intérprete que comienza o termina un bloque; si esa expectativa no se cumple, obtendrás un IndentationError.

Causas comunes

• Copiar y pegar código desde editores con diferentes configuraciones (tabs vs espacios).
• Mezclar tabulaciones y espacios en el mismo archivo.
• Olvidar la sangría dentro de un bloque.
• Líneas en blanco con espacios o tabs invisibles.

Ejemplo que falla

for i in range(5):
print(i)

Solución mínima

for i in range(5):
    print(i)

Buenas prácticas para evitarlo

• Configura tu editor para que muestre caracteres invisibles (tabs y espacios).
• Elige espacios (PEP 8 recomienda 4 espacios) o tabs y documenta la decisión en el proyecto.
• Usa una herramienta de formateo automático (black, autopep8).
• Añade una regla en el linter que detecte mezcla de tabs y espacios.

Diagnóstico rápido (lista de verificación)

• ¿El editor muestra tabulaciones? ¿Se ven como flechas o cuadros?
• ¿El archivo contiene una mezcla de tabs y espacios? (buscar ‘\t’ y cuatro espacios)
• Ejecuta: python -m py_compile archivo.py para localizar el error exacto.

Cuándo puede fallar esta solución

Si el código proviene de múltiples colaboradores con distintas configuraciones, arreglar un bloque puede dejar otros con inconsistencias; aplica formateo automático a todo el repositorio.

4 SyntaxError

Qué es (una línea): SyntaxError ocurre cuando el código viola las reglas gramaticales del lenguaje Python y no puede ser interpretado.

Explicación extendida

La sintaxis es la gramática del lenguaje de programación. Cuando escribes algo que no encaja en esa gramática, Python no sabe cómo convertirlo en instrucciones ejecutables. Los SyntaxError impiden que el programa arranque y normalmente incluyen la línea y la posición aproximada del problema.

Causas comunes

• Olvidar dos puntos (:) al iniciar un bloque (if, for, def, class).
• Paréntesis, corchetes o comillas sin cerrar.
• Palabras reservadas mal escritas (por ejemplo, esle en vez de else).
• Uso indebido de operadores (= en lugar de ==) en expresiones condicionales.
• Asignar a una palabra reservada.

Ejemplo típico

if x > 0
    print("positivo")

Solución

if x > 0:
    print("positivo")

Tips de depuración

• Revisa la línea indicada y la anterior: el error real muchas veces está en la línea previa.
• Usa un buen IDE o linter que marque errores de sintaxis mientras escribes.
• Si el mensaje es críptico, intenta ejecutar porciones pequeñas del código hasta aislar el problema.

Cuando la ayuda del intérprete no basta

Hay casos con estructuras complejas (f-strings anidados, cadenas multilínea, comprensiones largas) en los que el mensaje puede ser ambiguo. En esos casos, reduce la expresión o separa en variables intermedias para encontrar el fallo.

3 IndexError

Qué es (una línea): IndexError ocurre cuando intentas acceder a una posición (índice) que está fuera del rango válido de una secuencia.

Explicación extendida

Secuencias como listas y tuplas indexan desde 0 hasta N-1. Si pides el índice N o un índice negativo que no existe, Python lanza IndexError. Este error surge con frecuencia por desajustes off-by-one o al modificar una secuencia mientras la iteras.

Ejemplo

numbers = [1, 2, 3]
print(numbers[3])  # IndexError porque los índices válidos son 0, 1, 2

Prevención

• Antes de acceder a un índice, comprueba 0 <= i < len(seq).
• Cuando iteres, prefiere “for elem in seq” en vez de indices;
• Si necesitas índices, usa enumerate(seq).
• Evita modificar la secuencia (append/pop) mientras iteras; crea una copia si necesitas mutarla.

Ejemplo seguro

for i, val in enumerate(numbers):
    print(i, val)

# o
if index < len(numbers):
    # ejecutar
    pass

Casos sutiles

• Al usar slicing, recuerda que el slice no lanza IndexError: numbers[0:10] simplemente devuelve lo disponible.
• Al combinar bucles y pops, el índice residual puede volverse inválido.

2 ValueError

Qué es (una línea): ValueError ocurre cuando una función recibe un argumento con el tipo correcto pero un valor inapropiado.

Explicación extendida

Muchas funciones validan no solo el tipo del argumento, sino también su valor. Cuando el tipo es aceptable pero el valor no tiene sentido para la operación, Python lanza ValueError. Esto ocurre frecuentemente en conversiones de tipos y operaciones matemáticas con dominios restringidos.

Ejemplos comunes

• Conversión inválida: int(‘ten’) → ValueError.
• Operación matemática fuera de dominio: math.sqrt(-5) → ValueError si la función no admite números complejos.

Demostración

int('10')   # 10
int('ten')  # ValueError

import math
math.sqrt(-5)  # ValueError en funciones que no aceptan negativos

Manejo recomendado

Encapsula conversiones y operaciones en bloques try/except y ofrece retroalimentación clara al usuario o consumidor de la función.

try:
    num = input("Introduce un número: ")
    num_int = int(num)
except ValueError as e:
    print(f"Se detectó un ValueError: {e}")

Alternativas cuando el valor es impredecible

• Usar validación previa con expresiones regulares o funciones de parseo más tolerantes.
• Proveer valores por defecto o pedir reintento al usuario.
• Para datos en lotes, registrar el error y continuar con el siguiente elemento.

1 AttributeError

Qué es (una línea): AttributeError ocurre cuando intentas acceder a un atributo o método inexistente en un objeto.

Explicación extendida

Los objetos en Python (instancias, módulos, tipos) tienen atributos y métodos asociados. Si solicitas algo que no existe, Python lo señaliza como AttributeError. Esto puede deberse a un error tipográfico, a suposiciones incorrectas sobre el tipo de objeto o a variables que resultan ser None.

Ejemplos

text = "hello world"
print(text.push())  # AttributeError: 'str' object has no attribute 'push'

user = None
print(user.name)    # AttributeError: 'NoneType' object has no attribute 'name'

Cómo evitarlo

• Verifica el tipo del objeto con type(obj) o isinstance(obj, Clase).
• Usa dir(obj) para listar atributos disponibles.
• Asegura que las variables no sean None antes de acceder a atributos (ej., if obj is not None: …).
• En APIs dinámicas, documenta los contratos y valida entradas y salidas.

Patrones útiles

• Patrón EAFP (Easier to Ask Forgiveness than Permission): intenta usar el atributo y captura AttributeError si aparece.

try:
    result = obj.some_method()
except AttributeError:
    # fallback
    result = fallback()

• Patrón LBYL (Look Before You Leap): comprueba con hasattr(obj, ‘some_method’) antes de llamar.

if hasattr(obj, 'some_method'):
    result = obj.some_method()
else:
    result = fallback()

Cuándo uno u otro patrón es preferible depende del contexto: EAFP es más “pythonico” cuando el error es excepcional; LBYL evita excepciones en código crítico donde el coste de manejar excepciones es alto.

Mini-metodología para depurar errores en Python (pasos rápidos)

1. Leer el traceback completo. Identifica la excepción y la línea donde ocurrió.
2. Reproducir el error con el mínimo código posible (minimizar para aislar).
3. Inspeccionar tipos y valores relevantes con print(), logging o el depurador (pdb).
4. Aplicar la solución más simple y segura; escribir un test unitario que reproduzca el fallo para evitar regresiones.
5. Añadir validaciones o manejo de excepciones si procede.

Checklist de diagnóstico

• ¿Es replicable con datos pequeños?
• ¿El error ocurre en producción o solo en un entorno concreto?
• ¿Los tests cubren este caso? Si no, añade tests.
• ¿Es un bug del código o un dato de entrada incorrecto?

Diagrama de decisión rápido (Mermaid)

flowchart TD
  A[¿Hay traceback?] -->|No| B[Ejecuta el script para obtenerlo]
  A -->|Sí| C[Leer tipo de excepción]
  C --> D{¿Es SyntaxError?}
  D -->|Sí| E[Revisar líneas previas y paréntesis]
  D -->|No| F{¿Es IndentationError?}
  F -->|Sí| G[Chequear tabs/espacios y sangría]
  F -->|No| H{¿Es IndexError?}
  H -->|Sí| I[Revisar índices y uso de len'']
  H -->|No| J{¿Es ValueError?}
  J -->|Sí| K[Validar valores y conversión]
  J -->|No| L{¿Es AttributeError?}
  L -->|Sí| M[Verificar tipo y hasattr/dir]
  L -->|No| N[Investigar otras excepciones]

Chequeos por rol: qué debe revisar cada miembro del equipo

• Desarrollador backend

  • Revisar entradas externas y contratos de API.
  • Añadir validaciones y tests unitarios.
  • Usar logging con contexto y métricas de error.

• Ingeniero de datos

  • Validar esquemas y sanitizar entradas antes del procesamiento.
  • Manejar errores por registro y continuar con lotes robustamente.

• Científico de datos

  • Comprobar tipos y dimensiones de arrays (NumPy/Pandas).
  • Añadir pruebas de integridad de datos (nulls, tipos, rangos).

• Instructor/educador

  • Enseñar buenas prácticas de sangría, manejo de excepciones y uso de herramientas.
  • Proveer ejercicios que provoquen y resuelvan cada error.

Casos de prueba y criterios de aceptación

Para cada error, crea tests unitarios que verifiquen el comportamiento correcto:

• IndentationError

  • Test: ejecutar módulo bien indentado → no se lanza IndentationError.
  • Criterio: el linter no debe reportar mezcla de tabs y espacios.

• SyntaxError

  • Test: parsear archivos con ast.parse(file_contents) → no debe lanzar excepción.
  • Criterio: el análisis estático pasa sin errores.

• IndexError

  • Test: funciones que acceden por índice, con índices límite (0, len-1) y fuera de rango → deberían manejar o lanzar IndexError documentado.
  • Criterio: el código valida índices antes de acceder.

• ValueError

  • Test: conversiones de entrada válidas e inválidas → las inválidas deben ser capturadas y tratadas según política.
  • Criterio: no hay crashes por inputs inválidos sin manejo.

• AttributeError

  • Test: llamadas condicionales con objetos None y objetos con atributo → debe existir manejo explicito.
  • Criterio: los casos None se tratan y los fallos quedan documentados.

Snippets y atajos (cheat sheet)

Validar índice antes de usar

def safe_get(lst, i, default=None):
    return lst[i] if 0 <= i < len(lst) else default

Conversión segura con reintento

def to_int_or_none(s):
    try:
        return int(s)
    except (TypeError, ValueError):
        return None

Detectar mezcla tabs/espacios

with open('archivo.py', 'rb') as f:
    data = f.read()
    if b'\t' in data and b'    ' in data:
        print('Posible mezcla de tabs y espacios')

Listar atributos disponibles

print(dir(obj))

Uso de enumerate para evitar IndexError

for i, val in enumerate(sequence):
    # seguro: i está dentro de rango
    pass

Glosario rápido (una línea cada término)

• IndentationError: error por sangría inconsistente en bloques de código.
• SyntaxError: error por violación de la gramática de Python.
• IndexError: acceso a un índice fuera del rango válido de una secuencia.
• ValueError: argumento con tipo correcto pero valor inapropiado.
• AttributeError: intento de usar un atributo o método inexistente en un objeto.

Notas importantes

Importanto: nunca ignores un traceback en producción; el mensaje contiene información clave sobre la causa real. Mantén logs legibles y anónimos si contienen datos sensibles.

Resumen final

• IndentationError y SyntaxError suelen detectarse temprano con linters y formateadores automáticos.
• IndexError y ValueError se resuelven con validaciones y tests que cubran límites y entradas inválidas.
• AttributeError se evita verificando tipos, usando dir/hasattr y adoptando patrones EAFP donde tenga sentido.

Aplicando las prácticas aquí descritas (formateo automático, pruebas unitarias, validación de entradas y manejo explícito de excepciones) reducirás el número de fallos y aumentarás la calidad y robustez del código Python.

Social preview sugerido

• Título breve: Errores comunes de Python: guía práctica
• Descripción breve: Aprende a identificar y corregir los 5 errores de Python que más se repiten, con ejemplos, checklist y snippets.