Depurar un programa significa observar su estado para descubrir por qué el resultado no coincide con lo esperado. Aunque un depurador visual y el módulo logging son herramientas más completas, las f-strings para depurar Python ofrecen una forma rápida de inspeccionar variables, tipos, expresiones y estructuras durante el desarrollo.
En esta guía aprenderás a usar el especificador de depuración =, !r, formatos numéricos, fechas, colecciones y mensajes de contexto. También verás cuándo una impresión temporal es suficiente y cuándo conviene pasar a la depuración de Python en VS Code o al módulo logging.
Qué es una f-string
Una f-string es una cadena precedida por la letra f. Las expresiones colocadas entre llaves se evalúan en el momento de construir el texto.
nombre = "Ana"
puntos = 87
print(f"Usuario: {nombre}, puntos: {puntos}")La documentación oficial sobre literales de cadena formateados explica la sintaxis y las opciones de formato. La propuesta original está documentada en la PEP 498.
Usar el especificador de depuración =
Desde Python 3.8 puedes escribir una expresión seguida de =. El resultado incluye tanto el texto de la expresión como su valor.
precio = 49.90
cantidad = 3
print(f"{precio=}")
print(f"{cantidad=}")
print(f"{precio * cantidad=}")La salida será parecida a:
precio=49.9
cantidad=3
precio * cantidad=149.7Este recurso evita escribir manualmente etiquetas que pueden quedar desactualizadas después de renombrar una variable.
Mostrar la representación real con !r
Los espacios, saltos de línea y caracteres especiales pueden pasar desapercibidos con una impresión normal. La conversión !r utiliza repr() y hace visibles esos detalles.
texto = " Python\n"
print(f"{texto=}")
print(f"{texto=!r}")Esto ayuda a detectar valores que contienen espacios al principio o al final. También es útil al revisar archivos, respuestas de APIs y entradas del usuario.
Comprobar valores y tipos
edad = "25"
print(f"{edad=}, {type(edad)=}")Aquí queda claro que edad es una cadena, no un entero. Muchos errores aparecen cuando el programa recibe un tipo distinto del esperado. Para organizar conversiones y validaciones, consulta la guía de funciones en Python.
Depurar cálculos numéricos
Los especificadores de formato se pueden combinar con =.
subtotal = 125.789
impuesto = 0.21
total = subtotal * (1 + impuesto)
print(f"{subtotal=:.2f}")
print(f"{impuesto=:.1%}")
print(f"{total=:.2f}")El formato permite comparar los valores con la misma presentación utilizada en la aplicación. Sin embargo, no confundas la presentación redondeada con el valor interno.
Inspeccionar condiciones
edad = 17
tiene_permiso = True
print(f"{edad >= 18=}")
print(f"{tiene_permiso=}")
print(f"{edad >= 18 or tiene_permiso=}")Imprimir cada parte de una condición larga facilita descubrir qué subexpresión provoca una decisión inesperada. También puedes asignar nombres intermedios para mejorar la legibilidad.
Depurar bucles
numeros = [3, 8, 12, 5]
for indice, numero in enumerate(numeros):
cuadrado = numero ** 2
print(f"{indice=}, {numero=}, {cuadrado=}")Incluye el índice y el valor para identificar exactamente en qué iteración aparece el problema. Evita imprimir miles de líneas en colecciones grandes; limita la muestra o utiliza logging con niveles.
Inspeccionar diccionarios y listas
usuario = {
"nombre": "Lucía",
"activo": True,
"roles": ["editor", "autor"],
}
print(f"{usuario=}")
print(f"{usuario['roles']=}")Para estructuras extensas, pprint puede ofrecer una presentación más clara. También puedes imprimir solamente las claves o el fragmento relevante.
Añadir contexto a una excepción
texto = "12a"
try:
numero = int(texto)
except ValueError as error:
print(f"No fue posible convertir {texto=!r}: {error}")Una buena salida de depuración muestra el valor problemático y la operación que falló. No captures excepciones solamente para ocultarlas. La guía de try y except en Python explica cómo manejar errores específicos.
Crear una función temporal de depuración
def depurar(etiqueta, valor):
print(f"[DEBUG] {etiqueta}: {valor!r} ({type(valor).__name__})")
depurar("respuesta", {"status": 200, "items": 4})Este patrón centraliza el formato, pero no debe crecer hasta convertirse en un sistema de registro improvisado. En aplicaciones reales, utiliza logging.debug(), que permite controlar niveles, destinos y formatos sin eliminar llamadas del código.
f-strings frente a logging
Las impresiones temporales son adecuadas para un script pequeño o una hipótesis puntual. Logging es preferible cuando necesitas conservar eventos, diferenciar gravedad, registrar excepciones o ejecutar el programa en producción.
import logging
logging.basicConfig(level=logging.DEBUG)
usuario_id = 42
logging.debug("Procesando usuario %s", usuario_id)En logging suele recomendarse pasar los argumentos por separado para evitar construir el mensaje cuando el nivel está desactivado.
Probar después de corregir el error
Una impresión confirma lo que ocurrió durante una ejecución, pero una prueba evita que el mismo problema regrese. Convierte el caso que falló en una prueba automatizada. La guía de Pytest para principiantes muestra cómo crear casos normales, límites y excepciones.
No revelar datos sensibles
No imprimas contraseñas, tokens, cookies, claves privadas ni datos personales. Una f-string puede exponer accidentalmente un objeto completo. Selecciona solamente los campos necesarios y reemplaza valores sensibles.
configuracion = {
"usuario": "ana",
"token": "secreto",
}
print(f"usuario={configuracion['usuario']!r}, token=[OCULTO]")Errores frecuentes
- Dejar impresiones de depuración en producción.
- Imprimir estructuras enormes dentro de un bucle.
- Exponer secretos o información personal.
- Usar un valor formateado como si fuera el valor real.
- Agregar tantas impresiones que la salida pierda utilidad.
- Confiar solamente en
print()cuando se necesita un depurador. - Corregir el síntoma sin añadir una prueba de regresión.
Flujo recomendado
- Reproduce el fallo con una entrada pequeña.
- Formula una hipótesis sobre la variable o condición incorrecta.
- Imprime únicamente los valores necesarios con
=y!r. - Comprueba tipos, límites y ramas de decisión.
- Corrige la causa.
- Elimina las impresiones temporales o conviértelas en logging.
- Añade una prueba automatizada.
Conclusión
Las f-strings son una herramienta rápida para depurar Python porque muestran expresiones y valores con poco código. El especificador =, la conversión !r y los formatos numéricos ayudan a revelar tipos, espacios, condiciones y cálculos inesperados.
Utilízalas para investigaciones puntuales, protege los datos sensibles y pasa a un depurador, logging y pruebas cuando el proyecto necesite un diagnóstico reproducible. La mejor depuración no consiste en imprimir todo, sino en observar la información exacta que permite confirmar o descartar una hipótesis.
