Timedelta Python: como trabalhar com intervalos de tempo em Python

Muitos conjuntos de dados reais incluem datas e horas, e uma operação comum na ciência de dados é calcular a diferença de tempo entre dois momentos no tempo.

As unidades que usamos para medir datas e horas (anos, meses, dias, horas, minutos, segundos) não são as mais fáceis de trabalhar, sobretudo quando essas unidades têm dimensões irregulares.

No entanto, o tipo de dados timedelta do Python, que faz parte do módulo datetime, lida com a complexidade de trabalhar com intervalos de tempo.

Vamos começar com uma resposta bem curta sobre o que é o timedelta do Python e, em seguida, continuar com mais detalhes.

Para saber mais sobre datas e horas em Python, confira este curso sobre Como Trabalhar com Datas e Horas em Python.

Resposta curta: o que é o timedelta do Python?

Os dois tipos de dados mais importantes e usados com frequência no módulo datetime são timedelta e datetime. Enquanto os objetos datetime representam momentos específicos no tempo (ex.: 1º de janeiro de 2024 às 10h30), os objetos timedelta representam durações ou intervalos entre dois momentos. Pense nisso como a diferença entre perguntar "Quando?" (datetime) e "Por quanto tempo?" (timedelta).

Considere duas datas, que podem ser representadas por meio de dois objetos datetime. Ao subtrair uma data de outra, é criado um objeto timedelta que representa o intervalo de tempo entre as datas:

import datetime

first_date = datetime.datetime(year=2024, month=1, day=1)
second_date = datetime.datetime(year=2024, month=5, day=27)
interval = second_date - first_date
print(interval)

147 days, 0:00:00

O resultado mostra que as duas datas têm exatamente 147 dias de diferença. No exemplo a seguir, usamos a data e a hora em que o código é executado chamando datetime.datetime.now():

first_date = datetime.datetime(year=2024, month=1, day=1)
second_date = datetime.datetime.now()
interval = second_date - first_date

print(second_date)
print(interval)

2024-05-28 08:32:44.871646
148 days, 8:32:44.871646

Agora o objeto timedelta mostra o tempo decorrido entre o início de 2024 e a data e hora em que o código é executado.

Neste artigo, vamos analisar melhor o timedelta do Python.

Criação de objetos timedelta

Na seção anterior, criamos um objeto timedelta a partir de dois objetos datetime, mas também podemos criar um intervalo de tempo diretamente chamando o construtor timedelta():

interval = datetime.timedelta(days=10, seconds=3600)
print(interval)

10 days, 1:00:00

O intervalo é de dez dias e uma hora. Também podemos usar outras unidades de tempo ao criar uma instância do timedelta:

interval = datetime.timedelta(weeks=1, days=3, hours=1)
print(interval)

10 days, 1:00:00

Qualquer uma das unidades de tempo a seguir é válida quando ao chamar timedelta():

• semanas
• dias
• horas
• minutos
• segundos
• milissegundos
• microssegundos

Este tutorial aborda mais detalhadamente como os intervalos de tempo são armazenados em um objeto timedelta.

Aritmética básica com timedelta

Também podemos fazer operações aritméticas com objetos timedelta. Considere os três objetos datetime a seguir, que representam as datas de lançamento do Python 1.0, Python 2.0 e Python 3.0. Quando um objeto datetime é subtraído de outro, é criado um objeto timedelta:

release_date_python_1 = datetime.datetime(year=1991, month=2, day=20)
release_date_python_2 = datetime.datetime(year=2000, month=10, day=16)
release_date_python_3 = datetime.datetime(year=2008, month=12, day=3)

​time_between_1_and_2 = release_date_python_2 - release_date_python_1
time_between_2_and_3 = release_date_python_3 - release_date_python_2

​print(time_between_1_and_2)
print(time_between_2_and_3)

3526 days, 0:00:00
2970 days, 0:00:00

A saída mostra o número de dias entre as versões do Python 1.0 e 2.0 e entre as versões do Python 2.0 e 3.0. Os intervalos de tempo são objetos timedelta.

Também é possível fazer a soma e a subtração de objetos timedelta e objetos datetime. Vamos somar um timedelta com days=100 a release_date_python_3:

print(release_date_python_3 + datetime.timedelta(days=100))

2009-03-13 00:00:00

O Python 3.0 foi lançado em 3 de dezembro de 2008. Ao somar 100 dias a essa data, obtemos 13 de março de 2009.

