Python timedelta : Travailler avec des intervalles de temps en Python

De nombreux ensembles de données du monde réel comprennent des dates et des heures, et une opération courante en science des données consiste à calculer la différence de temps entre deux points dans le temps.

Les unités que nous utilisons pour mesurer les dates et les heures (années, mois, jours, heures, minutes, secondes) ne sont pas les plus faciles à utiliser, surtout lorsque ces unités ont des longueurs irrégulières.

Cependant, le type de données timedelta de Python, qui fait partie du module datetime, gère la complexité des intervalles de temps.

Commençons par une réponse très courte sur ce qu'est Python timedelta et poursuivons avec plus de détails.

Pour en savoir plus sur les dates et les heures en Python, consultez ce cours sur le travail avec les dates et l'heure en Python.

Réponse courte : Qu'est-ce que le timedelta de Python ?

Les deux types de données les plus importants et les plus fréquemment utilisés du module datetime sont timedelta et datetime. Alors que les objets datetime représentent des points spécifiques dans le temps (par exemple, le 1er janvier 2024 à 10h30), les objets timedelta représentent des durées ou des intervalles entre deux points. Pensez à la différence entre la question "Quand ?" (datetime) et la question "Combien de temps ?" (timedelta).

Considérons deux dates, que nous pouvons représenter à l'aide de deux objets datetime. La soustraction d'une date à une autre crée un objet timedelta représentant l'intervalle de temps entre les dates :

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

Le résultat montre que les deux dates sont exactement à 147 jours d'intervalle. Dans l'exemple suivant, nous utilisons la date et l'heure d'exécution du code en appelant 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

L'objet timedelta indique maintenant le temps écoulé entre le début de 2024 et la date et l'heure d'exécution du code.

Nous explorerons plus en détail le site timedelta de Python dans cet article.

Création d'objets timedelta

Dans la section précédente, nous avons créé un objet timedelta à partir de deux objets datetime, mais nous pouvons également créer un intervalle de temps directement en appelant le constructeur timedelta():

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

10 days, 1:00:00

L'intervalle est de dix jours et une heure. Nous pouvons également utiliser d'autres unités de temps lors de la création d'une instance timedelta:

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

10 days, 1:00:00

Toutes les unités de temps suivantes sont valables lorsque vous appelez timedelta():

• semaines
• jours
• heures
• minutes
• secondes
• millisecondes
• microsecondes

Ce tutoriel vous permettra d'approfondir la manière dont les intervalles de temps sont stockés dans un objet timedelta.

Arithmétique de base avec timedelta

Nous pouvons également effectuer des opérations arithmétiques avec les objets timedelta. Considérez les trois objets datetime suivants, représentant les dates de publication de Python 1.0, Python 2.0 et Python 3.0. En soustrayant les objets datetime les uns des autres, on obtient un objet 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

Le résultat indique le nombre de jours entre les versions de Python 1.0 et 2.0 et entre les versions de Python 2.0 et 3.0. Les intervalles de temps sont des objets timedelta.

Il est également possible d'effectuer des additions et des soustractions entre les objets timedelta et datetime. Ajoutons un timedelta avec days=100 à release_date_python_3:

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

2009-03-13 00:00:00

Python 3.0 a été publié le 3 décembre 2008. En ajoutant cent jours à cette date, nous arrivons au 13 mars 2009.

Cependant, nous pouvons également effectuer des opérations arithmétiques directement avec les objets 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

Le résultat confirme qu'il est possible de soustraire et d'ajouter des objets timedelta. La multiplication et la division sont également possibles :

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

Nous pouvons également comparer les objets timedelta:

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

True

Le résultat confirme que l'intervalle entre les dates de publication de Python 1.0 et Python 2.0 est plus long que l'intervalle entre Python 2.0 et Python 3.0.

Attributs et méthodes clés de timedelta

Un objet timedelta représente un intervalle de temps en stockant le nombre de jours, de secondes et de microsecondes. Ces trois unités sont les seules unités de temps représentées par des attributs dans la 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

Même si l'appel à timedelta() comprend des arguments pour les semaines, les heures, les minutes et les millisecondes, le constructeur convertit ces unités en jours, secondes et microsecondes. Les appels à print() comprennent des chaînes f avec un signe égal = pour afficher le nom de la variable et sa valeur. Vous pouvez en savoir plus sur les chaînes f dans ce tutoriel sur le formatage des chaînes f en Python.

