# 15.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. On January 1st of that year, at 0 hours, the « time since the epoch » is zero. For Unix, the epoch is 1970. To find out what the epoch is, look at `gmtime(0)`.

- The functions in this module do not handle dates and times before the epoch or far in the future. The cut-off point in the future is determined by the C library; for Unix, it is typically in 2038.

- Year 2000 (Y2K) issues: Python depends on the platform’s C library, which generally doesn’t have year 2000 issues, since all dates and times are represented internally as seconds since the epoch. Functions accepting a `struct_time` (see below) generally require a 4-digit year. For backward compatibility, 2-digit years are supported if the module variable `accept2dyear` is a non-zero integer; this variable is initialized to `1` unless the environment variable `PYTHONY2K` is set to a non-empty string, in which case it is initialized to `0`. Thus, you can set `PYTHONY2K` to a non-empty string in the environment to require 4-digit years for all year input. When 2-digit years are accepted, they are converted according to the POSIX or X/Open standard: values 69-99 are mapped to 1969-1999, and values 0–68 are mapped to 2000–2068. Values 100–1899 are always illegal.

- 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).

- The time value as returned by `gmtime()`, `localtime()`, and `strptime()`, and accepted by `asctime()`, `mktime()` and `strftime()`, may be considered as a sequence of 9 integers. The return values of `gmtime()`, `localtime()`, and `strptime()` also offer attribute names for individual fields.

  Voir `struct_time` pour une description de ces objets.

  Modifié dans la version 2.2: The time value sequence was changed from a tuple to a `struct_time`, with the addition of attribute names for the fields.

- 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.``accept2dyear`

  Boolean value indicating whether two-digit year values will be accepted. This is true by default, but will be set to false if the environment variable `PYTHONY2K` has been set to a non-empty string. It may also be modified at run time.

`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])

  Convert a tuple or `struct_time` representing a time as returned by `gmtime()` or `localtime()` to a 24-character string of the following form: `'Sun Jun 20 23:21:05 1993'`. If t is not provided, the current time as returned by `localtime()` is used. Locale information is not used by `asctime()`.

  Note

  Unlike the C function of the same name, there is no trailing newline.

  Modifié dans la version 2.1: Allowed t to be omitted.

`time.``clock`()

  On Unix, return the current processor time as a floating point number expressed in seconds. The precision, and in fact the very definition of the meaning of « processor time », depends on that of the C function of the same name, but in any case, this is the function to use for benchmarking Python or timing algorithms.

  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.

`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()`.

  Modifié dans la version 2.1: Allowed secs to be omitted.

  Modifié dans la version 2.4: If secs is `None`, the current time is used.

`time.``daylight`

  Nonzero if a DST timezone is defined.

`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.

  Modifié dans la version 2.1: Allowed secs to be omitted.

  Modifié dans la version 2.4: If secs is `None`, the current time is used.

`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.

  Modifié dans la version 2.1: Allowed secs to be omitted.

  Modifié dans la version 2.4: If secs is `None`, the current time is used.

`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.``sleep`(secs)

  Suspend execution of the current thread for the given number of seconds. The argument may be a floating point number to indicate a more precise sleep time. The actual suspension time may be less than that requested because any caught signal will terminate the `sleep()` following execution of that signal’s catching routine. Also, the suspension time may be longer than requested by an arbitrary amount because of the scheduling of other activity in the system.

`time.``strftime`(format[, t])

  Convert a tuple or `struct_time` representing a time as returned by `gmtime()` or `localtime()` to a string as specified by the format argument. If t is not provided, the current time as returned by `localtime()` is used. format must be a string. `ValueError` is raised if any field in t is outside of the allowed range. `strftime()` returns a locale dependent byte string; the result may be converted to unicode by doing `strftime(<myformat>).decode(locale.getlocale()[1])`.

  Modifié dans la version 2.1: Allowed t to be omitted.

  Modifié dans la version 2.4: `ValueError` raised if a field in t is out of range.

  Modifié dans la version 2.5: 0 is now a legal argument for any position in the time tuple; if it is normally illegal the value is forced to a correct one.

  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` | Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. | (3)
  `%w` | Jour de la semaine sous forme de nombre décimal [0 (dimanche), 6]. |
  `%W` | Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 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` | 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`; this accounts for leap seconds and the (very rare) double leap seconds.

  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])

  Parse a string representing a time according to a format. The return value is a `struct_time` as returned by `gmtime()` or `localtime()`.

  The format parameter uses the same directives as those used by `strftime()`; it defaults to `"%a %b %d %H:%M:%S %Y"` which matches the formatting returned by `ctime()`. If string cannot be parsed according to format, or if it has excess data after parsing, `ValueError` is raised. The default values used to fill in any missing data when more accurate values cannot be inferred are `(1900, 1, 1, 0, 0, 0, 0, 1, -1)`.

  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

  Nouveau dans la version 2.2.

  Note that unlike the C structure, the month value is a range of [1, 12], not [0, 11]. A year value will be handled as described under Year 2000 (Y2K) issues above.

  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é.

`time.``time`()

  Return the time in seconds since the epoch as a floating point number. 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.

`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`()

  Reset the time conversion rules used by the library routines. The environment variable `TZ` specifies how this is done. It will also set the variables `tzname` (from the `TZ` environment variable), `timezone` (non-DST seconds West of UTC), `altzone` (DST seconds west of UTC) and `daylight` (to 0 if this timezone does not have any daylight saving time rules, or to nonzero if there is a time, past, present or future when daylight saving time applies).

  Nouveau dans la version 2.3.

  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.