timedelta Python: Trabajar con intervalos de tiempo en Python

Muchos conjuntos de datos reales incluyen fechas y horas, y una operación habitual en la ciencia de datos es calcular la diferencia temporal entre dos puntos.

Las unidades que utilizamos para medir fechas y horas (años, meses, días, horas, minutos, segundos) no son las más fáciles para trabajar, sobre todo cuando estas unidades tienen duraciones irregulares.

Sin embargo, el tipo de datos timedelta de Python, que forma parte del módulo datetime, se ocupa de las complejidades de calcular intervalos de tiempo.

Empecemos con una respuesta muy breve sobre qué es timedelta de Python y continuemos con más detalles.

Para aprender más sobre fechas y horas en Python, consulta este curso sobre Cómo trabajar con fechas y horas en Python.

Respuesta corta: Qué es timedelta de Python

Los dos tipos de datos más importantes y utilizados del módulo datetime son timedelta y datetime. Mientras que los objetos datetime representan puntos temporales concretos (por ejemplo, 1 de enero de 2024 a las 10:30 h), los objetos timedelta representan duraciones o intervalos entre dos puntos. Es la diferencia entre preguntar "¿Cuándo?" (datetime) y "¿Cuánto tiempo?" (timedelta).

Tenemos dos fechas, que podemos representar utilizando dos objetos datetime. Al restar una fecha a otra, se crea un objeto timedelta que representa el intervalo de tiempo entre las fechas:

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

El resultado muestra que las dos fechas están separadas exactamente por 147 días. En el siguiente ejemplo, utilizamos la fecha y la hora de ejecución del código llamando a 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

El objeto timedelta muestra ahora el tiempo transcurrido entre el inicio de 2024 y la fecha y la hora de ejecución del código.

En este artículo exploraremos más a fondo timedelta de Python.

Creación de objetos timedelta

En el apartado anterior, creamos un objeto timedelta a partir de dos objetos datetime, pero también podemos crear un intervalo de tiempo directamente llamando al constructor timedelta():

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

10 days, 1:00:00

El intervalo es de diez días y una hora. También podemos utilizar otras unidades de tiempo al crear una instancia de timedelta:

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

10 days, 1:00:00

Cualquiera de las siguientes unidades de tiempo es válida al llamar a timedelta():

• semanas
• días
• horas
• minutos
• segundos
• milisegundos
• microsegundos

Este tutorial profundizará en cómo se almacenan los intervalos de tiempo en un objeto timedelta.

Aritmética básica con timedelta

También podemos realizar operaciones aritméticas con los objetos timedelta. Tenemos los tres objetos datetime indicados a continuación, que representan las fechas de publicación de Python 1.0, Python 2.0 y Python 3.0. Si se restan los objetos datetime unos a otros, se crea un 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

El resultado muestra el número de días transcurridos entre las publicaciones de Python 1.0 y 2.0 y entre las publicaciones de Python 2.0 y 3.0. Los intervalos de tiempo son objetos timedelta.

También es posible realizar sumas y restas entre objetos timedelta y objetos datetime. Añadamos timedelta con days=100 a release_date_python_3:

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

2009-03-13 00:00:00

Python 3.0 se publicó el 3 de diciembre de 2008. Si añadimos cien días a esta fecha, llegaremos al 13 de marzo de 2009.

Sin embargo, también podemos realizar operaciones aritméticas directamente con los 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

El resultado confirma que es posible restar y sumar objetos timedelta. También son posibles la multiplicación y la división:

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

También podemos 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

El resultado confirma que el intervalo entre las fechas de publicación de Python 1.0 y Python 2.0 es mayor que el intervalo entre Python 2.0 y Python 3.0.

Atributos y métodos clave de timedelta

Un objeto timedelta representa un intervalo de tiempo almacenando el número de días, segundos y microsegundos. Estas tres unidades son las únicas unidades de tiempo representadas por atributos en la clase 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

Aunque la llamada a timedelta() incluye argumentos para semanas, horas, minutos y milisegundos, el constructor convierte estas unidades a días, segundos y microsegundos. Las llamadas a print() incluyen f-strings con un signo de igual a (=) para mostrar el nombre de la variable y su valor. Puedes aprender más sobre las f-strings en este tutorial sobre el formato de f-strings en Python.

