Utiliser correctement datetime et timezone dans Django

Aperçu

La gestion des dates et heures peut facilement engendrer des bugs en raison de petites différences. Cet article passe en revue rapidement les concepts souvent confus de naive/aware, ISO8601, timestamp(UNIX epoch) dans Django et Python, et présente des exemples de leur utilisation sécuritaire.

Les deux visages de datetime : naive vs aware

Les objets datetime se divisent en deux catégories selon la présence d'informations sur le fuseau horaire.

• naive : objet sans information de fuseau horaire (tzinfo=None)

• aware : objet incluant des informations de fuseau horaire (tzinfo=...)

Les règles d'opération sont simples. Seules des opérations d'addition et de soustraction peuvent être effectuées entre objets du même type.

• naive - naive ✅ (possible)

• aware - aware (même fuseau horaire) ✅ (possible)

• naive - aware ❌ (TypeError se produit)

from datetime import datetime, timezone

# naive : aucune information de fuseau horaire
naive = datetime(2025, 11, 14, 9, 25, 1)                 # tzinfo=None

# aware : spécifie l'information de fuseau horaire (dans ce cas UTC)
aware = datetime(2025, 11, 14, 9, 25, 1, tzinfo=timezone.utc)

_ = aware - datetime.now(timezone.utc)  # OK (aware - aware)
# _ = aware - datetime.now()            # TypeError (aware - naive)

Timezone et USE_TZ dans Django

La configuration USE_TZ dans le settings.py de Django est importante.

• USE_TZ=True (recommandé) : django.utils.timezone.now() retourne un objet aware basé sur UTC.

• USE_TZ=False : retourne un objet naive basé sur l'heure locale du serveur.

La plupart des applications web doivent être configurées avec USE_TZ=True, et toutes les logiques internes et le stockage de la base de données doivent être uniformisés en UTC. Ce n'est qu'au moment de l'affichage à l'utilisateur qu'une conversion en heure locale doit être effectuée.

from django.utils import timezone

# Lorsque USE_TZ=True, now() retourne toujours un objet aware UTC
now = timezone.now()

ISO8601 et isoformat()

La méthode datetime.isoformat() génère une chaîne conforme à la norme ISO8601.

• Les objets aware en UTC incluent généralement un décalage comme 2025-11-14T09:25:01+00:00.

• Z est une autre notation signifiant UTC (+00:00). (Exemple : ...T09:25:01Z)

Piège important : La fonction datetime.fromisoformat() de la bibliothèque standard Python ne peut pas parser directement le suffixe Z. Si vous devez gérer cette notation, il est prudent d'utiliser django.utils.dateparse.parse_datetime().

from datetime import datetime, timezone
from django.utils.dateparse import parse_datetime

dt = datetime(2025, 11, 14, 9, 25, 1, tzinfo=timezone.utc)
s  = dt.isoformat()                      # '2025-11-14T09:25:01+00:00'

_aware = datetime.fromisoformat(s)       # OK
_aware2 = parse_datetime("2025-11-14T09:25:01Z")  # OK (utilitaire Django)

Comprendre correctement le timestamp (UNIX epoch)

Timestamp définit la durée écoulée depuis 1970-01-01 00:00:00 UTC (UNIX epoch) en secondes.

• Partie entière : "secondes" écoulées depuis le point de référence

• Partie décimale : précision en sous-secondes (microsecondes)

La fonction time.time() de Python renvoie le nombre de secondes actuelles dans l'epoch UTC. La méthode .timestamp() des objets datetime utilise également la même référence d'epoch UTC.

import time
from datetime import datetime, timezone

# L'epoch à l'heure actuelle (les deux valeurs ont en réalité le même sens)
t1 = time.time()
t2 = datetime.now(timezone.utc).timestamp()

# Conversion mutuelle entre un temps spécifique ↔ epoch
exp_ts = 1731576301.25  # partie décimale de 0.25 seconde (250ms)
exp_dt = datetime.fromtimestamp(exp_ts, tz=timezone.utc)  # aware UTC
back_ts = exp_dt.timestamp()  # 1731576301.25

Le timestamp est utile pour échanger des données entre serveurs ou pour calculer des durées d'expiration, lorsqu'une opération numérique est nécessaire. Cela permet d'éviter les problèmes de parsing de chaîne de caractères de fuseau horaire.

Modèles de conversion/calcul sécurisés (exemples)

1. Chaîne (ISO8601) → datetime

Pour traiter en toute sécurité le suffixe Z ou divers décalages, utilisez parse_datetime.

from django.utils.dateparse import parse_datetime
from django.utils import timezone

s = "2025-11-14T09:25:01Z"  # ou ...+00:00
dt = parse_datetime(s)

if dt is None:
    raise ValueError("Chaîne de datetime invalide")

# Si l'heure analysée est naive (absence d'informations de décalage)
if timezone.is_naive(dt):
    # Spécifiez explicitement le fuseau horaire selon la règle d'entreprise (par exemple, supposé UTC)
    from zoneinfo import ZoneInfo
    dt = timezone.make_aware(dt, ZoneInfo("UTC"))

2. datetime (aware) ↔ timestamp

Il est clair que la conversion devrait toujours être basée sur timezone.utc.

from datetime import datetime, timezone

dt = datetime(2025, 11, 14, 9, 25, 1, tzinfo=timezone.utc)
ts = dt.timestamp()                               # float
dt2 = datetime.fromtimestamp(ts, tz=timezone.utc) # conversion réciproque OK

3. Calcul du temps restant jusqu'à l'expiration (en secondes)

Soustrayez deux objets aware pour obtenir un timedelta, puis utilisez .total_seconds().

from datetime import datetime, timezone

exp = datetime(2025, 11, 14, 9, 25, 1, tzinfo=timezone.utc)
now = datetime.now(timezone.utc)

remaining = (exp - now).total_seconds()  # secondes en float (peut être négatif)

Essentiel : Toutes les opérations doivent être effectuées sur des objets aware (de préférence UTC) pour une plus grande sécurité. Note : le paramètre tz|tzinfo passé à datetime() doit être timezone.utc et non pas django.utils.timezone.

Pièges courants et moyens de les éviter rapidement

• Opérations aware - naive : génèrent une TypeError.

  • → unifiez-les soit en aware (idéalement UTC), soit en naive tout en prenant conscience de leur signification.

• fromisoformat() et suffixe "Z" :

  • → la bibliothèque standard ne supporte pas Z. Utilisez parse_datetime() de Django ou remplacez Z par +00:00.

• Dépendance à l'heure locale (datetime.now()) :

  • → cela peut engendrer des bugs en raison de variations de temps selon l'environnement de déploiement (local, serveur de développement, production). La logique interne doit toujours être construite sur UTC (timezone.now()).

Conclusion

• Le premier principe des opérations temporelles est de ne pas mélanger naive et aware. Unifiez-les de préférence en aware (UTC).

• Lors de la gestion de chaînes, utilisez le format ISO8601, mais pour le parsing, privilégiez parse_datetime() capable de traiter Z.

• Pour les opérations numériques telles que le calcul du temps d'expiration, utilisez timestamp.