Comprendre le module Datetime de Python
Apprenez à travailler avec les dates et heures en Python grâce au module datetime : date, time, timedelta, strftime, strptime et fuseaux horaires.
Python ne possède pas de type de date natif dédié. En revanche, le module datetime de la bibliothèque standard fournit une boîte à outils complète pour créer, manipuler, formater et analyser des dates et des heures. Ce chapitre couvre toutes les classes principales — date, time, datetime, timedelta et timezone — et présente des modèles pratiques que vous utiliserez régulièrement.
Importation du module
Le module datetime fait partie de la bibliothèque standard et ne nécessite aucune installation. Vous pouvez l'importer de deux façons courantes :
# Import the module and qualify every name
import datetime
today = datetime.date.today()
# Import specific classes directly
from datetime import date, time, datetime, timedelta, timezone
today = date.today()Le style from datetime import ... est plus court en pratique et est utilisé tout au long de ce chapitre.
La classe date
date représente une date du calendrier (année, mois, jour) sans composante horaire.
Création d'objets date
Accès aux attributs d'une date
Une fois que vous disposez d'un objet date, vous pouvez lire son année, son mois et son jour comme attributs entiers, et demander quel jour de la semaine il correspond :
from datetime import date
d = date(2024, 6, 15)
print(d.year) # 2024
print(d.month) # 6
print(d.day) # 15
# weekday(): Monday = 0, Sunday = 6
print(d.weekday()) # 5 (Saturday)
# isoweekday(): Monday = 1, Sunday = 7
print(d.isoweekday()) # 6 (Saturday)La classe time
time représente une heure de la journée (heure, minute, seconde, microseconde) indépendamment de toute date particulière.
from datetime import time
# time(hour, minute, second) — all arguments optional, default to 0
t = time(14, 30, 0)
print(t) # 14:30:00
print(t.hour) # 14
print(t.minute) # 30
print(t.second) # 0La classe time est particulièrement utile lorsque vous devez stocker ou comparer des heures sans vous soucier de la date, par exemple « rappelle-moi à 09:00 chaque jour ».
La classe datetime
datetime est la classe de référence. Elle combine une date complète et une heure en un seul objet, et c'est celle que vous utiliserez dans la plupart de vos programmes réels.
Obtenir la date et l'heure actuelles
from datetime import datetime
# Local system time (naive — no time zone)
now = datetime.now()
print(now) # e.g. 2024-06-15 14:30:45.123456
# UTC time
utc_now = datetime.utcnow()
print(utc_now) # e.g. 2024-06-15 18:30:45.123456Création d'objets datetime
from datetime import datetime, date, time
# Constructor: datetime(year, month, day, hour=0, minute=0, second=0)
dt = datetime(2024, 6, 15, 14, 30, 45)
print(dt) # 2024-06-15 14:30:45
# From an ISO 8601 string
dt2 = datetime.fromisoformat("2024-06-15T14:30:45")
print(dt2) # 2024-06-15 14:30:45
# Combine a date and a time object
combined = datetime.combine(date(2024, 6, 15), time(14, 30, 0))
print(combined) # 2024-06-15 14:30:00Accès aux attributs d'un datetime
datetime expose tous les attributs de date et de time :
from datetime import datetime
dt = datetime(2024, 6, 15, 14, 30, 45)
print(dt.year) # 2024
print(dt.month) # 6
print(dt.day) # 15
print(dt.hour) # 14
print(dt.minute) # 30
print(dt.second) # 45
# Extract just the date or time part
print(dt.date()) # 2024-06-15
print(dt.time()) # 14:30:45La classe timedelta
timedelta représente une durée — la différence entre deux points dans le temps. Vous l'utilisez pour ajouter ou soustraire des intervalles de temps à des objets date et datetime.
Création et utilisation de timedelta
from datetime import date, timedelta
today = date(2024, 6, 15)
# Add 30 days
future = today + timedelta(days=30)
print(future) # 2024-07-15
# Subtract 7 days
last_week = today - timedelta(weeks=1)
print(last_week) # 2024-06-08
# timedelta can express days, seconds, and microseconds
# Convenience arguments: days, seconds, microseconds, milliseconds, minutes, hours, weeks
delta = timedelta(hours=2, minutes=30)
print(delta) # 2:30:00Calcul de la différence entre deux dates
La soustraction d'un objet date ou datetime d'un autre renvoie un timedelta :
from datetime import date
start = date(2024, 1, 1)
end = date(2024, 6, 15)
diff = end - start
print(diff) # 166 days, 0:00:00
print(diff.days) # 166C'est la méthode standard pour calculer le nombre de jours entre deux dates. Utilisez .total_seconds() sur un timedelta si vous avez besoin de l'intervalle en secondes.
Formatage des dates et heures (strftime)
strftime (« string format time») convertit un objet date ou datetime en une chaîne lisible par l'homme. Vous passez une chaîne de format contenant des directives commençant par %.
from datetime import datetime
dt = datetime(2024, 6, 15, 14, 30, 45)
print(dt.strftime("%Y-%m-%d")) # 2024-06-15
print(dt.strftime("%d/%m/%Y")) # 15/06/2024
print(dt.strftime("%A, %B %d, %Y")) # Saturday, June 15, 2024
print(dt.strftime("%I:%M %p")) # 02:30 PM
print(dt.strftime("%Y-%m-%d %H:%M:%S")) # 2024-06-15 14:30:45Directives strftime courantes
| Directive | Signification | Exemple |
|---|---|---|
%Y | Année sur 4 chiffres | 2024 |
%y | Année sur 2 chiffres | 24 |
%m | Mois en nombre avec zéro initial | 06 |
%B | Nom complet du mois | June |
%b | Nom abrégé du mois | Jun |
%d | Jour du mois avec zéro initial | 15 |
%A | Nom complet du jour de la semaine | Saturday |
%a | Nom abrégé du jour de la semaine | Sat |
%H | Heure (horloge 24 heures) | 14 |
%I | Heure (horloge 12 heures) | 02 |
%M | Minute | 30 |
%S | Seconde | 45 |
%p | AM ou PM | PM |
%j | Jour de l'année | 167 |
%W | Numéro de semaine de l'année | 24 |
Analyse syntaxique des dates et heures (strptime)
strptime (« string parse time») est l'inverse de strftime : il convertit une chaîne en objet datetime. Vous devez fournir une chaîne de format correspondant à la saisie.
Un piège fréquent : strptime renvoie toujours un datetime, même si la chaîne ne contient qu'une date. Appelez .date() sur le résultat si vous avez besoin d'un objet date simple.
Format ISO 8601
Le standard ISO 8601 (YYYY-MM-DDTHH:MM:SS) est la façon la plus portable d'échanger des valeurs de date et d'heure. Python dispose d'assistants intégrés pour cela :
from datetime import datetime
dt = datetime(2024, 6, 15, 14, 30, 45)
# Produce ISO 8601 string
print(dt.isoformat()) # 2024-06-15T14:30:45
# Parse ISO 8601 string (Python 3.7+)
dt2 = datetime.fromisoformat("2024-06-15T14:30:45")
print(dt2) # 2024-06-15 14:30:45Travailler avec les horodatages
Un horodatage Unix est le nombre de secondes écoulées depuis le 1er janvier 1970 00:00:00 UTC. Python peut convertir entre des horodatages et des objets datetime :
Fuseaux horaires
Par défaut, datetime.now() renvoie un datetime naïf — sans information de fuseau horaire. L'ajout d'un objet tzinfo le rend conscient. Les datetimes conscients sont essentiels lorsque votre programme gère des utilisateurs dans plusieurs fuseaux horaires ou stocke des horodatages dans une base de données.
Utilisation du timezone intégré
datetime.timezone fournit timezone.utc et permet de créer des zones à décalage fixe :
from datetime import datetime, timezone, timedelta
# Create an aware UTC datetime
utc_dt = datetime(2024, 6, 15, 14, 30, 45, tzinfo=timezone.utc)
print(utc_dt) # 2024-06-15 14:30:45+00:00
# Create a fixed +5:30 (India Standard Time) offset
ist_offset = timezone(timedelta(hours=5, minutes=30))
ist_dt = utc_dt.astimezone(ist_offset)
print(ist_dt) # 2024-06-15 20:00:45+05:30Utilisation de zoneinfo (Python 3.9+)
Pour les vrais fuseaux horaires IANA comme America/New_York ou Asia/Tokyo, utilisez le module intégré zoneinfo (Python 3.9+). Il gère automatiquement l'heure d'été.
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
# UTC aware datetime
utc_dt = datetime(2024, 6, 15, 14, 30, 45, tzinfo=timezone.utc)
# Convert to Eastern Time (handles DST automatically)
eastern = ZoneInfo("America/New_York")
eastern_dt = utc_dt.astimezone(eastern)
print(eastern_dt) # 2024-06-15 10:30:45-04:00
# Convert to Tokyo time
tokyo = ZoneInfo("Asia/Tokyo")
tokyo_dt = utc_dt.astimezone(tokyo)
print(tokyo_dt) # 2024-06-15 23:30:45+09:00Sur Python 3.8 et antérieur, installez la bibliothèque tierce pytz pour la prise en charge des zones IANA.
Remplacement de composants
replace() renvoie un nouvel objet avec des champs spécifiques modifiés. L'original n'est jamais modifié.
from datetime import datetime
dt = datetime(2024, 6, 15, 14, 30, 45)
# Change only the year
dt2 = dt.replace(year=2025)
print(dt2) # 2025-06-15 14:30:45
# Change hour and minute
dt3 = dt.replace(hour=9, minute=0, second=0)
print(dt3) # 2024-06-15 09:00:00Comparaison des dates et heures
Les objets date et datetime prennent en charge tous les opérateurs de comparaison standard :
from datetime import date
d1 = date(2024, 1, 1)
d2 = date(2024, 6, 15)
print(d1 < d2) # True
print(d1 == d2) # False
# Find the earliest date
earliest = min(d1, d2)
print(earliest) # 2024-01-01Comparez uniquement des datetimes conscients avec des datetimes conscients, et des datetimes naïfs avec des naïfs — les mélanger lève une TypeError.
Mise en pratique
Voici un exemple pratique qui combine plusieurs concepts : il calcule combien de jours restent avant une échéance future et formate les deux dates pour l'affichage.
from datetime import date
deadline = date(2024, 12, 31)
today = date(2024, 6, 15)
days_left = (deadline - today).days
print(f"Today: {today.strftime('%B %d, %Y')}") # June 15, 2024
print(f"Deadline: {deadline.strftime('%B %d, %Y')}") # December 31, 2024
print(f"Days remaining: {days_left}") # 199Référence rapide
| Tâche | Code |
|---|---|
| Date d'aujourd'hui | date.today() |
| Date et heure actuelles | datetime.now() |
| Date spécifique | date(2024, 6, 15) |
| Date depuis une chaîne | datetime.strptime(s, fmt) |
| Date vers une chaîne | dt.strftime(fmt) |
| Format ISO | dt.isoformat() / datetime.fromisoformat(s) |
| Ajouter/soustraire des jours | d + timedelta(days=N) |
| Jours entre deux dates | (d2 - d1).days |
| Convertir un fuseau horaire | dt.astimezone(ZoneInfo("Zone/Name")) |