calendar.timegm es una función de la biblioteca estándar de Python que convierte una estructura de fecha y hora en un timestamp Unix interpretando todos los componentes como UTC. Es útil cuando un parser, protocolo, API antigua o función del sistema entrega una tupla compatible con time.gmtime() y necesitas obtener los segundos transcurridos desde la época Unix.
En esta guía aprenderás qué devuelve la función, cómo se diferencia de time.mktime(), cómo combinarla con datetime y zoneinfo, y cómo evitar errores sutiles de zona horaria en APIs, registros, tareas programadas y sistemas distribuidos.
Qué hace calendar.timegm
La función recibe una secuencia que contiene al menos año, mes, día, hora, minuto y segundo. Trata esos valores como una fecha UTC y devuelve el timestamp correspondiente. La época Unix comienza el 1 de enero de 1970 a las 00:00:00 UTC.
import calendar
tupla_utc = (2026, 9, 14, 12, 0, 0)
timestamp = calendar.timegm(tupla_utc)
print(timestamp)
La función es el inverso práctico de time.gmtime(). Mientras gmtime convierte un timestamp en una estructura UTC, timegm convierte la estructura nuevamente en segundos.
Conversión de ida y vuelta
import calendar
import time
original = time.time()
estructura = time.gmtime(original)
restaurado = calendar.timegm(estructura)
print(original, restaurado)
El valor restaurado normalmente pierde la parte fraccionaria porque struct_time trabaja con segundos enteros. Este patrón es útil en colas de mensajes, auditorías y protocolos que intercambian timestamps enteros.
Diferencia frente a time.mktime
time.mktime() interpreta la entrada como hora local. Por eso, la misma tupla puede producir timestamps distintos en servidores configurados en regiones diferentes. calendar.timegm() siempre interpreta los valores como UTC.
import calendar
import time
valor = (2026, 9, 14, 9, 0, 0, 0, 0, -1)
print(calendar.timegm(valor))
print(time.mktime(valor))
Si la tupla representa tiempo universal, usar mktime puede desplazar silenciosamente el instante según el offset local. Usa timegm cuando UTC forme parte del contrato de datos.
Uso con struct_time
Un objeto struct_time es válido porque se comporta como una secuencia. Los campos adicionales, como día de la semana y día del año, no sustituyen los componentes principales.
import calendar
import time
estructura = time.strptime("2026-09-14 12:30:00", "%Y-%m-%d %H:%M:%S")
timestamp = calendar.timegm(estructura)
strptime analiza el texto, pero no demuestra que la fuente esté en UTC. La aplicación debe conocer y documentar el significado de la zona horaria.
Comparación con datetime.timestamp
El código moderno suele usar objetos datetime conscientes de zona porque conservan más contexto.
from datetime import datetime, timezone
fecha = datetime(2026, 9, 14, 12, 0, tzinfo=timezone.utc)
print(fecha.timestamp())
Esta suele ser la opción más clara cuando la aplicación ya trabaja con datetime. Sin embargo, calendar.timegm sigue siendo conveniente para interfaces basadas en tuplas y para dejar explícito que una estructura representa UTC.
Convertir datetime mediante una tupla UTC
import calendar
from datetime import datetime, timezone
ahora = datetime.now(timezone.utc)
timestamp = calendar.timegm(ahora.utctimetuple())
Esta conversión descarta los microsegundos. Usa ahora.timestamp() si necesitas precisión inferior al segundo.
El problema de datetime sin zona
Un datetime naive no contiene información de zona horaria. Interpretarlo como UTC sin conocer su origen es peligroso. Un valor 09:00 podría representar São Paulo, Madrid, Nueva York o UTC.
from datetime import datetime, timezone
naive = datetime(2026, 9, 14, 9, 0)
utc_explicito = naive.replace(tzinfo=timezone.utc)
replace no convierte el instante. Solo declara que los números existentes pertenecen a UTC. Úsalo únicamente cuando esa afirmación sea correcta.
Conversión regional con zoneinfo
from datetime import datetime
from zoneinfo import ZoneInfo
local = datetime(2026, 9, 14, 9, 0, tzinfo=ZoneInfo("America/Sao_Paulo"))
utc = local.astimezone(ZoneInfo("UTC"))
print(utc.timestamp())
Las zonas regionales consideran reglas históricas de offset. Convertir con zoneinfo es más seguro que sumar o restar horas manualmente.
Entradas de API
Una API debería aceptar un formato documentado, idealmente ISO 8601 con offset. Analiza el valor como un objeto consciente de zona antes de convertirlo.
from datetime import datetime
texto = "2026-09-14T12:00:00+00:00"
fecha = datetime.fromisoformat(texto)
timestamp = int(fecha.timestamp())
Usa calendar.timegm cuando el protocolo ya entregue una tupla UTC. No elimines el offset de una cadena para después tratar los números restantes como UTC.
Timestamps negativos
Muchas plataformas modernas admiten timestamps negativos para fechas anteriores a 1970. El rango exacto puede variar según el sistema operativo y la compilación de Python. Las aplicaciones históricas deben probar los límites requeridos en todos sus entornos.
Segundos intercalares
Los timestamps Unix tradicionales no modelan segundos intercalares como segundos ordinarios separados. Python sigue el comportamiento temporal de la plataforma y no pretende ser una biblioteca de escala astronómica. Para requisitos científicos, utiliza una librería especializada.
Validación de entrada
Los componentes externos deben validarse. Construir un datetime permite rechazar combinaciones imposibles.
from datetime import datetime, timezone
try:
valor = datetime(2026, 2, 30, tzinfo=timezone.utc)
except ValueError as error:
print("Fecha inválida", error)
También conviene limitar el rango de años, rechazar tipos inesperados y registrar claramente si la fuente es UTC o una hora regional.
Pruebas deterministas
El código de fechas es más fácil de probar con valores UTC fijos. Verifica el timestamp esperado y la conversión inversa.
import calendar
import time
def test_timegm_roundtrip():
origen = (2026, 9, 14, 12, 0, 0, 0, 0, 0)
timestamp = calendar.timegm(origen)
resultado = time.gmtime(timestamp)
assert resultado[:6] == origen[:6]
Evita pruebas cuyo resultado dependa de la zona horaria del servidor de integración continua. Las pruebas UTC son portables y fáciles de revisar.
Segundos, milisegundos y microsegundos
calendar.timegm devuelve segundos enteros. Navegadores y ecosistemas Java suelen usar milisegundos. Bases de datos y telemetría pueden usar microsegundos o nanosegundos. Documenta siempre la unidad.
segundos = calendar.timegm((2026, 9, 14, 12, 0, 0))
milisegundos = segundos * 1000
Un valor correcto en una unidad incorrecta puede aparecer como una fecha absurda. La confusión de unidades es uno de los errores más frecuentes en integraciones.
Logs y sistemas distribuidos
Los timestamps UTC permiten ordenar eventos producidos en regiones diferentes. Los servicios deberían guardar el instante en UTC y convertirlo a la zona del usuario únicamente al presentarlo.
evento = {
"nombre": "tarea_finalizada",
"timestamp": calendar.timegm((2026, 9, 14, 12, 0, 0)),
}
Si el orden de eventos exige más precisión, conserva también microsegundos o utiliza un entero de mayor resolución.
Tareas programadas
Un planificador suele recibir una hora regional. Convierte esa hora con zoneinfo y guarda después el instante UTC. No pases directamente una tupla regional a timegm, porque la función la interpretará como UTC.
Almacenamiento en bases de datos
Una base de datos puede guardar fechas como tipos nativos, cadenas ISO o enteros Unix. Sea cual sea la representación, define la zona y la precisión. Los enteros son compactos, pero no conservan la zona original ni la intención de formato.
Errores frecuentes
Los problemas habituales incluyen pasar hora local a timegm, usar mktime con datos UTC, perder microsegundos sin advertirlo, mezclar segundos y milisegundos, asumir que una tupla contiene información de zona y depender de la configuración del servidor.
Buenas prácticas
Mantén los instantes internos en UTC, usa objetos conscientes de zona en los límites, convierte horas regionales con zoneinfo, valida los componentes externos, documenta las unidades y reserva calendar.timegm para estructuras que realmente representen UTC.
Guías relacionadas de Academify
Continúa con las guías de Academify sobre datetime en Python, zoneinfo en Python, módulo time y fechas en Python.
Referencias externas
Consulta la documentación oficial de calendar.timegm y la documentación oficial de datetime para revisar el comportamiento y la compatibilidad.
Conclusión
calendar.timegm ofrece una conversión específica y predecible de una tupla UTC a un timestamp Unix. Evita la interpretación local de time.mktime y se combina naturalmente con time.gmtime. Los objetos datetime conscientes de zona suelen ser más expresivos en aplicaciones nuevas, pero timegm continúa siendo una herramienta fiable para protocolos basados en tuplas, registros, parsers, planificadores e integraciones antiguas donde UTC está explícito.
