6.2Problemas recurrentes (playbook)
Lo esencial en 30 segundos
- Reflejo : un síntoma = unas causas probables = una acción específica — se diagnostica antes de tocar el código.
- Leer : la traceback se lee por abajo : la última línea nombra, lo de arriba localiza.
- Aislar : toda diferencia entre local y CI se trata con venv, requirements fijado y versiones alineadas.
Hilo Nabil — el playbook pegado junto a la pantalla
Nabil guarda este playbook junto a su pantalla. Veredicto tras un año : tres líneas son las que más le sirvieron — el venv no activado detrás de ModuleNotFoundError, la mezcla de tabulaciones + espacios, y la CI en rojo cuando todo estaba en verde en local. Para cada una, acabó aplicando la secuencia (leer la traceback, verificar la causa, corregir) en lugar de modificar al azar.
Síntoma observado, causas verificadas, acciones en orden : el reflejo cabe en tres tiempos.
Diagnosticar antes de relanzar
La mayoría de los bloqueos Python son grandes clásicos : cada síntoma tiene causas típicas y una acción específica. El cuadro siguiente agrupa las situaciones más frecuentes, de la importación al despliegue.
| Síntoma | Causas probables | Acciones |
|---|---|---|
| ModuleNotFoundError | intérprete equivocado, venv no activado, archivo en el lugar equivocado | seleccionar el intérprete correcto, activar el venv, verificar la ruta |
| IndentationError / TabError | tabulaciones + espacios mezclados | convertir a 4 espacios, black para normalizar |
| NameError | errata, variable fuera de alcance, importación olvidada | releer la última línea, verificar alcance e importaciones |
| KeyError en dict | clave ausente, acceso directo | .get() con valor por defecto + validar los datos de entrada |
| Funcionaba ayer (dependencias) | global mezclado, versiones derivadas | venv + requirements fijados, rebuild para probar |
| Pruebas en rojo tras refactorizar | comportamiento cambiado sin querer | leer LA prueba que falla, corregir el código (no la prueba), relanzar |
| API inalcanzable en contenedor | host localhost en lugar de 0.0.0.0 | CMD con --host 0.0.0.0, -p para publicar |
| CI en rojo, local en verde | versiones distintas, prueba faltante, secreto ausente | alinear versiones (requirements), reproducir en local, verificar secretos |
| Script lento con gran volumen | bucles Python en lugar de vectorizado/generador | perfilar, vectorizar (pandas/NumPy) o yield |
Guion listo para decir — diagnosticar sin tocar al azar (30 s)
« Mi síntoma : [ModuleNotFoundError / KeyError / CI en rojo / lentitud]. Leo la traceback por abajo, identifico la causa probable del playbook, aplico la acción específica y verifico. »
Modelo copiar-pegar — acceso seguro + error preciso
def taux_ville(ligne: dict) -> float:
ville = ligne.get("ville", "inconnue")
if ville == "inconnue":
raise ValueError("clé 'ville' absente de la ligne")
return float(ligne.get("taux", 0.0))TPE / presupuesto pequeño
Sin cuadro formal : un síntoma, la causa probable del playbook, la acción y el responsable anotado.
Pyme Argel
Integrar las realidades locales en el diagnóstico : versiones instaladas, puestos compartidos, picos del lunes conocidos.
Remoto / híbrido
Añadir los logs escritos inmediatos a las acciones : a distancia, un síntoma no anotado parece un sistema que funciona.
Intercultural
Explicitar las observaciones por escrito : lo que parece evidente (qué venv, qué versión) no lo es para todos.
Desafío 48h — aplica mañana
Detecta 1 síntoma actual (importación, KeyError, CI en rojo), aplica la línea del playbook (traceback leída + causa verificada + acción específica).
- Sé relacionar un síntoma con sus causas probables.
- Leo la traceback por abajo antes de corregir.
- Sé blindar con venv, hints y pruebas.
El script de Nabil lanza KeyError en un dict de ventas. ¿Qué reflejo aplica el playbook ?
Un mismo problema que vuelve sin cesar no son diez incidentes : es un método a corregir (venv, pruebas, hints).