16.3. time — Accès au temps et conversions

Ce module fournit différentes fonctions liées au temps. Pour les fonctionnalités associées, voir aussi les modules datetime et calendar.

Bien que ce module soit toujours disponible, toutes les fonctions ne sont pas disponibles sur toutes les plateformes. La plupart des fonctions définies dans ce module délèguent à des fonctions de même nom de la bibliothèque C. Il peut parfois être utile de consulter la documentation de la plate-forme, car la sémantique de ces fonctions peut varier.

Vous trouvez ci-dessous, mises en ordre, quelques explications relative à la terminologie et aux conventions.

  • The epoch is the point where the time starts, and is platform dependent. For Unix, the epoch is January 1, 1970, 00:00:00 (UTC). To find out what the epoch is on a given platform, look at time.gmtime(0).
  • The term seconds since the epoch refers to the total number of elapsed seconds since the epoch, typically excluding leap seconds. Leap seconds are excluded from this total on all POSIX-compliant platforms.
  • Les fonctions de ce module peuvent ne pas gérer les dates et heures antérieures à epoch ou dans un avenir lointain. Le seuil du futur est déterminé par la bibliothèque C ; pour les systèmes 32 bits, il s’agit généralement de 2038.
  • Problèmes liés à l’an 2000 (Y2K) : Python dépend de la bibliothèque C de la plate-forme, qui n’a généralement pas de problèmes liés à l’an 2000, étant donné que toutes les dates et heures sont représentées en interne en secondes depuis epoch. La fonction strptime() peut analyser des années à 2 chiffres lorsque le format %y est spécifié. Lorsque les années à deux chiffres sont analysées, elles sont converties conformément aux normes POSIX et ISO C : les valeurs 69—99 correspondent à 1969—1999 et les valeurs 0—68 à 2000—2068.
  • UTC désigne le temps universel coordonné (Coordinated Universal Time en anglais), anciennement l’heure de Greenwich (ou GMT). L’acronyme UTC n’est pas une erreur mais un compromis entre l’anglais et le français.

  • Le DST (Daylight Saving Time) correspond à l’heure d’été, un ajustement du fuseau horaire d’une heure (généralement) pendant une partie de l’année. Les règles de DST sont magiques (déterminées par la loi locale) et peuvent changer d’année en année. La bibliothèque C possède une table contenant les règles locales (souvent, elle est lue dans un fichier système par souci de souplesse) et constitue la seule source fiable.

  • La précision des diverses fonctions en temps réel peut être inférieure à celle suggérée par les unités dans lesquelles leur valeur ou leur argument est exprimé. Par exemple, sur la plupart des systèmes Unix, l’horloge ne « bat » que 50 ou 100 fois par seconde.

  • D’autre part, la précision de time() et sleep() est meilleure que leurs équivalents Unix : les temps sont exprimés en nombres à virgule flottante, time() renvoie le temps le plus précis disponible (en utilisant gettimeofday() d’Unix si elle est disponible), et sleep() accepte le temps avec une fraction non nulle (select() d’Unix est utilisée pour l’implémenter, si elle est disponible).

  • La valeur temporelle renvoyée par gmtime(), localtime() et strptime(), et acceptée par asctime(), mktime() et strftime(), est une séquence de 9 nombres entiers. Les valeurs de retour de gmtime(), localtime() et strptime() proposent également des noms d’attributs pour des champs individuels.

    Voir struct_time pour une description de ces objets.

    Modifié dans la version 3.3: Le type struct_time a été étendu pour fournir les attributs tm_gmtoff et tm_zone lorsque la plateforme prend en charge les membres struct tm correspondants.

  • Utilisez les fonctions suivantes pour convertir des représentations temporelles :

    De À Utilisez
    secondes depuis epoch struct_time en UTC gmtime()
    secondes depuis epoch struct_time en heure locale localtime()
    struct_time en UTC secondes depuis epoch calendar.timegm()
    struct_time en heure locale secondes depuis epoch mktime()

The module defines the following functions and data items:

time.altzone