No entanto, também podemos fazer operações aritméticas diretamente com os objetos timedelta:

print("Difference between gap 1 and gap 2")
print(time_between_1_and_2 - time_between_2_and_3)

print("Sum of gap 1 and gap 2")
print(time_between_1_and_2 + time_between_2_and_3)

Difference between gap 1 and gap 2
556 days, 0:00:00

Sum of gap 1 and gap 2
6496 days, 0:00:00

O resultado confirma que é possível subtrair e adicionar objetos timedelta. Também é possível fazer operações de multiplicação e divisão:

print("Multiply time interval by 3:")
print(time_between_1_and_2 * 3)

print("Divide time interval by 3:")
print(time_between_1_and_2 / 3)

Multiply time interval by 3:
10578 days, 0:00:00

Divide time interval by 3:
1175 days, 8:00:00

Podemos ainda comparar objetos timedelta:

print("Check if gap 1 is greater than gap 2")
print(time_between_1_and_2 > time_between_2_and_3)

True

O resultado confirma que o intervalo entre as datas de lançamento do Python 1.0 e do Python 2.0 é maior do que o intervalo entre o Python 2.0 e o Python 3.0.

Principais atributos e métodos do timedelta

Um objeto timedelta representa um intervalo de tempo armazenando o número de dias, segundos e microssegundos. Essas são as três únicas unidades de tempo representadas por atributos na classe timedelta:

interval = datetime.timedelta(
    weeks=1,
    hours=10,
    minutes=22,
    milliseconds=1042,
)

print(f"{interval = }")
print(f"{interval.days = }")
print(f"{interval.seconds = }")
print(f"{interval.microseconds = }")

interval = datetime.timedelta(days=7, seconds=37321, microseconds=42000)
interval.days = 7
interval.seconds = 37321
interval.microseconds = 42000

Embora a chamada para timedelta() inclua argumentos para semanas, horas, minutos e milissegundos, o construtor converte essas unidades em dias, segundos e microssegundos. As chamadas de print() incluem f-strings com sinal de igual = para exibir o nome da variável e seu valor. Para saber mais sobre f-strings, confira este tutorial sobre formatação de f-strings em Python.

Outra ferramenta útil da classe timedelta é o método total_seconds(). Esse método retorna o intervalo de tempo total em segundos:

print("Total time interval in seconds:")
print(interval.total_seconds())

Total time interval in seconds:
642121.042

Esse valor representa o intervalo de tempo total em segundos. Não é o mesmo que o valor de .seconds, que mostra apenas o componente de segundos do intervalo, sem levar em conta os dias e os microssegundos.

Você pode usar o valor retornado por .total_seconds() para converter o intervalo de tempo em qualquer outra unidade:

print("Total time interval in days:")
print(interval.total_seconds() / 3600 / 24)

Total time interval in days:
7.431956504629629

O resultado mostra o intervalo de tempo em dias, já que o valor retornado por .total_seconds() é dividido pelo número de segundos em uma hora e pelo número de horas em um dia.

Exemplo do timedelta: cálculo do crescimento

Vejamos um exemplo. A loja online de uma empresa que vende livros sobre Python registra todas as vendas. Estes são os dados de um cliente:

data = {
    "customer_id": 3542,
    "sales": [
        {"date": "2024-04-21T13:23:45", "price": 24.99, "quantity": 1},
        {"date": "2024-02-13T10:54:12", "price": 24.99, "quantity": 2},
        {"date": "2024-01-08T20:32:24", "price": 18.99, "quantity": 1},
    ],
}

Precisamos calcular a diferença de tempo entre o primeiro e o último pedidos de um cliente. Os pedidos estão sempre em ordem cronológica na lista que contém todas as vendas.

A primeira etapa é extrair as datas dessa estrutura aninhada e convertê-las em objetos datetime. Por sorte, os registros de data e hora estão no formato padrão ISO 8601 (AAAA-MM-DDTHH:MM:SS), portanto podemos usar o conveniente método fromisoformat():

sales = data["sales"]
dates = []
for item in sales:
    date = datetime.datetime.fromisoformat(item["date"])
    dates.append(date)

print(dates)

[datetime.datetime(2024, 4, 21, 13, 23, 45), datetime.datetime(2024, 2, 13, 10, 54, 12), datetime.datetime(2024, 1, 8, 20, 32, 24)]

