Eu estou consultando uma API e ela me retorna a data da seguinte forma:
"timestamp":"1444253422.348340958"
Como converter essa informação em data e hora utilizando Python?
Este número é um timestamp, que representa a quantidade de tempo decorrida a partir do Unix Epoch (1970-01-01T00:00Z
- 1 de janeiro de 1970 à meia-noite em UTC).
Normalmente usa-se um valor em segundos ou milissegundos, e no seu caso, está em segundos. Ou seja, é um valor que representa 1.444.253.422,348340958 segundos depois do Unix Epoch. (se estivesse em milissegundos, corresponderia a uma data em 1970, então acho mais provável que esteja em segundos mesmo).
Como você quer transformar isso em uma data e hora, há um detalhe que deve levar em conta. O timestamp representa um ponto na linha do tempo: um único instante que é o mesmo no mundo todo. Só que este mesmo instante corresponde a uma data e hora diferentes, dependendo do timezone (fuso-horário). Por exemplo, o timestamp 1444253422.348340958
corresponde aos seguintes dias e horários:
Repare que o horário é diferente em cada parte do mundo, e em Tóquio até mesmo o dia é diferente (interessante notar também que em Londres não é o mesmo horário que UTC - um mito comum - pois neste dia a Inglaterra estava em horário de verão).
Portanto, se você quer converter um timestamp para uma data e hora específicas, você precisa saber qual timezone será utilizado.
datetime
e pytz
Usando o módulo datetime
, é possível converter o timestamp para uma data e hora. E para trabalhar com timezones, até o Python 3.8, sugiro o módulo pytz
, que possui suporte aos timezones da IANA (logo mais explico a solução para Python >= 3.9 e porque estes são melhores do que usar timedelta
).
Mas antes você precisa transformar a string "1444253422.348340958"
em número. Como não é um número inteiro, podemos usar float
, sem esquecer de capturar o ValueError
caso a string não seja um número.
Em seguida eu uso datetime.fromtimestamp
, passando dois parâmetros:
float
diretamente)from datetime import datetime
from pytz import timezone
try:
# converter string para número
timestamp = float("1444253422.348340958")
# converter o timestamp para uma data e hora em um timezone específico
dt = datetime.fromtimestamp(timestamp, tz = timezone("Asia/Tokyo"))
print(dt) # 2015-10-08 06:30:22.348341+09:00
# se quiser mostrar em outro formato
print(dt.strftime("%d/%m/%Y %H:%M:%S.%f %z")) # 08/10/2015 06:30:22.348341 +0900
# converter para outro timezone
dt = dt.astimezone(timezone("Europe/London"))
print(dt) # 2015-10-07 22:30:22.348341+01:00
print(dt.strftime("%d/%m/%Y %H:%M:%S.%f %z")) # 07/10/2015 22:30:22.348341 +0100
except ValueError:
print("não foi possível converter o valor do timestamp para um número")
Neste exemplo eu usei Asia/Tokyo
, o que fez com que a data e hora fosse "8 de outubro de 2015 às 06:30.22.348341" (a API possui precisão de microssegundos, ou seja, os 3 últimos dígitos da fração de segundos são perdidos). Em seguida eu converti para Europe/London
, o que mudou tanto o dia quanto a hora (isso é para mostrar que o mesmo timestamp de fato corresponde a uma data e hora diferentes, dependendo do timezone utilizado). Repare também nos valores +09:00
e +01:00
: estes são os offsets (a diferença com relação a UTC), que no caso indicam que estes horários estão respectivamente 9 horas e 1 hora à frente do UTC.
E se eu não especificar o timezone no método fromtimestamp
?
print(datetime.fromtimestamp(timestamp))
Na minha máquina o resultado foi 2015-10-07 18:30:22.348341
, mas este resultado pode variar de acordo com o timezone default utilizado internamente (no meu caso, pelo valor retornado, parece ser America/Sao_Paulo
- o timezone correspondente ao horário oficial de Brasília). Mas rodando no Ideone.com, por exemplo, o resultado foi 2015-10-07 21:30:22.348341
(pois provavelmente lá o timezone está configurado como UTC).
Por isso é importante passar um timezone específico, pois o timestamp corresponde a uma data e hora diferentes em cada lugar do mundo. Ao usar fromtimestamp
e sem especificar um timezone, você perde o controle sobre a data/hora retornada.
Os nomes de timezones, como America/Sao_Paulo
, Europe/London
e Asia/Tokyo
, seguem o padrão da IANA, e você pode ver a lista completa usando all_timezones
:
import pytz
print(pytz.all_timezones)
Isso imprime uma lista com vários nomes (mais de 500), e você pode escolher o mais adequado para a sua situação. Para o horário oficial de Brasília, você pode usar America/Sao_Paulo
(que possui inclusive as regras do horário de verão), mas caso queira o fuso do Nordeste (que atualmente não usa horário de verão) pode usar America/Recife
ou America/Bahia
, por exemplo. A IANA disponibiliza seus arquivos no GitHub, então você também pode consultar todos os timezones do Brasil (todas as linhas que começam com "BR" neste arquivo) e escolher o que precisa.
O próprio pytz
também possui esta informação. Basta acessar o dicionário country_timezones
, passando como chave o código do país (duas letras, de acordo com a ISO 3166). No caso, o código do Brasil é "BR", então para saber todos os timezones do Brasil, basta fazer:
print(pytz.country_timezones['BR'])
Isso retorna uma lista com todos os nomes de timezones do Brasil. Na versão que estou usando atualmente (pytz 2018.7), o retorno foi:
['America/Noronha', 'America/Belem', 'America/Fortaleza', 'America/Recife', 'America/Araguaina', 'America/Maceio', 'America/Bahia', 'America/Sao_Paulo', 'America/Campo_Grande', 'America/Cuiaba', 'America/Santarem', 'America/Porto_Velho', 'America/Boa_Vista', 'America/Manaus', 'America/Eirunepe', 'America/Rio_Branco']
Escolha o que melhor se adequar ao que você precisa. Exemplo:
dt = datetime.fromtimestamp(timestamp, tz = timezone("America/Sao_Paulo"))
print(dt) # 2015-10-07 18:30:22.348341-03:00
# se quiser mostrar em outro formato
print(dt.strftime("%d/%m/%Y %H:%M:%S.%f %z")) # 07/10/2015 18:30:22.348341 -0300
Neste caso, eu obtive a data e hora no horário de Brasília (America/Sao_Paulo
).
A partir do Python 3.9 você pode usar o módulo zoneinfo
, que já vem instalado nativamente e possui suporte aos timezones da IANA. O código acima ficaria praticamente igual, bastando substituir o timezone
do pytz
por ZoneInfo
:
from datetime import datetime
from zoneinfo import ZoneInfo
try:
# converter string para número
timestamp = float("1444253422.348340958")
# converter o timestamp para uma data e hora em um timezone específico
dt = datetime.fromtimestamp(timestamp, tz = ZoneInfo("Asia/Tokyo"))
print(dt) # 2015-10-08 06:30:22.348341+09:00
# se quiser mostrar em outro formato
print(dt.strftime("%d/%m/%Y %H:%M:%S.%f %z")) # 08/10/2015 06:30:22.348341 +0900
# converter para outro timezone
dt = dt.astimezone(ZoneInfo("Europe/London"))
print(dt) # 2015-10-07 22:30:22.348341+01:00
print(dt.strftime("%d/%m/%Y %H:%M:%S.%f %z")) # 07/10/2015 22:30:22.348341 +0100
# usar o timezone do Horário de Brasília
dt = datetime.fromtimestamp(timestamp, tz = ZoneInfo("America/Sao_Paulo"))
print(dt) # 2015-10-07 18:30:22.348341-03:00
# se quiser mostrar em outro formato
print(dt.strftime("%d/%m/%Y %H:%M:%S.%f %z")) # 07/10/2015 18:30:22.348341 -0300
except ValueError:
print("não foi possível converter o valor do timestamp para um número")
E para ver todos os timezones disponíveis, basta usar zoneinfo.available_timezones
:
from zoneinfo import available_timezones
print(available_timezones())
timedelta
Uma das respostas sugere o uso de timedelta
para subtrair 3 horas da data e com isso obter o "fuso horário brasileiro". Isso só funciona se fromtimestamp
retornar a data e hora em UTC (o que já vimos que não é garantido se você não especificar o timezone), e se o timestamp corresponde a uma data/hora em que o Brasil não está em horário de verão (pois durante o horário de verão o offset passa a ser de -02:00
, então deveriam ser subtraídas somente 2 horas).
O problema é que é muito difícil determinar o valor exato a ser subtraído de UTC, já que as regras do horário de verão mudam o tempo todo. No Brasil, por exemplo: até 2017, o horário de verão começava no terceiro domingo de outubro, mas a partir de 2018, passou a começar no primeiro domingo de novembro. E será assim "para sempre", ou seja, até que mude de novo - aliás, já mudou, o Brasil não terá horário de verão em 2019 (e será assim até que mude de novo).
Além disso, não é todo o país que adotava o horário de verão. No momento em que escrevo esta resposta (dezembro de 2018), os estados do Nordeste não adotam, então eles usam o offset -03:00
o ano todo. Já os estados do Sul/Sudeste usam -03:00
durante parte do ano, e no horário de verão mudam para -02:00
. E os estados do Centro-oeste usam -03:00
no horário de verão e -04:00
no horário "normal". Mas no Norte (Amazonas/Pará/etc), atualmente não adotam o horário de verão e usam -04:00
o ano todo, exceto pelo Acre, que usa -05:00
o ano todo (mas já mudou essas regras várias vezes). E não esqueça de Fernando de Noronha, que usa o offset -02:00
o ano todo.
Enfim, usar valores fixos de timedelta
(como -3
, ou qualquer outro valor) é impreciso porque é preciso saber de todas essas regras (se determinada região tem horário de verão, quando começa e termina, quais os offsets usados, etc), e mesmo "o horário brasileiro" é algo difícil de definir, já que depende de qual região você está se referindo. E é aí que entra a IANA: ela possui um banco de dados que já tem todo esse histórico e você não precisa se preocupar com isso. Tudo que você precisa é saber o identificador do timezone que quer usar (os nomes America/Sao_Paulo
, Europe/London
, etc).
Usando estes identificadores, como por exemplo America/Sao_Paulo
, ele já saberá se no instante que o timestamp representa, aquela região está ou não em horário de verão e usará o offset correto (sem você precisar "adivinhar" e subtrair/somar timedeltas
arbitrários).
Isso é importante porque estas regras mudam mais do que imaginamos. Atualmente America/Recife
não adota o horário de verão, mas nos anos 80 adotava. E nada garante que isso não mudará no futuro, já que estas regras são definidas por governos/leis e nem sempre com justificativas técnicas. É comum justificativas como "Quero que o povo tenha mais horas de sol", e até mesmo o argumento de economia de energia e demais vantagens e desvantagens é debatido em vários lugares, e a todo momento, em algum lugar do mundo, há alguém discutindo se deveria mudar ou não o horário de verão (ou seja, a única certeza que temos é que estas regras mudam o tempo todo).
Agora que o Brasil cancelou o horário de verão, é tentador achar que podemos usar um valor fixo de timedelta
, mas nada garante que no futuro o governo não volte a adotá-lo. Mesmo que demore para acontecer, usar um timezone é bem mais garantido, pelos motivos já explicados acima.
Por isso há uma grande vantagem em usar o pytz
, pois ele é atualizado conforme a IANA lança novas versões do seu banco, e estas atualizações ficam disponíveis no PyPI. Inclusive, eles já estão cientes que o Brasil não vai ter horário de verão em 2019 e já foi lançada uma nova versão contendo esta mudança.
O uso de timedelta
é uma solução que "parece" certa porque muitos não consideram todas as regras envolvendo timezones, e acham que um valor fixo de offset é o suficiente.
Só que um offset não é o mesmo que um timezone: o offset é apenas um valor numérico fixo (a diferença com relação a UTC, como +09:00
ou -03:00
), enquanto um timezone (como America/Sao_Paulo
ou Europe/London
) possui todo o histórico de offsets de uma determinada região (os valores do offset quando é horário de verão e quando não é, os instantes exatos em que ocorrem estas mudanças, etc). Para mais informações, veja a seção "Diferenças entre timezone e offset" na descrição da tag timezone.
Use o módulo datetime
.
Exemplo:
from datetime import datetime
ts = int("1284101485")
print(datetime.utcfromtimestamp(ts).strftime('%Y-%m-%d %H:%M:%S'))
Fonte: SO - Converting unix timestamp string to readable date
Este formato de data se chama Unix time. É o número de segundos passados desde 01/01/1970 emm UTC/GMT.
Usando a biblioteca datetime você pode fazer esta conversão. Você vai transformar esse valor em um objeto data que pode ser manipulado de várias formas usando o datetime. A data pode ser convertida para BRT utilizando métodos do datetime, mas aconselho fazer a conversão você mesmo. Ver observação
from datetime import datetime
from datetime import timedelta
objeto_data = datetime.fromtimestamp(1444253422.348340958)
print(objeto_data)
data_br = objeto_data - timedelta(hours=3) #Cuidado com esta conversão. Leia a observação abaixo.
print(data_br) #imprimir desse jeito fica horrivel, mas voce pode separar cada informacao e imprimir como quiser
texto = str(data_br.day) + "/" + str(data_br.month) + "/" + str(data_br.year) + " BRT " + str(data_br.hour) + ":" + str(data_br.minute)
print(texto)
Este provavelmente não é o melhor modo de imprimir a data e hora, mas o importante é você converter o valor em Unix time para um objeto de data manipulável. Com isto você tem toda a flexibilidade da biblioteca datetime.
-------------------------------------------------------------------
OBS: Caso necessite de utilizar fuso horário, veja a resposta abaixo a respeito da biblioteca pytz
timedelta
nem sempre trará o "horário brasileiro" correto, veja minha resposta para mais detalhes. Resumindo, fromtimestamp
usa o timezone default da máquina e nem sempre será UTC. Na minha máquina, por exemplo, o resultado deste código foi 7/10/2015 BRT 15:30
(sendo que o timestamp em questão corresponde a 18:30 no horário de Brasília)
timedelta
nem sempre funcionará corretamente. Se o timestamp recebido corresponder a uma data que cai no horário de verão, e/ou se o servidor estiver configurado com um timezone que não seja UTC, usar otimedelta
trará resultados incorretos - veja a minha resposta para mais detalhes.