The offset of the local DST timezone, in seconds west of UTC, if one is defined. This is negative if the local DST timezone is east of UTC (as in Western Europe, including the UK). Only use this if daylight is nonzero.

time.asctime([t])

Convertit un tuple ou struct_time représentant une heure renvoyée par gmtime() ou localtime() en une chaîne de la forme suivante : 'Sun Jun 20 23:21:05 1993'. Si t n’est pas fourni, l’heure actuelle renvoyée par localtime() est utilisée. Les informations sur les paramètres régionaux ne sont pas utilisées par asctime().

Note

Contrairement à la fonction C du même nom, asctime() n’ajoute pas de caractère de fin de ligne.

time.clock()

Sous UNIX, renvoie le temps processeur actuel, en secondes, sous la forme d’un nombre à virgule flottante exprimé en secondes. La précision, et en fait la définition même de la signification de « temps processeur », dépend de celle de la fonction C du même nom.

Sous Windows, cette fonction renvoie les secondes réelles (type horloge murale) écoulées depuis le premier appel à cette fonction, en tant que nombre à virgule flottante, en fonction de la fonction Win32 QueryPerformanceCounter(). La résolution est généralement meilleure qu’une microseconde.

Obsolète depuis la version 3.3: Le comportement de cette fonction dépend de la plate-forme : utilisez plutôt perf_counter() ou process_time(), selon vos besoins, pour avoir un comportement bien défini.

time.clock_getres(clk_id)

Return the resolution (precision) of the specified clock clk_id.

Disponibilité : Unix.

Nouveau dans la version 3.3.

time.clock_gettime(clk_id)

Return the time of the specified clock clk_id.

Disponibilité : Unix.

Nouveau dans la version 3.3.

time.clock_settime(clk_id, time)

Set the time of the specified clock clk_id.

Disponibilité : Unix.

Nouveau dans la version 3.3.

time.CLOCK_HIGHRES

The Solaris OS has a CLOCK_HIGHRES timer that attempts to use an optimal hardware source, and may give close to nanosecond resolution. CLOCK_HIGHRES is the nonadjustable, high-resolution clock.

Availability: Solaris.

Nouveau dans la version 3.3.

time.CLOCK_MONOTONIC

Horloge qui ne peut pas être réglée et représente l’heure monotone depuis un point de départ non spécifié.

Disponibilité : Unix.

Nouveau dans la version 3.3.

time.CLOCK_MONOTONIC_RAW

Similaire à CLOCK_MONOTONIC, mais donne accès à une heure matérielle brute qui n’est pas soumise aux ajustements NTP.

Availability: Linux 2.6.28 or later.

Nouveau dans la version 3.3.

time.CLOCK_PROCESS_CPUTIME_ID

Minuterie haute résolution par processus du CPU.

Disponibilité : Unix.

Nouveau dans la version 3.3.

time.CLOCK_REALTIME

Horloge en temps réel à l’échelle du système. Le réglage de cette horloge nécessite des privilèges appropriés.

Disponibilité : Unix.

Nouveau dans la version 3.3.

time.CLOCK_THREAD_CPUTIME_ID

Horloge de temps CPU spécifique au thread.

Disponibilité : Unix.

Nouveau dans la version 3.3.

time.ctime([secs])

Convertit une heure exprimée en secondes depuis epoch en une chaîne représentant l’heure locale. Si secs n’est pas fourni ou vaut None, l’heure actuelle renvoyée par time() est utilisée. ctime(secs) est équivalent à asctime(localtime(secs)). Les informations sur les paramètres régionaux ne sont pas utilisées par ctime().

time.daylight

Nonzero if a DST timezone is defined.

time.get_clock_info(name)

Renvoie des informations sur l’horloge spécifiée en tant qu’objet d’espace de nom. Les noms d’horloge pris en charge et les fonctions correspondantes permettant de lire leur valeur sont les suivants :