A lista dates contém objetos datetime com as datas de cada pedido. Por fim, podemos calcular o intervalo de tempo entre o primeiro e o último pedidos:

time_span = dates[0] - dates[-1]
print(time_span)
print(time_span.days)

103 days, 16:51:21
103

A diferença entre a primeira e a última data fornece um objeto timedelta. O código exibe time_span, que mostra o número de dias, horas, minutos e segundos. Também exibimos time_span.days para mostrar apenas o número total de dias.

Se quiser saber mais sobre a conversão de strings em datetime, confira este tutorial sobre Python: de string para datetime.

Dicas rápidas ao usar o timedelta

Vamos dar uma olhada em algumas questões a ter em mente ao usar o timedelta do Python:

1. É melhor usar argumentos de palavras-chave ao chamar timedelta() para evitar erros com unidades:

interval = datetime.timedelta(weeks=1, days=3, hours=1, milliseconds=1354)

2. Ao calcular um intervalo de tempo entre duas datas em fusos horários diferentes, timedelta converte as datas em datas UTC antes de calcular a diferença de horário:

import zoneinfo

some_date = datetime.datetime.fromisoformat("2024-01-01T00:00:00")

some_date_lon = some_date.replace(tzinfo=zoneinfo.ZoneInfo("Europe/London"))
some_date_nyc = some_date.replace(tzinfo=zoneinfo.ZoneInfo("America/New_York"))

print(some_date_lon)
print(some_date_nyc)
print(some_date_nyc - some_date_lon)

2024-01-01 00:00:00+00:00
2024-01-01 00:00:00-05:00
5:00:00

A data em some_date mostra o início do novo ano. Esse é um objeto datetime ingênuo, pois não tem informações sobre o fuso horário. Entretanto, some_date_lon e some_date_nyc são objetos datetime conscientes, pois representam o início do ano novo em Londres e Nova York, respectivamente.

O timedelta obtido pela subtração dos dois objetos datetime conscientes mostra um intervalo de tempo de cinco horas, que é a diferença de horário UTC.

3. Diferenças no horário de verão não são levadas em conta pelo timedelta:

nyc = zoneinfo.ZoneInfo("America/New_York")

first_time = datetime.datetime.strptime("2024-03-10 1:00am", "%Y-%m-%d %I:%M%p")
first_time = first_time.replace(tzinfo=nyc)

second_time = datetime.datetime.strptime("2024-03-10 3:00am", "%Y-%m-%d %I:%M%p")
second_time = second_time.replace(tzinfo=nyc)

time_difference = second_time - first_time
print("Time difference between the first and second time:")
print(time_difference)

print("Checking the DST status of the first and second time:")
print(f"{first_time.dst() = }")
print(f"{second_time.dst() = }")

Time difference between the first and second time:
2:00:00

Checking the DST status of the first and second time:
first_time.dst() = datetime.timedelta(0)
second_time.dst() = datetime.timedelta(seconds=3600)

Os dois horários representam 1h00 e 3h00 do dia 3 de março de 2024, em Nova York. O horário de verão começou às 2h da manhã no mesmo dia em que os relógios passaram para as 3h. A diferença entre os dois horários resulta em um timedelta que representa duas horas, embora apenas uma hora tenha se passado entre os dois horários devido ao início do horário de verão.

Podemos converter em UTC se precisarmos do intervalo real decorrido:

first_time_utc = first_time.astimezone(zoneinfo.ZoneInfo("UTC"))
second_time_utc = second_time.astimezone(zoneinfo.ZoneInfo("UTC"))
time_difference_utc = second_time_utc - first_time_utc

print("Actual time difference between the first and second time:")
print(time_difference_utc)

Actual time difference between the first and second time:
1:00:00

A conversão em UTC antes de subtrair os objetos datetime fornece o tempo real entre os dois objetos datetime.

Conclusão

A classe timedelta do Python oferece métodos fáceis para lidar com intervalos de tempo, simplificando o trabalho com períodos de tempo em várias unidades. Analisamos como criar objetos timedelta e fazer operações aritméticas com eles, como adição, subtração, multiplicação e divisão.

Você pode ler mais sobre como lidar com datas e horas nos artigos a seguir:

• Folha de dicas para trabalhar com datas e horas em Python
• De string para datetime em Python: como converter strings em objetos datetime em Python
• Como trabalhar com datas e horas em Python