calendar.timegm é uma função da biblioteca padrão do Python usada para converter uma estrutura de data e hora em um timestamp Unix interpretando os valores como UTC. Ela é especialmente útil quando você recebe uma tupla compatível com time.gmtime(), precisa transformar datas universais em segundos desde a época Unix ou quer evitar ambiguidades causadas pelo fuso horário local.
Neste guia, você vai entender como a função trabalha, quando ela é preferível a outras alternativas, como evitar erros com horários locais, como integrar a conversão com datetime e como testar códigos que lidam com timestamps de forma previsível.
O que calendar.timegm faz
A função recebe uma sequência com pelo menos os seis primeiros componentes de uma data: ano, mês, dia, hora, minuto e segundo. Ela trata essa sequência como um horário em UTC e devolve o timestamp correspondente. O retorno representa a quantidade de segundos transcorridos desde 1º de janeiro de 1970 às 00:00:00 UTC.
import calendar
tupla_utc = (2026, 9, 14, 12, 0, 0)
timestamp = calendar.timegm(tupla_utc)
print(timestamp)
Esse comportamento é o inverso prático de time.gmtime(). Enquanto gmtime converte um timestamp em uma estrutura UTC, timegm faz a conversão de volta.
Exemplo com time.gmtime
import calendar
import time
agora = time.time()
estrutura = time.gmtime(agora)
reconstruido = calendar.timegm(estrutura)
print(agora)
print(reconstruido)
Os valores podem diferir apenas pela parte fracionária, porque a estrutura produzida por gmtime trabalha com segundos inteiros. Esse padrão é útil para serialização, logs, filas de mensagens e integração com sistemas que trocam timestamps UTC.
Por que não usar time.mktime
time.mktime() interpreta a estrutura recebida no fuso horário local do sistema. Isso significa que o mesmo conjunto de números pode produzir timestamps diferentes em servidores configurados em fusos distintos. Já calendar.timegm() sempre interpreta a entrada como UTC.
import calendar
import time
valor = (2026, 9, 14, 9, 0, 0, 0, 0, -1)
print(calendar.timegm(valor))
print(time.mktime(valor))
Em uma máquina configurada para São Paulo, mktime entende 09:00 como horário local. Em outra máquina configurada para Londres, o resultado pode mudar. Se a informação representa UTC, prefira timegm.
Compatibilidade com struct_time
A função aceita objetos struct_time, porque eles são sequências. Os campos adicionais, como dia da semana e dia do ano, não alteram o cálculo principal.
import calendar
import time
estrutura = time.strptime("2026-09-14 12:30:00", "%Y-%m-%d %H:%M:%S")
timestamp = calendar.timegm(estrutura)
print(timestamp)
Observe que strptime apenas interpreta o texto e produz uma estrutura sem fuso. É sua responsabilidade garantir que o texto realmente represente UTC antes de passá-lo para timegm.
Integração com datetime
Em código moderno, datetime costuma ser mais expressivo. Um objeto consciente de fuso pode gerar timestamp diretamente.
from datetime import datetime, timezone
data = datetime(2026, 9, 14, 12, 0, tzinfo=timezone.utc)
print(data.timestamp())
Mesmo assim, calendar.timegm continua útil quando a fonte já fornece uma tupla, quando você trabalha com APIs antigas baseadas no módulo time ou quando precisa deixar explícito que uma estrutura será tratada como UTC.
Convertendo datetime para tupla UTC
import calendar
from datetime import datetime, timezone
data = datetime.now(timezone.utc)
timestamp = calendar.timegm(data.utctimetuple())
Esse exemplo descarta microssegundos. Para preservar precisão subsegundo, use data.timestamp() ou acrescente a fração separadamente.
Cuidados com datetime sem fuso
Um datetime sem tzinfo é chamado de naive. Ele não informa se representa UTC, horário de Brasília ou qualquer outro fuso. Converter esse valor como UTC sem conhecer sua origem pode deslocar o instante real.
from datetime import datetime, timezone
naive = datetime(2026, 9, 14, 9, 0)
consciente = naive.replace(tzinfo=timezone.utc)
replace não converte o horário; apenas declara que os números já representam UTC. Se os números representam um horário local, use uma zona real com zoneinfo antes de converter.
Conversão com 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())
Esse caminho é mais seguro quando a entrada está associada a uma região. Ele considera regras históricas e possíveis mudanças de offset. Depois que o instante está em UTC, você pode trabalhar com timestamps sem depender do fuso do servidor.
Uso em APIs
APIs frequentemente recebem datas ISO 8601 e armazenam timestamps. Uma estratégia segura é validar o texto, criar um objeto consciente de fuso e converter para segundos.
from datetime import datetime
texto = "2026-09-14T12:00:00+00:00"
data = datetime.fromisoformat(texto)
timestamp = int(data.timestamp())
Use calendar.timegm quando a biblioteca ou protocolo já entregar uma tupla UTC. Evite transformar textos locais em tuplas e tratá-los como UTC sem conversão explícita.
Datas antes de 1970
Em muitos sistemas modernos, a função pode retornar timestamps negativos para datas anteriores à época Unix. Entretanto, o suporte exato pode variar conforme a plataforma e o intervalo de datas. Aplicações portáveis devem testar os limites usados pelo negócio.
Segundos bissextos
O timestamp Unix tradicional não representa segundos bissextos de maneira direta. A biblioteca padrão segue o comportamento do sistema e normalmente trabalha com uma linha temporal contínua sem expor o segundo 60 como um instante especial. Não use a função como ferramenta de astronomia ou cronometria de altíssima precisão.
Validação de entrada
Valores impossíveis, como mês 13 ou dia incompatível, devem ser rejeitados antes de chegar às camadas críticas. Uma forma clara é construir um datetime, que valida os componentes.
from datetime import datetime, timezone
try:
data = datetime(2026, 2, 30, tzinfo=timezone.utc)
except ValueError as erro:
print("Data inválida", erro)
Em entradas externas, nunca confie em números sem validação. Defina limites de ano, confirme o fuso esperado e registre erros de parsing com contexto suficiente para diagnóstico.
Testes determinísticos
Testes de data ficam mais confiáveis quando usam valores fixos em UTC. Compare o resultado com um timestamp conhecido e faça também a conversão inversa.
import calendar
import time
def test_timegm_roundtrip():
origem = (2026, 9, 14, 12, 0, 0, 0, 0, 0)
timestamp = calendar.timegm(origem)
resultado = time.gmtime(timestamp)
assert resultado[:6] == origem[:6]
Evite testes dependentes do fuso local da máquina de CI. A principal vantagem de timegm é justamente tornar a interpretação UTC explícita.
Precisão e microssegundos
A função trabalha com segundos inteiros. Se sua aplicação registra eventos em microssegundos, preserve a fração em um campo separado ou use datetime.timestamp(), que retorna ponto flutuante. Em sistemas financeiros ou científicos, considere armazenar inteiros em milissegundos ou nanossegundos para evitar erros de arredondamento.
Uso em logs e filas
Um timestamp UTC simplifica a ordenação de eventos vindos de diferentes regiões. Produtores podem converter seus horários para UTC antes de publicar, e consumidores podem formatar o instante no fuso do usuário apenas na apresentação.
evento = {
"tipo": "processamento_concluido",
"timestamp": calendar.timegm((2026, 9, 14, 12, 0, 0))
}
Documente a unidade usada. Alguns sistemas esperam segundos, outros milissegundos. Um valor correto na unidade errada produz datas absurdas e é um erro comum em integrações.
Erros comuns
Os erros mais frequentes são tratar horário local como UTC, usar mktime em dados universais, perder microssegundos sem perceber, assumir que uma tupla possui informação de fuso, misturar segundos e milissegundos e confiar no fuso configurado no servidor.
Boas práticas
Mantenha instantes internos em UTC, use objetos conscientes de fuso nas fronteiras, converta horários regionais com zoneinfo, documente a unidade do timestamp, valide datas externas e prefira funções explícitas. Use calendar.timegm quando a entrada realmente for uma estrutura UTC.
Links internos recomendados
Veja também os guias da Academify sobre datetime no Python, zoneinfo no Python, módulo time e datas no Python.
Referências externas
Consulte a documentação oficial de calendar.timegm e a documentação oficial de datetime para detalhes de compatibilidade e comportamento.
Conclusão
calendar.timegm resolve um problema específico de forma simples: converter componentes de data e hora interpretados como UTC em um timestamp Unix. Ela evita a dependência do fuso local que existe em time.mktime e combina bem com estruturas produzidas por time.gmtime. Para código novo, objetos datetime conscientes de fuso oferecem mais contexto, mas timegm continua sendo uma ferramenta clara, rápida e útil em integrações, logs, protocolos e APIs baseadas em tuplas UTC.