Le résultat a les attributs suivants :

  • adjustable : True si l’horloge peut être changée automatiquement (par exemple par un démon NTP) ou manuellement par l’administrateur système, False autrement
  • implementation: The name of the underlying C function used to get the clock value
  • monotonic : True si l’horloge ne peut pas revenir en arrière, False autrement
  • resolution : La résolution de l’horloge en secondes (float)

Nouveau dans la version 3.3.

time.gmtime([secs])

Convertit un temps exprimé en secondes depuis epoch en un struct_time au format UTC dans lequel le drapeau dst est toujours égal à zéro. Si secs n’est pas fourni ou vaut None, l’heure actuelle renvoyée par time() est utilisée. Les fractions de seconde sont ignorées. Voir ci-dessus pour une description de l’objet struct_time. Voir calendar.timegm() pour l’inverse de cette fonction.

time.localtime([secs])

Comme gmtime() mais convertit le résultat en heure locale. Si secs n’est pas fourni ou vaut None, l’heure actuelle renvoyée par time() est utilisée. Le drapeau dst est mis à 1 lorsque l’heure d’été s’applique à l’heure indiquée.

time.mktime(t)

C’est la fonction inverse de localtime(). Son argument est soit un struct_time soit un 9-tuple (puisque le drapeau dst est nécessaire ; utilisez -1 comme drapeau dst s’il est inconnu) qui exprime le temps local, pas UTC. Il retourne un nombre à virgule flottante, pour compatibilité avec time(). Si la valeur d’entrée ne peut pas être représentée comme une heure valide, soit OverflowError ou ValueError sera levée (selon que la valeur non valide est interceptée par Python ou par les bibliothèque C sous-jacentes). La date la plus proche pour laquelle il peut générer une heure dépend de la plate-forme.

time.monotonic()

Renvoie la valeur (en quelques fractions de secondes) d’une horloge monotone, c’est-à-dire une horloge qui ne peut pas revenir en arrière. L’horloge n’est pas affectée par les mises à jour de l’horloge système. Le point de référence de la valeur renvoyée n’est pas défini, de sorte que seule la différence entre les résultats d’appels consécutifs est valide.

On Windows versions older than Vista, monotonic() detects GetTickCount() integer overflow (32 bits, roll-over after 49.7 days). It increases an internal epoch (reference time) by 232 each time that an overflow is detected. The epoch is stored in the process-local state and so the value of monotonic() may be different in two Python processes running for more than 49 days. On more recent versions of Windows and on other operating systems, monotonic() is system-wide.

Nouveau dans la version 3.3.

Modifié dans la version 3.5: The function is now always available.

time.perf_counter()

Renvoie la valeur (en quelques fractions de secondes) d’un compteur de performance, c’est-à-dire une horloge avec la résolution disponible la plus élevée possible pour mesurer une courte durée. Cela inclut le temps écoulé pendant le sommeil et concerne l’ensemble du système. Le point de référence de la valeur renvoyée n’est pas défini, de sorte que seule la différence entre les résultats d’appels consécutifs est valide.

Nouveau dans la version 3.3.

time.process_time()

Renvoie la valeur (en quelques fractions de secondes) de la somme des temps système et utilisateur du processus en cours. Il ne comprend pas le temps écoulé pendant le sommeil. C’est un processus par définition. Le point de référence de la valeur renvoyée n’est pas défini, de sorte que seule la différence entre les résultats d’appels consécutifs est valide.

Nouveau dans la version 3.3.

time.sleep(secs)

Suspend l’exécution du thread appelant pendant le nombre de secondes indiqué. L’argument peut être un nombre à virgule flottante pour indiquer un temps de sommeil plus précis. Le temps de suspension réel peut être inférieur à celui demandé, car tout signal capturé mettra fin à la commande sleep() après l’exécution de la routine de capture de ce signal. En outre, le temps de suspension peut être plus long que celui demandé par un montant arbitraire en raison de la planification d’une autre activité dans le système.

Modifié dans la version 3.5: La fonction dort maintenant au moins secondes même si le sommeil est interrompu par un signal, sauf si le gestionnaire de signaux lève une exception (voir PEP 475 pour la justification).

time.strftime(format[, t])

