El módulo time de Python ofrece funciones para trabajar con tiempo a bajo nivel: obtener marcas temporales, pausar la ejecución, convertir valores a estructuras locales y medir la duración de operaciones. Está incluido en la biblioteca estándar, por lo que no requiere instalación. Aunque algunas tareas de calendario se resuelven mejor con datetime, time sigue siendo fundamental para temporizadores, esperas, métricas y scripts que interactúan con el sistema.
La primera decisión importante es distinguir entre una fecha civil y una medición de duración. Para fechas, zonas horarias y cálculos de calendario, consulta la guía de datetime en Python. Para medir cuánto tarda una operación, utiliza relojes monotónicos como perf_counter().
Obtener el timestamp actual
time.time() devuelve los segundos transcurridos desde el inicio de la época Unix, normalmente el 1 de enero de 1970 en UTC. El resultado es un número de punto flotante:
import time
ahora = time.time()
print(ahora)Este valor es útil para almacenar instantes, comparar momentos o construir identificadores temporales sencillos. Sin embargo, el reloj del sistema puede ajustarse por sincronización, cambios manuales o administración de la máquina. Por eso no es la mejor opción para medir duraciones.
Convertir timestamps a una estructura legible
localtime() convierte un timestamp a la hora local y devuelve una estructura struct_time:
import time
momento = time.localtime()
print(momento.tm_year)
print(momento.tm_mon)
print(momento.tm_mday)
print(momento.tm_hour)Para UTC utiliza gmtime():
utc = time.gmtime()
print(utc)Estas funciones dependen de la configuración del sistema. En aplicaciones distribuidas suele ser más seguro almacenar tiempos en UTC y convertirlos únicamente al presentar información al usuario.
Formatear fechas con strftime
strftime() transforma una estructura temporal en texto mediante códigos de formato:
import time
texto = time.strftime("%Y-%m-%d %H:%M:%S")
print(texto)Los códigos más comunes son %Y para el año, %m para el mes, %d para el día, %H para la hora, %M para minutos y %S para segundos. Algunos nombres de meses y días dependen de la configuración regional del sistema.
Convertir texto con strptime
strptime() analiza una cadena y devuelve struct_time:
import time
fecha = time.strptime("2026-07-11 18:30", "%Y-%m-%d %H:%M")
print(fecha.tm_year)
print(fecha.tm_hour)Si el texto no coincide con el formato, se lanza ValueError. Valida entradas externas y muestra un mensaje claro en lugar de capturar todas las excepciones.
Pausar la ejecución con sleep
time.sleep(segundos) suspende el hilo actual durante aproximadamente el tiempo indicado:
import time
print("Iniciando")
time.sleep(2)
print("Continuando")La pausa puede ser ligeramente mayor debido a la planificación del sistema. sleep() no garantiza precisión de tiempo real y bloquea el hilo donde se ejecuta. En una interfaz gráfica puede congelar la ventana; en código asíncrono debes utilizar una espera compatible con asyncio.
Crear una cuenta regresiva
import time
for restante in range(5, 0, -1):
print(f"Comenzamos en {restante}...")
time.sleep(1)
print("¡Ahora!")Este patrón funciona para scripts de terminal, pero no debe utilizarse como temporizador exacto. La ejecución del propio código también consume tiempo, por lo que los pequeños retrasos pueden acumularse.
Medir duración con perf_counter
perf_counter() utiliza el reloj de mayor resolución disponible e incluye el tiempo transcurrido durante las esperas. Es ideal para medir una operación completa:
import time
inicio = time.perf_counter()
total = sum(range(1_000_000))
fin = time.perf_counter()
print(f"Duración: {fin - inicio:.6f} segundos")El valor absoluto de perf_counter() no tiene significado útil; solo importa la diferencia entre dos lecturas. Para microbenchmarks repetibles, la guía de timeit en Python explica cómo reducir errores de medición.
Usar monotonic para timeouts
time.monotonic() nunca retrocede durante la ejecución del proceso, incluso si cambia la hora del sistema. Esto lo hace adecuado para límites de tiempo:
import time
limite = time.monotonic() + 5
while time.monotonic() < limite:
print("Esperando...")
time.sleep(1)
print("Tiempo agotado")No uses time.time() para un timeout cuando un ajuste del reloj podría extenderlo o reducirlo de forma inesperada.
Medir CPU con process_time
process_time() mide el tiempo de CPU consumido por el proceso y no incluye la mayor parte del tiempo de espera:
import time
inicio = time.process_time()
sum(i * i for i in range(2_000_000))
fin = time.process_time()
print(fin - inicio)Comparar process_time() con perf_counter() puede ayudarte a distinguir una carga intensiva de CPU de una operación que pasa tiempo esperando.
Crear un decorador de medición
from functools import wraps
import time
def medir(funcion):
@wraps(funcion)
def wrapper(*args, **kwargs):
inicio = time.perf_counter()
try:
return funcion(*args, **kwargs)
finally:
duracion = time.perf_counter() - inicio
print(f"{funcion.__name__}: {duracion:.6f} s")
return wrapper
@medir
def calcular():
return sum(range(500_000))Para producción, envía la métrica a un sistema de observabilidad o utiliza la guía de logging en Python en lugar de depender de print().
Esperas en reintentos
Cuando una API falla temporalmente, una pausa entre intentos puede evitar sobrecargar el servicio:
import time
for intento in range(1, 4):
try:
resultado = operacion_remota()
break
except TimeoutError:
if intento == 3:
raise
espera = 2 ** intento
time.sleep(espera)Este ejemplo utiliza espera exponencial. En servicios reales añade aleatoriedad, respeta los encabezados del proveedor y establece un número máximo de intentos.
Errores frecuentes
Los errores habituales son medir rendimiento con time.time(), usar sleep() en una interfaz o coroutine, asumir precisión exacta, mezclar hora local con UTC y formatear fechas sin documentar el patrón. También es frecuente utilizar pausas para “sincronizar” hilos; en ese caso necesitas primitivas de coordinación, no una espera arbitraria.
La documentación oficial del módulo time explica las diferencias entre relojes y la disponibilidad por plataforma. Para benchmarks pequeños y repetidos, consulta también la documentación oficial de timeit.
Cuándo elegir time o datetime
Utiliza time para pausas, relojes monotónicos, medición de rendimiento e interacción básica con timestamps del sistema. Elige datetime para fechas, zonas horarias, calendarios, intervalos y formatos de negocio. Una aplicación puede usar ambos: perf_counter() para métricas internas y objetos de fecha para información visible.
Conclusión
El módulo time ofrece herramientas pequeñas pero esenciales. sleep() controla pausas, time() obtiene timestamps, monotonic() protege timeouts y perf_counter() mide duraciones con precisión adecuada. La calidad del código depende de elegir el reloj correcto. Cuando distingues entre instante, duración, CPU y espera, evitas mediciones engañosas y construyes temporizadores más confiables.