Otra herramienta útil de la clase timedelta es el método total_seconds(). Este método devuelve el intervalo de tiempo total en segundos:

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

Total time interval in seconds:
642121.042

Este valor representa el intervalo de tiempo total en segundos. No es lo mismo que el valor de .seconds, que solo muestra el componente de segundos del intervalo, sin tener en cuenta los días ni los microsegundos.

Podemos utilizar el valor devuelto por .total_seconds() para convertir el intervalo de tiempo en cualquier otra unidad:

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

Total time interval in days:
7.431956504629629

El resultado muestra el intervalo de tiempo en días, ya que el valor devuelto por .total_seconds() se divide entre el número de segundos de una hora y el número de horas de un día.

Ejemplo de timedelta: Cálculo del crecimiento

Veamos un ejemplo. La tienda online de una empresa que vende libros sobre Python registra todas las ventas. Aquí tienes los datos de un 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},
    ],
}

Tenemos que calcular la diferencia temporal entre el primer y el último pedido de un cliente. Los pedidos aparecen siempre en orden cronológico en la lista que contiene todas las ventas.

Nuestro primer paso es extraer las fechas de esta estructura anidada y convertirlas en objetos datetime. Afortunadamente, las marcas de tiempo están en el formato estándar ISO 8601 (AAAA-MM-DDTHH:MM:SS), por lo que podemos utilizar el cómodo 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)]

La lista dates contiene objetos datetime con las fechas de cada pedido. Por último, podemos calcular el intervalo de tiempo entre el primer y el último pedido:

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

103 days, 16:51:21
103

La diferencia entre la primera y la última fecha da un objeto timedelta. El código muestra time_span, que indica el número de días, horas, minutos y segundos. También mostramos time_span.days para mostrar solo el número entero de días.

Si quieres saber más sobre la conversión de cadenas a datetime, consulta este tutorial sobre conversión de cadenas de Python a Datetime.

Consejos rápidos para utilizar timedelta

Veamos algunas cosas que hay que tener en cuenta al utilizar timedelta de Python:

1. Lo mejor es utilizar argumentos de palabra clave al llamar a timedelta() para evitar errores con las unidades:

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

2. Cuando se encuentra un intervalo de tiempo entre dos fechas de zonas horarias diferentes, timedelta convierte las fechas a fechas UTC antes de calcular la diferencia temporal:

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

La fecha en some_date indica el comienzo del nuevo año. Se trata de un objeto datetime ingenuo, ya que no tiene información sobre la zona horaria. Sin embargo, some_date_lon y some_date_nyc son objetos datetime conscientes, ya que representan el comienzo del nuevo año en Londres y Nueva York, respectivamente.

El timedelta obtenido restando los dos objetos datetime conscientes muestra un intervalo de tiempo de cinco horas, que es la diferencia horaria UTC.

3. Los cambios de horario de verano no se tienen en cuenta en 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)

Las dos horas representan la 1:00 a. m. y las 3:00 a. m. del 3 de marzo de 2024 en Nueva York. El horario de verano comenzó a las 2:00 a. m. del mismo día, cuando los relojes pasaron a las 3:00 a. m. La diferencia entre las dos horas da un timedelta que representa dos horas aunque solo haya pasado una hora entre las dos horas debido al inicio del horario de verano.

Podemos convertir a UTC si necesitamos el tiempo real transcurrido:

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

La conversión a UTC antes de restar los objetos de datetime da la hora real entre los dos objetos datetime.

Conclusión

La clase timedelta de Python ofrece métodos sencillos para manejar intervalos de tiempo, lo que facilita el trabajo con periodos de tiempo en diferentes unidades. Hemos explorado cómo crear objetos timedelta y realizar operaciones aritméticas con ellos, como sumas, restas, multiplicaciones y divisiones.

Puedes leer más sobre el manejo de fechas y horas en los siguientes artículos:

• Hoja de trucos Trabajar con fechas y horas en Python
• Conversión de cadenas de Python a DateTime: Cómo convertir cadenas en objetos DateTime en Python
• Trabajar con fechas y horas en Python