Convertit un tuple ou struct_time représentant une heure renvoyée par gmtime() ou localtime() en une chaîne spécifiée par l’argument format. Si t n’est pas fourni, l’heure actuelle renvoyée par localtime() est utilisée. format doit être une chaîne. Si l’un des champs de t se situe en dehors de la plage autorisée, une ValueError est levée .

0 est un argument légal pour toute position dans le tuple temporel ; s’il est normalement illégal, la valeur est forcée à une valeur correcte.

Les directives suivantes peuvent être incorporées dans la chaîne format. Ils sont affichés sans la spécification facultative de largeur de champ ni de précision, et sont remplacés par les caractères indiqués dans le résultat de strftime() :

Directive Signification Notes
%a Nom abrégé du jour de la semaine selon les paramètres régionaux.  
%A Le nom de semaine complet de la région.  
%b Nom abrégé du mois de la région.  
%B Nom complet du mois de la région.  
%c Représentation locale de la date et de l’heure.  
%d Jour du mois sous forme décimale [01,31].  
%H Heure (horloge sur 24 heures) sous forme de nombre décimal [00,23].  
%I Heure (horloge sur 12 heures) sous forme de nombre décimal [01,12].  
%j Jour de l’année sous forme de nombre décimal [001,366].  
%m Mois sous forme décimale [01,12].  
%M Minutes sous forme décimale [00,59].  
%p Équivalent local à AM/PM. (1)
%S Deuxième sous forme de nombre décimal [00,61]. (2)
%U Numéro de semaine de l’année (dimanche en tant que premier jour de la semaine) sous forme décimale [00,53]. Tous les jours d’une nouvelle année précédant le premier dimanche sont considérés comme appartenant à la semaine 0. (3)
%w Jour de la semaine sous forme de nombre décimal [0 (dimanche), 6].  
%W Numéro de semaine de l’année (lundi comme premier jour de la semaine) sous forme décimale [00,53]. Tous les jours d’une nouvelle année précédant le premier lundi sont considérés comme appartenant à la semaine 0. (3)
%x Représentation locale de la date.  
%X Représentation locale de l’heure.  
%y Année sans siècle comme un nombre décimal [00, 99].  
%Y Année complète sur quatre chiffres.  
%z Décalage de fuseau horaire indiquant une différence de temps positive ou négative par rapport à UTC / GMT de la forme +HHMM ou -HHMM, où H représente les chiffres des heures décimales et M, les chiffres des minutes décimales [-23:59, +23:59].  
%Z Nom du fuseau horaire (pas de caractères s’il n’y a pas de fuseau horaire).  
%% Un caractère '%' littéral.  

Notes :

  1. Lorsqu’elle est utilisée avec la fonction strptime(), la directive %p n’affecte le champ d’heure en sortie que si la directive %I est utilisée pour analyser l’heure.
  2. The range really is 0 to 61; value 60 is valid in timestamps representing leap seconds and value 61 is supported for historical reasons.
  3. Lorsqu’elles sont utilisées avec la fonction strptime(), %U et %W ne sont utilisées que dans les calculs lorsque le jour de la semaine et l’année sont spécifiés.

Voici un exemple de format de date compatible avec celui spécifié dans la norme de courrier électronique Internet suivante RFC 2822. [1]

>>> from time import gmtime, strftime
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
'Thu, 28 Jun 2001 14:17:15 +0000'

Des directives supplémentaires peuvent être prises en charge sur certaines plates-formes, mais seules celles énumérées ici ont une signification normalisée par ANSI C. Pour voir la liste complète des codes de format pris en charge sur votre plate-forme, consultez la documentation strftime(3).

Sur certaines plates-formes, une spécification facultative de largeur et de précision de champ peut suivre immédiatement le '%' initial d’une directive dans l’ordre suivant ; ce n’est pas non plus portable. La largeur du champ est normalement 2 sauf pour %j où il est 3.

time.strptime(string[, format])

Analyse une chaîne représentant une heure selon un format. La valeur renvoyée est une struct_time tel que renvoyé par gmtime() ou localtime().