Un autre outil utile de la classe timedelta est la méthode total_seconds(). Cette méthode renvoie l'intervalle de temps total en secondes :

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

Total time interval in seconds:
642121.042

Cette valeur représente l'ensemble de l'intervalle de temps en secondes. Ce n'est pas la même chose que la valeur de .seconds, qui n'indique que la composante secondes de l'intervalle sans tenir compte des jours et des microsecondes.

Nous pouvons utiliser la valeur renvoyée par .total_seconds() pour convertir l'intervalle de temps en toute autre unité :

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

Total time interval in days:
7.431956504629629

La sortie indique l'intervalle de temps en jours puisque la valeur renvoyée par .total_seconds() est divisée par le nombre de secondes dans une heure et le nombre d'heures dans un jour.

timedelta Exemple : Calcul de la croissance

Prenons un exemple. La boutique en ligne d'une entreprise qui vend des livres Python enregistre toutes les ventes. Voici les données d'un client :

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},
    ],
}

Nous devons calculer la différence de temps entre la première et la dernière commande d'un client. Les commandes sont toujours classées par ordre chronologique dans la liste contenant toutes les ventes.

Notre première étape consiste à extraire les dates de cette structure imbriquée et à les convertir en objets datetime. Heureusement, les horodatages sont au format standard ISO 8601 (YYYY-MM-DDTHH:MM:SS), ce qui nous permet d'utiliser la méthode pratique 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 liste dates contient les objets datetime avec les dates de chaque commande. Enfin, nous pouvons calculer l'intervalle de temps entre la première et la dernière commande :

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

103 days, 16:51:21
103

La différence entre la première et la dernière date donne un objet timedelta. Le code affiche time_span, qui indique le nombre de jours, d'heures, de minutes et de secondes. Nous affichons également time_span.days pour ne montrer que le nombre entier de jours.

Si vous voulez en savoir plus sur la conversion de chaînes de caractères en dates, consultez ce tutoriel sur la conversion de chaînes de caractères en dates en Python.

Conseils rapides pour l'utilisation de timedelta

Examinons quelques points à garder à l'esprit lors de l'utilisation de Python timedelta:

1. Il est préférable d'utiliser des arguments de type mot-clé lorsque vous appelez timedelta() afin d'éviter les erreurs avec les unités :

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

2. Lorsque vous recherchez un intervalle de temps entre deux dates situées dans des fuseaux horaires différents, timedelta convertit les dates en dates UTC avant de calculer le décalage horaire :

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 date sur some_date indique le début de la nouvelle année. Il s'agit d'un objet datetime naïf puisqu'il ne contient pas d'informations sur le fuseau horaire. Cependant, some_date_lon et some_date_nyc sont des objets connus de datetime puisqu'ils représentent le début de la nouvelle année à Londres et à New York respectivement.

Le site timedelta obtenu en soustrayant les deux objets conscients datetime montre un intervalle de temps de cinq heures, ce qui correspond à la différence de temps UTC.

3. Les changements d'heure d'été ne sont pas pris en compte par 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)

Les deux heures représentent 1 heure et 3 heures du matin le 3 mars 2024 à New York. L'heure d'été a commencé à 2 heures du matin le même jour où les horloges sont passées à 3 heures. La différence entre les deux heures donne un timedelta qui représente deux heures alors qu'il ne s'est écoulé qu'une heure entre les deux heures en raison du début de l'heure d'été.

Nous pouvons convertir en UTC si nous avons besoin du temps réel écoulé :

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

En convertissant en UTC avant de soustraire les objets datetime, on obtient le temps réel entre les deux objets datetime.

Conclusion

La classe timedelta de Python propose des méthodes simples pour gérer les intervalles de temps, ce qui facilite le travail avec des périodes de temps dans différentes unités. Nous avons appris à créer des objets timedelta et à effectuer des opérations arithmétiques avec eux, notamment l'addition, la soustraction, la multiplication et la division.

Pour en savoir plus sur la gestion des dates et des heures, consultez les articles suivants :

• Travailler avec des dates et des heures en Python - Aide-mémoire
• Chaîne Python vers DateTime : Comment convertir des chaînes de caractères en objets DateTime en Python
• Travailler avec des dates et des heures en Python