Parcourir les aide-mémoire · Python
Manipuler des dates et des horodatages
Analysez, comparez, filtrez, normalisez, localisez, convertissez, regroupez et validez des dates et des horodatages avec pandas sans introduire d’erreurs de fuseau horaire ou de bornes.
Sur cette page
- Problème
- Réponse rapide
- Code / commandes
- 1. Analyser une colonne datetime
- 2. Analyser explicitement un format connu
- 3. Analyser directement les horodatages en UTC
- 4. Vérifier si une colonne datetime a un fuseau horaire
- 5. Localiser des horodatages naïfs dans le fuseau horaire de la source
- 6. Convertir des horodatages avec fuseau horaire
- 7. Gérer délibérément les ambiguïtés liées à l’heure d’été
- 8. Filtrer une journée complète en toute sécurité
- 9. Filtrer un mois complet en toute sécurité
- 10. Filtrer des horodatages avec fuseau horaire avec des bornes cohérentes
- 11. Filtrer selon la date locale métier
- 12. Extraire les composantes d’une date
- 13. Ramener les horodatages à minuit
- 14. Convertir en valeurs date Python
- 15. Arrondir les horodatages à l’intervalle inférieur
- 16. Arrondir les horodatages
- 17. Regrouper par jour avec pd.Grouper
- 18. Regrouper par mois
- 19. Calculer des écarts de temps
- 20. Ajouter des décalages temporels
- 21. Trier par horodatage
- 22. Obtenir la ligne la plus récente par entité
- 23. Obtenir l’horodatage de l’événement précédent
- 24. Comparer en toute sécurité des horodatages provenant de sources différentes
- 25. Utiliser merge_asof pour les jointures sur périodes de validité
- 26. Limiter l’écart temporel des correspondances avec une tolérance
- 27. Trouver les dates invalides ou manquantes après l’analyse
- 28. Vérifier la plage de dates après l’analyse
- 29. Vérifier les horodatages en double au sein d’une clé métier
- Interpréter le résultat
- Points à vérifier
- De nombreuses valeurs deviennent NaT
- L’horodatage semble décalé de plusieurs heures
- Les totaux journaliers diffèrent d’un système à l’autre
- Des lignes de fin de journée sont manquantes
- La durée est étonnamment inférieure à un jour
- Les changements d’heure produisent des heures locales ambiguës ou manquantes
- Notes de production
- Stockez les horodatages d’événements en UTC lorsque c’est possible
- Ne perdez pas l’information de fuseau horaire trop tôt
- Les dates seules et les horodatages sont des concepts différents
- Les intervalles semi-ouverts évitent les bugs de borne
- L’analyse peut être coûteuse
- La conversion de fuseau horaire peut changer les dates de reporting
- L’arithmétique calendaire diffère des durées fixes
- Erreurs fréquentes
- 1. Comparer des chaînes de dates au lieu d’horodatages analysés
- 2. Utiliser tz_localize() alors que vous voulez tz_convert()
- 3. Marquer des horodatages locaux comme UTC
- 4. Filtrer jusqu’à 23:59:59
- 5. Utiliser .dt.date trop tôt
- 6. Utiliser .dt.seconds pour des durées complètes
- 7. Ignorer les changements d’heure
- 8. Regrouper par jour des horodatages UTC pour un rapport en heure locale métier
- 9. Écraser les échecs d’analyse sans les inspecter
- Étape suivante
- Pour aller plus loin
Problème
Les dates et les horodatages semblent simples jusqu’à ce que les données de production contiennent :
- plusieurs formats
- des valeurs invalides
- des horodatages avec et sans fuseau horaire (aware et naïfs)
- de l’heure UTC et de l’heure locale mélangées
- des bugs de borne en fin de journée
- des changements d’heure (heure d’été)
- des rapports à la date seule mélangés à des horodatages d’événements précis
- des jointures avec des données de référence datées par période de validité
L’objectif est de traiter le temps de façon explicite afin que les filtres, les regroupements, les comparaisons, les jointures et les rapports restent corrects.
Vous devez répondre aux questions suivantes :
- La colonne est-elle réellement de type datetime ?
- Quelles lignes n’ont pas pu être analysées ?
- Les horodatages sont-ils avec fuseau horaire ou naïfs ?
- Le fuseau horaire de la source est-il connu ?
- Les données doivent-elles être stockées en UTC ?
- Les bornes des plages de dates sont-elles inclusives ou exclusives ?
- Les périodes de regroupement reposent-elles sur l’heure UTC ou sur l’heure locale métier ?
Réponse rapide
Analysez délibérément :
df["event_time"] = pd.to_datetime(
df["event_time"],
errors="coerce",
)
Inspectez les échecs d’analyse :
failed = df.loc[
df["event_time"].isna()
]
Filtrez un mois avec un intervalle semi-ouvert :
start = pd.Timestamp("2026-10-01")
end = pd.Timestamp("2026-11-01")
october = df.loc[
(df["event_time"] >= start)
& (df["event_time"] < end)
]
Pour des données de production avec fuseau horaire, normalisez en UTC :
df["event_time"] = pd.to_datetime(
df["event_time"],
utc=True,
errors="coerce",
)
Ne convertissez ensuite en heure locale que lorsque la règle métier l’exige.
Code / commandes
1. Analyser une colonne datetime
df["event_time"] = pd.to_datetime(
df["event_time"],
errors="coerce",
)
errors="coerce" convertit les valeurs invalides en NaT.
C’est utile lors de l’ingestion, car les mauvaises valeurs deviennent visibles au lieu de lever une erreur et de tout arrêter immédiatement.
N’écrasez pas la colonne source avant d’avoir inspecté les échecs de conversion si le texte d’origine compte pour le débogage.
Plus sûr pendant l’investigation :
parsed = pd.to_datetime(
df["event_time"],
errors="coerce",
)
failed = df.loc[
df["event_time"].notna()
& parsed.isna()
]
print(failed)
2. Analyser explicitement un format connu
Si le format d’entrée est stable, précisez-le.
df["event_date"] = pd.to_datetime(
df["event_date"],
format="%Y-%m-%d",
errors="coerce",
)
Pour les horodatages :
df["event_time"] = pd.to_datetime(
df["event_time"],
format="%Y-%m-%d %H:%M:%S",
errors="coerce",
)
Les formats explicites rendent l’intention plus claire et aident à détecter des changements inattendus dans la source.
3. Analyser directement les horodatages en UTC
df["event_time"] = pd.to_datetime(
df["event_time"],
utc=True,
errors="coerce",
)
Utilisez cette approche lorsque :
- les horodatages de la source incluent déjà des décalages de fuseau horaire
- la source est documentée comme étant en UTC
- vous voulez une représentation cohérente avec fuseau horaire
Soyez prudent lorsque vous analysez des horodatages locaux naïfs avec utc=True.
Si le texte source représente une heure locale (heure affichée par l’horloge), localisez-le d’abord au lieu de faire comme s’il était en UTC.
4. Vérifier si une colonne datetime a un fuseau horaire
print(df["event_time"].dtype)
Exemples :
datetime64[ns]
signifie sans fuseau horaire (naïf).
datetime64[ns, UTC]
signifie avec fuseau horaire, en UTC.
Vous pouvez aussi inspecter :
print(df["event_time"].dt.tz)
Pour une Series datetime naïve, cela renvoie None.
5. Localiser des horodatages naïfs dans le fuseau horaire de la source
Supposons que les valeurs sources représentent l’heure locale de New York :
df["event_time"] = (
pd.to_datetime(
df["event_time"],
errors="coerce",
)
.dt.tz_localize("America/New_York")
)
Utilisez tz_localize() lorsque les horodatages sont naïfs mais que leur fuseau horaire réel est connu.
N’utilisez pas tz_convert() sur des horodatages naïfs.
6. Convertir des horodatages avec fuseau horaire
Une fois que les horodatages ont un fuseau horaire :
df["event_time_local"] = (
df["event_time"]
.dt.tz_convert("America/New_York")
)
Utilisez tz_convert() pour représenter le même instant dans un autre fuseau horaire.
L’instant reste le même ; seule la représentation affichée en heure locale change.
7. Gérer délibérément les ambiguïtés liées à l’heure d’été
La localisation peut rencontrer des heures locales ambiguës ou inexistantes.
Exemple :
localized = (
pd.to_datetime(df["event_time"], errors="coerce")
.dt.tz_localize(
"America/New_York",
ambiguous="NaT",
nonexistent="NaT",
)
)
C’est plus sûr pour l’investigation que de deviner en silence.
Inspectez les lignes concernées avant de choisir une règle de production.
8. Filtrer une journée complète en toute sécurité
Pour des horodatages précis, préférez un intervalle semi-ouvert.
start = pd.Timestamp("2026-10-04")
end = pd.Timestamp("2026-10-05")
day_rows = df.loc[
(df["event_time"] >= start)
& (df["event_time"] < end)
]
Cela inclut chaque horodatage du 4 octobre sans dépendre d’un 23:59:59.999999 artificiel.
9. Filtrer un mois complet en toute sécurité
start = pd.Timestamp("2026-10-01")
end = pd.Timestamp("2026-11-01")
october = df.loc[
(df["event_time"] >= start)
& (df["event_time"] < end)
]
Ce modèle est robuste pour les horodatages avec une précision inférieure à la seconde.
10. Filtrer des horodatages avec fuseau horaire avec des bornes cohérentes
Si la Series est en UTC avec fuseau horaire :
start = pd.Timestamp(
"2026-10-01",
tz="UTC",
)
end = pd.Timestamp(
"2026-11-01",
tz="UTC",
)
filtered = df.loc[
(df["event_time"] >= start)
& (df["event_time"] < end)
]
Ne comparez pas des horodatages avec fuseau horaire à des bornes sans fuseau horaire.
11. Filtrer selon la date locale métier
Supposons que les horodatages sont stockés en UTC, mais que les rapports doivent utiliser les jours calendaires de New York.
Convertissez avant de dériver la date locale :
local_time = (
df["event_time"]
.dt.tz_convert("America/New_York")
)
df["local_date"] = local_time.dt.date
Filtrez ensuite :
filtered = df.loc[
df["local_date"]
== pd.Timestamp("2026-10-04").date()
]
C’est important pour les événements proches de minuit UTC.
12. Extraire les composantes d’une date
df["year"] = df["event_time"].dt.year
df["month"] = df["event_time"].dt.month
df["day"] = df["event_time"].dt.day
df["hour"] = df["event_time"].dt.hour
df["weekday"] = df["event_time"].dt.day_name()
Utile pour :
- les rapports
- l’ingénierie des variables (feature engineering)
- le filtrage
- l’analyse par heure de la journée
Ne matérialisez pas de façon permanente des composantes que vous pouvez dériver à faible coût, sauf si elles sont nécessaires en aval.
13. Ramener les horodatages à minuit
df["event_date"] = (
df["event_time"]
.dt.normalize()
)
Pour les horodatages avec fuseau horaire, le fuseau horaire est conservé.
Utilisez cette approche lorsque vous avez besoin d’une clé de jour de type datetime plutôt que d’objets date Python.
14. Convertir en valeurs date Python
df["event_date"] = (
df["event_time"]
.dt.date
)
Cela produit des objets date Python et donne généralement une Series de type object.
Pour les opérations temporelles natives de pandas, .dt.normalize() ou .dt.floor("D") conservent souvent un dtype datetime plus utile.
15. Arrondir les horodatages à l’intervalle inférieur
Par heure :
df["event_hour"] = (
df["event_time"]
.dt.floor("h")
)
Par jour :
df["event_day"] = (
df["event_time"]
.dt.floor("D")
)
Utilisez cette approche pour répartir des horodatages exacts dans des intervalles de rapport.
16. Arrondir les horodatages
df["rounded_time"] = (
df["event_time"]
.dt.round("15min")
)
N’arrondissez que lorsque l’intervalle le plus proche est vraiment la règle voulue.
Pour les intervalles de rapport, l’arrondi inférieur (floor) est souvent plus prévisible.
17. Regrouper par jour avec pd.Grouper
daily = (
df.groupby(
pd.Grouper(
key="event_time",
freq="D",
)
)
.agg(
events=("event_id", "count"),
revenue=("revenue", "sum"),
)
.reset_index()
)
La clé temporelle reste ainsi de type datetime.
18. Regrouper par mois
monthly = (
df.groupby(
pd.Grouper(
key="event_time",
freq="MS",
)
)
.agg(
events=("event_id", "count"),
revenue=("revenue", "sum"),
)
.reset_index()
)
MS désigne une fréquence de début de mois.
Utilisez ME lorsque vous voulez explicitement des libellés de fin de mois, dans une version de pandas qui prend en charge cet alias.
19. Calculer des écarts de temps
df["processing_time"] = (
df["completed_at"]
- df["started_at"]
)
Résultat :
timedelta64[ns]
Convertir en secondes :
df["processing_seconds"] = (
df["processing_time"]
.dt.total_seconds()
)
N’utilisez pas .dt.seconds lorsque vous avez besoin de la durée complète.
.dt.seconds ne représente que la composante des secondes à l’intérieur de la journée.
20. Ajouter des décalages temporels
df["expires_at"] = (
df["created_at"]
+ pd.Timedelta(hours=24)
)
Jours :
df["next_day"] = (
df["event_time"]
+ pd.Timedelta(days=1)
)
Pour des décalages tenant compte du calendrier :
df["next_month"] = (
df["event_time"]
+ pd.offsets.MonthBegin(1)
)
Utilisez des décalages calendaires lorsque « le mois suivant » relève d’une logique de calendrier métier plutôt que d’un nombre fixe de jours.
21. Trier par horodatage
df = df.sort_values(
["customer_id", "event_time"]
)
C’est important avant :
- un remplissage vers l’avant (forward fill)
- un remplissage vers l’arrière (backward fill)
- des calculs glissants
- la sélection de l’enregistrement le plus récent
- l’analyse de séquences
Ne supposez jamais que l’ordre des lignes de la source est chronologique.
22. Obtenir la ligne la plus récente par entité
latest = (
df.sort_values(
["customer_id", "event_time"]
)
.groupby(
"customer_id",
as_index=False,
)
.tail(1)
)
Cela conserve la ligne réelle associée à l’horodatage le plus récent.
N’utilisez pas :
groupby().agg("max")
pour reconstituer une ligne « la plus récente » à partir de colonnes sans rapport entre elles.
23. Obtenir l’horodatage de l’événement précédent
df = df.sort_values(
["customer_id", "event_time"]
)
df["previous_event_time"] = (
df.groupby("customer_id")["event_time"]
.shift(1)
)
df["seconds_since_previous"] = (
df["event_time"]
- df["previous_event_time"]
).dt.total_seconds()
Utile pour :
- la reconstitution de sessions (sessionization)
- l’analyse des écarts entre événements
- les calculs de latence
- la détection de requêtes répétées
24. Comparer en toute sécurité des horodatages provenant de sources différentes
Avant la comparaison, normalisez les deux côtés.
Exemple :
left_time = pd.to_datetime(
left["event_time"],
utc=True,
errors="coerce",
)
right_time = pd.to_datetime(
right["event_time"],
utc=True,
errors="coerce",
)
Comparez ensuite, ou faites le merge.
Ne comparez pas une Series UTC avec fuseau horaire à une Series locale naïve en supposant que la différence n’est qu’une question de format.
25. Utiliser merge_asof pour les jointures sur périodes de validité
Exemple : associer à chaque événement le dernier prix en vigueur avant celui-ci.
events = events.sort_values(
["product_id", "event_time"]
)
prices = prices.sort_values(
["product_id", "effective_time"]
)
result = pd.merge_asof(
events,
prices,
left_on="event_time",
right_on="effective_time",
by="product_id",
direction="backward",
)
Utilisez cette approche lorsque l’égalité exacte des horodatages n’est pas la règle métier.
Validez :
- l’ordre de tri
- la cohérence des fuseaux horaires
- la clé d’entité
- la direction
- la tolérance, le cas échéant
26. Limiter l’écart temporel des correspondances avec une tolérance
result = pd.merge_asof(
events,
prices,
left_on="event_time",
right_on="effective_time",
by="product_id",
direction="backward",
tolerance=pd.Timedelta("7D"),
)
Cela évite les correspondances avec des données de référence trop anciennes.
N’utilisez une tolérance que lorsque la règle métier définit un écart maximal pertinent.
27. Trouver les dates invalides ou manquantes après l’analyse
parsed = pd.to_datetime(
df["event_time_raw"],
errors="coerce",
)
invalid = df.loc[
df["event_time_raw"].notna()
& parsed.isna()
]
print(invalid)
C’est une vérification essentielle lors de l’ingestion.
Un appel pd.to_datetime() réussi avec errors="coerce" peut tout de même masquer de mauvaises valeurs sources si vous n’inspectez pas les conversions forcées.
28. Vérifier la plage de dates après l’analyse
print(df["event_time"].min())
print(df["event_time"].max())
Utilisez cette vérification pour détecter :
- des dates futures
- des dates anormalement anciennes
- une année mal analysée
- des décalages de fuseau horaire
- des périodes manquantes dans la source
29. Vérifier les horodatages en double au sein d’une clé métier
duplicates = df.loc[
df.duplicated(
subset=["customer_id", "event_time"],
keep=False,
)
].sort_values(
["customer_id", "event_time"]
)
print(duplicates)
Un horodatage en double peut être valide.
La question importante est de savoir si la clé métier et la granularité des événements autorisent plusieurs lignes au même instant.
Interpréter le résultat
| Concept | Signification |
|---|---|
datetime64[ns] |
dtype datetime pandas/NumPy sans fuseau horaire. |
datetime64[ns, UTC] |
dtype datetime avec fuseau horaire, en UTC. |
pd.Timestamp |
Scalaire pandas représentant une date/heure. |
NaT |
Valeur datetime/timedelta manquante. |
tz_localize() |
Attribue un fuseau horaire à des horodatages naïfs sans modifier l’heure locale affichée. |
tz_convert() |
Convertit des horodatages avec fuseau horaire vers un autre fuseau horaire en conservant l’instant. |
Timedelta |
Durée entre des horodatages ou décalage temporel fixe. |
DateOffset |
Décalage tenant compte du calendrier, par exemple d’un mois ou d’un jour ouvré. |
floor() |
Arrondit à la borne temporelle inférieure. |
normalize() |
Ramène l’heure à minuit en conservant le contexte de date et de fuseau horaire. |
Points à vérifier
De nombreuses valeurs deviennent NaT
Cela signifie que l’analyse a échoué.
Causes possibles :
- format modifié
- formats mélangés
- dates impossibles
- texte de fuseau horaire
- données sources mal formées
Inspectez les chaînes d’origine.
L’horodatage semble décalé de plusieurs heures
Probablement une confusion de fuseau horaire.
Vérifiez :
- le fuseau horaire de la source
- si la source était déjà en UTC
- si
tz_localize()ettz_convert()ont été utilisés dans le bon ordre
Les totaux journaliers diffèrent d’un système à l’autre
Vérifiez si les systèmes regroupent par :
- date UTC
- date locale métier
- fuseau horaire du serveur
- fuseau horaire de l’utilisateur
Le même événement peut appartenir à des jours calendaires différents selon le fuseau de reporting.
Des lignes de fin de journée sont manquantes
Cela vient souvent d’un filtre comme :
timestamp <= "2026-10-31"
qui représente minuit au début de la journée.
Utilisez un intervalle semi-ouvert qui se termine au jour ou au mois suivant.
La durée est étonnamment inférieure à un jour
Vérifiez si le code a utilisé :
timedelta.dt.seconds
au lieu de :
timedelta.dt.total_seconds()
Les changements d’heure produisent des heures locales ambiguës ou manquantes
C’est le comportement attendu dans les fuseaux horaires qui appliquent l’heure d’été.
Gérez l’ambiguïté explicitement au lieu de deviner en silence.
Notes de production
Stockez les horodatages d’événements en UTC lorsque c’est possible
UTC est généralement la représentation canonique la plus sûre pour :
- le stockage des événements
- les systèmes multirégions
- les API
- le traitement distribué
- les data lakes
Convertissez en heure locale métier à la frontière du reporting ou de la présentation, lorsque c’est nécessaire.
Ne perdez pas l’information de fuseau horaire trop tôt
Convertir des horodatages avec fuseau horaire en horodatages naïfs peut rendre leur interprétation ultérieure ambiguë.
Conservez le fuseau horaire jusqu’à ce que la règle métier exige explicitement le contraire.
Les dates seules et les horodatages sont des concepts différents
Exemples :
2026-10-04
2026-10-04T15:27:18Z
La première est une date calendaire.
Le second est un instant précis.
Ne les modélisez pas de manière interchangeable.
Les intervalles semi-ouverts évitent les bugs de borne
Préférez :
start <= timestamp < next_start
plutôt que de construire manuellement un horodatage maximal de fin de journée.
Ce modèle est plus facile à raisonner et fonctionne quelle que soit la précision des horodatages.
L’analyse peut être coûteuse
Sur de grands DataFrames :
- analysez une seule fois
- évitez les conversions répétées
- précisez les formats connus lorsque c’est pertinent
- ne sélectionnez que les colonnes nécessaires
- déléguez le filtrage par date au moteur de stockage ou de requête lorsque c’est possible
La conversion de fuseau horaire peut changer les dates de reporting
Un horodatage UTC proche de minuit peut tomber la veille en heure locale après conversion.
Convertissez toujours avant de dériver les composantes de date locale métier.
L’arithmétique calendaire diffère des durées fixes
Un mois ne compte pas toujours 30 jours.
Utilisez DateOffset ou les fréquences calendaires pour les règles fondées sur le calendrier.
Utilisez Timedelta pour les durées écoulées fixes.
Erreurs fréquentes
1. Comparer des chaînes de dates au lieu d’horodatages analysés
La comparaison de chaînes peut sembler fonctionner avec les formats ISO, mais elle est fragile et sémantiquement fausse pour une logique de dates générale.
Analysez d’abord.
2. Utiliser tz_localize() alors que vous voulez tz_convert()
Utilisez :
tz_localize -> horodatage naïf vers horodatage avec fuseau horaire
tz_convert -> d’un fuseau horaire vers un autre fuseau horaire
Ils résolvent des problèmes différents.
3. Marquer des horodatages locaux comme UTC
Cela change le sens des données.
Si 08:00 était l’heure locale de New York, n’attribuez pas simplement UTC.
Localisez d’abord dans le fuseau de New York, puis convertissez en UTC.
4. Filtrer jusqu’à 23:59:59
Cela peut encore manquer des horodatages plus précis.
Utilisez la borne suivante avec <.
5. Utiliser .dt.date trop tôt
Cela convertit les horodatages en objets date Python et fait perdre l’heure de la journée.
Conservez les horodatages jusqu’à ce que vous ayez réellement besoin d’une sémantique de date seule.
6. Utiliser .dt.seconds pour des durées complètes
.dt.seconds exclut les jours entiers.
Utilisez .dt.total_seconds().
7. Ignorer les changements d’heure
Les heures locales peuvent être ambiguës ou inexistantes.
Gérez-les explicitement.
8. Regrouper par jour des horodatages UTC pour un rapport en heure locale métier
Convertissez d’abord dans le fuseau horaire métier.
Sinon, les événements proches de minuit peuvent tomber dans le mauvais jour de reporting.
9. Écraser les échecs d’analyse sans les inspecter
errors="coerce" est utile, mais peut masquer de mauvaises données si vous ne vérifiez jamais les nouvelles valeurs NaT.
Ce contenu vous a-t-il été utile ?
Que pourrions-nous améliorer ?
Merci — cela m’aide à améliorer Javi Builds.
Restez au courant
Recevez uniquement les nouvelles de Javi Builds qui vous intéressent.
Consultez votre boîte de réception
Je vous ai envoyé un lien de confirmation. Votre abonnement sera actif après confirmation.