Le paramètre format utilise les mêmes directives que celles utilisées par strftime(); La valeur par défaut est "%a %b %d %H:%M:%S %Y" qui correspond à la mise en forme renvoyée par ctime(). Si string ne peut pas être analysé selon format, ou s’il contient trop de données après l’analyse, une exception ValueError est levée. Les valeurs par défaut utilisées pour renseigner les données manquantes lorsque des valeurs plus précises ne peuvent pas être inférées sont (1900, 1, 1, 0, 0, 0, 0, 1, -1). string et format doivent être des chaînes.

Par exemple :

>>> import time
>>> time.strptime("30 Nov 00", "%d %b %y")   # doctest: +NORMALIZE_WHITESPACE
time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0,
                 tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)

La prise en charge de la directive %Z est basée sur les valeurs contenues dans tzname et sur le fait de savoir si daylight est vrai. Pour cette raison, il est spécifique à la plate-forme, à l’exception de la reconnaissance des heures UTC et GMT, qui sont toujours connues (et considérées comme des fuseaux horaires ne respectant pas l’heure d’été).

Seules les directives spécifiées dans la documentation sont prises en charge. Parce que strftime() peut être implémenté différemment sur chaque plate-forme, il peut parfois offrir plus de directives que celles listées. Mais strptime() est indépendant de toute plate-forme et ne supporte donc pas nécessairement toutes les directives disponibles qui ne sont pas documentées comme gérées.

class time.struct_time

Le type de la séquence de valeur temporelle renvoyé par gmtime(), localtime() et strptime(). Semblable à un named tuple : ses valeurs sont accessibles par index et par nom d’attribut. Les valeurs suivantes sont présentes :

Index Attribut Valeurs
0 tm_year (par exemple, 1993)
1 tm_mon plage [1, 12]
2 tm_mday plage [1, 31]
3 tm_hour plage [0, 23]
4 tm_min plage [0, 59]
5 tm_sec plage [0, 61]; voir (2) dans la description strftime()
6 tm_wday plage [0, 6], Lundi valant 0
7 tm_yday plage [1, 366]
8 tm_isdst 0, 1 or -1 ; voir en bas
N/A tm_zone abréviation du nom du fuseau horaire
N/A tm_gmtoff décalage à l’est de UTC en secondes

Notez que contrairement à la structure C, la valeur du mois est une plage de [1, 12], pas de [0, 11].

Dans les appels à mktime(), tm_isdst peut être défini sur 1 lorsque l’heure d’été est en vigueur et sur 0 lorsque ce n’est pas le cas. Une valeur de -1 indique que cela n’est pas connu et entraînera généralement le remplissage de l’état correct.

Lorsqu’un tuple de longueur incorrecte est passé à une fonction acceptant une struct_time, ou comportant des éléments de type incorrect, une exception TypeError est levé.

Modifié dans la version 3.3: tm_gmtoff and tm_zone attributes are available on platforms with C library supporting the corresponding fields in struct tm.

time.time()

Return the time in seconds since the epoch as a floating point number. The specific date of the epoch and the handling of leap seconds is platform dependent. On Windows and most Unix systems, the epoch is January 1, 1970, 00:00:00 (UTC) and leap seconds are not counted towards the time in seconds since the epoch. This is commonly referred to as Unix time. To find out what the epoch is on a given platform, look at gmtime(0).

Note that even though the time is always returned as a floating point number, not all systems provide time with a better precision than 1 second. While this function normally returns non-decreasing values, it can return a lower value than a previous call if the system clock has been set back between the two calls.

The number returned by time() may be converted into a more common time format (i.e. year, month, day, hour, etc…) in UTC by passing it to gmtime() function or in local time by passing it to the localtime() function. In both cases a struct_time object is returned, from which the components of the calendar date may be accessed as attributes.

time.timezone

The offset of the local (non-DST) timezone, in seconds west of UTC (negative in most of Western Europe, positive in the US, zero in the UK).

time.tzname

A tuple of two strings: the first is the name of the local non-DST timezone, the second is the name of the local DST timezone. If no DST timezone is defined, the second string should not be used.

time.tzset()

Resets the time conversion rules used by the library routines. The environment variable TZ specifies how this is done.

Disponibilité : Unix.

Note

Bien que dans de nombreux cas, la modification de la variable d’environnement TZ puisse affecter la sortie de fonctions telles que localtime() sans appeler tzset(), ce comportement n’est pas garanti.

La variable d’environnement TZ ne doit contenir aucun espace.

Le format standard de la variable d’environnement TZ est (espaces ajoutés pour plus de clarté):

std offset [dst [offset [,start[/time], end[/time]]]]

Où les composants sont :

std and dst
Trois alphanumériques ou plus donnant les abréviations du fuseau horaire. Ceux-ci seront propagés dans time.tzname
offset
Le décalage a la forme suivante : ± hh[:mm[:ss]]. Cela indique la valeur ajoutée à l’heure locale pour arriver à UTC. S’il est précédé d’un '-', le fuseau horaire est à l’est du Premier Méridien ; sinon, c’est l’ouest. Si aucun décalage ne suit dst, l’heure d’été est supposée être en avance d’une heure sur l’heure standard.
start[/time], end[/time]

Indique quand passer à DST et en revenir. Le format des dates de début et de fin est l’un des suivants :

Jn
Le jour Julien n (1 <= n <= 365). Les jours bissextiles ne sont pas comptabilisés. Par conséquent, le 28 février est le 59e jour et le 1er Mars est le 60e jour de toutes les années.
n
Le jour Julien de base zéro (0 <= n <= 365). Les jours bissextiles sont comptés et il est possible de se référer au 29 février.
Mm.n.d
The d’th day (0 <= d <= 6) or week n of month m of the year (1 <= n <= 5, 1 <= m <= 12, where week 5 means « the last d day in month m » which may occur in either the fourth or the fifth week). Week 1 is the first week in which the d’th day occurs. Day zero is Sunday.

time a le même format que offset sauf qu’aucun signe de direction ('-' ou '+') n’est autorisé. La valeur par défaut, si l’heure n’est pas spécifiée, est 02:00:00.

>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'02:07:36 05/08/03 EDT'
>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'16:08:12 05/08/03 AEST'

Sur de nombreux systèmes Unix (y compris *BSD, Linux, Solaris et Darwin), il est plus pratique d’utiliser la base de données zoneinfo (tzfile (5)) du système pour spécifier les règles de fuseau horaire. Pour ce faire, définissez la variable d’environnement TZ sur le chemin du fichier de fuseau horaire requis, par rapport à la racine de la base de données du système zoneinfo, généralement situé à /usr/share/zoneinfo. Par exemple, 'US/Eastern', 'Australia/Melbourne', 'Egypt' ou 'Europe/Amsterdam'.

>>> os.environ['TZ'] = 'US/Eastern'
>>> time.tzset()
>>> time.tzname
('EST', 'EDT')
>>> os.environ['TZ'] = 'Egypt'
>>> time.tzset()
>>> time.tzname
('EET', 'EEST')

Voir aussi

Module datetime
Interface plus orientée objet vers les dates et les heures.
Module locale
Services d’internationalisation. Les paramètres régionaux affectent l’interprétation de nombreux spécificateurs de format dans strftime() et strptime().
Module calendar
Fonctions générales liées au calendrier. timegm() est l’inverse de gmtime() à partir de ce module.

Notes

[1]L’utilisation de %Z est maintenant obsolète, mais l’échappement %z qui donne le décalage horaire jusqu’à la minute et dépendant des paramètres régionaux n’est pas pris en charge par toutes les bibliothèques C ANSI. En outre, une lecture stricte du standard RFC 822 de 1982 milite pour une année à deux chiffres (%y plutôt que %Y), mais la pratique a migré vers des années à 4 chiffres de long avant l’année 2000. Après cela, la RFC 822 est devenue obsolète et l’année à 4 chiffres a été recommandée pour la première fois par la RFC 1123 puis rendue obligatoire par la RFC 2822.