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

* L'*epoch* est le point de départ du temps et dépend de la plate-
  forme. Pour Unix, *epoch* est le 1^er janvier 1970 à 00:00:00 (UTC).
  Pour savoir comment est définie *epoch* sur une plate-forme donnée,
  regardez "time.gmtime(0)".

* Le terme *secondes depuis *epoch** désigne le nombre total de
  secondes écoulées depuis *epoch*, souvent en excluant les secondes
  intercalaires (leap seconds). Les secondes intercalaires sont
  exclues de ce total sur toutes les plates-formes conformes POSIX.

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

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

  Modifié dans la version 3.6: Les attributs "struct_time" "tm_gmtoff"
  et "tm_zone" sont maintenant disponibles sur toutes les plateformes.

* 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    | "localtime()"             |
  |                           | locale                    |                           |
  +---------------------------+---------------------------+---------------------------+
  | "struct_time" en UTC      | secondes depuis *epoch*   | "calendar.timegm()"       |
  +---------------------------+---------------------------+---------------------------+
  | "struct_time" en heure    | secondes depuis *epoch*   | "mktime()"                |
  | locale                    |                           |                           |
  +---------------------------+---------------------------+---------------------------+


Fonctions
=========

time.asctime([t])

   Convertit un n-uplet 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'". Le numéro du jour est un
   champ de deux caractères complété par une espace si celui-ci n'a
   qu'un seul chiffre, par exemple : "'Wed Jun  9 04:26:40 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.pthread_getcpuclockid(thread_id)

   Renvoie le *clk_id* de l'horloge du temps CPU spécifique au fil
   d'exécution pour le *thread_id* spécifié.

   Utilisez "threading.get_ident()" ou l'attribut "ident" de
   "threading.Thread" pour obtenir une valeur appropriée pour
   *thread_id*.

   Avertissement:

     Passer un *thread_id* invalide ou arrivé à expiration peut
     entraîner un comportement indéfini, tel qu’une erreur de
     segmentation.

   Disponibilité : Unix (regardez la page man pour
   *pthread_getcpuclockid(3)* pour plus d’information).

   Nouveau dans la version 3.7.

time.clock_getres(clk_id)

   Renvoie la résolution (précision) de l’horloge *clk_id*. Référez-
   vous à Constantes d’identification d’horloge pour une liste des
   valeurs acceptées pour *clk_id*.

   Disponibilité : Unix.

   Nouveau dans la version 3.3.

time.clock_gettime(clk_id) -> float

   Renvoie l’heure de l’horloge *clk_id*. Référez-vous à Constantes
   d’identification d’horloge pour une liste des valeurs acceptées
   pour *clk_id*.

   Disponibilité : Unix.

   Nouveau dans la version 3.3.

time.clock_gettime_ns(clk_id) -> int

   Similaire à "clock_gettime()" mais le temps renvoyé est exprimé en
   nanosecondes.

   Disponibilité : Unix.

   Nouveau dans la version 3.7.

time.clock_settime(clk_id, time: float)

   Définit l’heure de l’horloge *clk_id*. Actuellement,
   "CLOCK_REALTIME" est la seule valeur acceptée pour *clk_id*.

   Disponibilité : Unix.

   Nouveau dans la version 3.3.

time.clock_settime_ns(clk_id, time: int)

   Similaire à "clock_settime()" mais définit l’heure avec des
   nanosecondes.

   Disponibilité : Unix.

   Nouveau dans la version 3.7.

time.ctime([secs])

   Convertit une heure exprimée en secondes depuis *epoch* en une
   chaîne représentant l’heure locale, sous la forme suivante : "'Sun
   Jun 20 23:21:05 1993'". Le numéro du jour est un champ de deux
   caractères complété par une espace si celui-ci n'a qu'un seul
   chiffre, par exemple : "'Wed Jun  9 04:26:40 1993'".

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

   * "'monotonic'": "time.monotonic()"

   * "'perf_counter'": "time.perf_counter()"

   * "'process_time'": "time.process_time()"

   * "'thread_time'": "time.thread_time()"

   * "'time'": "time.time()"

   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* : nom de la fonction C sous-jacente utilisée
     pour obtenir la valeur d’horloge. Voir Constantes
     d’identification d’horloge pour les valeurs possibles.

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

   "localtime()" may raise "OverflowError", if the timestamp is
   outside the range of values supported by the platform C
   "localtime()" or "gmtime()" functions, and "OSError" on
   "localtime()" or "gmtime()" failure. It's common for this to be
   restricted to years between 1970 and 2038.

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

   Return the value (in fractional seconds) of a monotonic clock, i.e.
   a clock that cannot go backwards.  The clock is not affected by
   system clock updates. The reference point of the returned value is
   undefined, so that only the difference between the results of two
   calls is valid.

   Nouveau dans la version 3.3.

   Modifié dans la version 3.5: La fonction est maintenant toujours
   disponible et toujours à l’échelle du système.

time.monotonic_ns() -> int

   Similaire à "monotonique()", mais le temps de retour est exprimé en
   nanosecondes.

   Nouveau dans la version 3.7.

time.perf_counter() -> float

   Return the value (in fractional seconds) of a performance counter,
   i.e. a clock with the highest available resolution to measure a
   short duration.  It does include time elapsed during sleep and is
   system-wide.  The reference point of the returned value is
   undefined, so that only the difference between the results of two
   calls is valid.

   Nouveau dans la version 3.3.

time.perf_counter_ns() -> int

   Similaire à "perf_counter()", mais renvoie le temps en
   nanosecondes.

   Nouveau dans la version 3.7.

time.process_time() -> float

   Return the value (in fractional seconds) of the sum of the system
   and user CPU time of the current process.  It does not include time
   elapsed during sleep.  It is process-wide by definition.  The
   reference point of the returned value is undefined, so that only
   the difference between the results of two calls is valid.

   Nouveau dans la version 3.3.

time.process_time_ns() -> int

   Similaire à "process_time()" mais renvoie le temps en nanosecondes.

   Nouveau dans la version 3.7.

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 appropriée de la date et de       |         |
   |             | l’heure selon les paramètres régionaux.          |         |
   +-------------+--------------------------------------------------+---------+
   | "%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"        | L’équivalent local de AM ou 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   | (3)     |
   |             | 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.     |         |
   +-------------+--------------------------------------------------+---------+
   | "%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        | (3)     |
   |             | 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.                      |         |
   +-------------+--------------------------------------------------+---------+
   | "%x"        | Représentation de la date appropriée par les     |         |
   |             | paramètres régionaux.                            |         |
   +-------------+--------------------------------------------------+---------+
   | "%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. La plage est en réalité de "0" à "61" ; La valeur "60" est
      valide dans les *timestamps* représentant des leap seconds et la
      valeur "61" est prise en charge pour des raisons historiques.

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

time.time() -> float

   Renvoie le temps en secondes depuis epoch sous forme de nombre à
   virgule flottante. La date spécifique de *epoch* et le traitement
   des secondes intercalaires (leap seconds) dépendent de la plate-
   forme. Sous Windows et la plupart des systèmes Unix, *epoch* est le
   1^er janvier 1970, 00:00:00 (UTC) et les secondes intercalaires ne
   sont pas comptées dans le temps en secondes depuis *epoch*. Ceci
   est communément appelé Heure Unix. Pour savoir quelle est *epoch*
   sur une plate-forme donnée, consultez "gmtime(0)".

   Notez que même si l’heure est toujours renvoyée sous forme de
   nombre à virgule flottante, tous les systèmes ne fournissent pas
   l’heure avec une précision supérieure à 1 seconde. Bien que cette
   fonction renvoie normalement des valeurs croissantes, elle peut
   renvoyer une valeur inférieure à celle d’un appel précédent si
   l’horloge système a été réglée entre les deux appels.

   Le nombre renvoyé par "time()" peut être converti en un format
   d’heure plus courant (année, mois, jour, heure, etc.) en UTC en le
   transmettant à la fonction "gmtime()" ou dans heure locale en le
   transmettant à la fonction "localtime()". Dans les deux cas, un
   objet "struct_time" est renvoyé, à partir duquel les composants de
   la date du calendrier peuvent être consultés en tant qu’attributs.

time.thread_time() -> float

   Renvoie la valeur (en quelques fractions de secondes) de la somme
   des temps processeur système et utilisateur du fil d'exécution en
   cours. Il ne comprend pas le temps écoulé pendant le sommeil. Il
   est spécifique au fil d'exécution par définition. Le point de
   référence de la valeur renvoyée est indéfini, de sorte que seule la
   différence entre les résultats d’appels consécutifs dans le même
   fil d'exécution est valide.

   Disponibilité : Systèmes Windows, Linux, Unix prenant en charge
   "CLOCK_THREAD_CPUTIME_ID".

   Nouveau dans la version 3.7.

time.thread_time_ns() -> int

   Similaire à "thread_time()" mais renvoie le temps en nanosecondes.

   Nouveau dans la version 3.7.

time.time_ns() -> int

   Similaire à "time()" mais renvoie le nombre de nanosecondes depuis
   epoch sous la forme d'un entier.

   Nouveau dans la version 3.7.

time.tzset()

   Réinitialise les règles de conversion de temps utilisées par les
   routines de la bibliothèque. La variable d’environnement "TZ"
   spécifie comment cela est effectué. La fonction définira également
   les variables "tzname" (à partir de la variable d’environnement
   "TZ"), "timezone" (secondes non DST à l’ouest de l’UTC), "altzone"
   (secondes DST à l’ouest de UTC) et "daylight" (à 0 si ce fuseau
   horaire ne comporte aucune règle d’heure d’été, ou non nul s’il
   existe une heure, passée, présente ou future lorsque l’heure d’été
   est appliquée).

   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" et "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 :

      "J*n*"
         Le jour Julien *n* (1 <= *n* <= 365). Les jours bissextiles
         ne sont pas comptabilisés. Par conséquent, le 28 février est
         le 59^e jour et le 1^er Mars est le 60^e 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.

      "M*m*.*n*.*d*"
         Le *d* jour (0 <= *d* <= 6) de la semaine *n* du mois *m* de
         l’année (1 <= *n* <= 5, 1 <= *m* <= 12, où semaine 5 signifie
         “le *dernier* jour du mois *m*” pouvant se produire au cours
         de la quatrième ou de la cinquième semaine). La semaine 1 est
         la première semaine au cours de laquelle le *jour* se
         produit. Le jour zéro est un dimanche.

      "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')


Constantes d’identification d’horloge
=====================================

Ces constantes sont utilisées comme paramètres pour "clock_getres()"
et "clock_gettime()".

time.CLOCK_BOOTTIME

   Identique à "CLOCK_MONOTONIC", sauf qu'elle inclut également toute
   suspension du système.

   Cela permet aux applications d’obtenir une horloge monotone tenant
   compte de la suspension sans avoir à gérer les complications de
   "CLOCK_REALTIME", qui peuvent présenter des discontinuités si
   l’heure est modifiée à l’aide de "settimeofday()" ou similaire.

   Disponibilité : Linux 2.6.39 et ultérieures.

   Nouveau dans la version 3.7.

time.CLOCK_HIGHRES

   Le système d’exploitation Solaris dispose d’une horloge
   "CLOCK_HIGHRES" qui tente d’utiliser une source matérielle optimale
   et peut donner une résolution proche de la nanoseconde.
   "CLOCK_HIGHRES" est l’horloge haute résolution non ajustable.

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

   Disponibilité: Linux 2.6.28 et ultérieur, MacOS 10.12 et ultérieur.

   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_PROF

   Minuterie haute résolution par processus du CPU.

   Disponibilité : FreeBSD, NetBSD 7 ou version ultérieure, OpenBSD.

   Nouveau dans la version 3.7.

time.CLOCK_THREAD_CPUTIME_ID

   Horloge de temps CPU spécifique au thread.

   Disponibilité : Unix.

   Nouveau dans la version 3.3.

time.CLOCK_UPTIME

   Heure dont la valeur absolue correspond à l’heure à laquelle le
   système a été exécuté et non suspendu, fournissant une mesure
   précise du temps de disponibilité, à la fois absolue et à
   intervalle.

   Disponibilité : FreeBSD, OpenBSD 5.5 ou version ultérieure.

   Nouveau dans la version 3.7.

time.CLOCK_UPTIME_RAW

   Horloge qui s'incrémente de manière monotone, en suivant le temps
   écoulé depuis un point arbitraire, n'est pas affectée par les
   ajustements de fréquence ou de temps et n'est pas incrémentée
   lorsque le système est en veille.

   Disponibilité : MacOS 10.12 et ultérieur.

   Nouveau dans la version 3.8.

La constante suivante est le seul paramètre pouvant être envoyé à
"clock_settime()".

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.


Constantes de fuseau horaire
============================

time.altzone

   Décalage du fuseau horaire DST local, en secondes à l’ouest de UTC,
   s’il en est défini un. Cela est négatif si le fuseau horaire DST
   local est à l’est de UTC (comme en Europe occidentale, y compris le
   Royaume-Uni). Utilisez ceci uniquement si "daylight" est différent
   de zéro. Voir note ci-dessous.

time.daylight

   Non nul si un fuseau horaire DST est défini. Voir note ci-dessous.

time.timezone

   Décalage du fuseau horaire local (hors heure d’été), en secondes à
   l’ouest de l’UTC (négatif dans la plupart des pays d’Europe
   occidentale, positif aux États-Unis, nul au Royaume-Uni). Voir note
   ci-dessous.

time.tzname

   Un *tuple* de deux chaînes : la première est le nom du fuseau
   horaire local autre que DST, la seconde est le nom du fuseau
   horaire DST local. Si aucun fuseau horaire DST n’est défini, la
   deuxième chaîne ne doit pas être utilisée. Voir note ci-dessous.

Note:

  Pour les constantes de fuseau horaire ci-dessus ( "altzone",
  "daylight", "timezone" et "tzname"), la valeur est déterminée par
  les règles de fuseau horaire en vigueur au moment du chargement du
  module ou la dernière fois "tzset()" est appelé et peut être
  incorrect pour des temps passés. Il est recommandé d’utiliser
  "tm_gmtoff" et "tm_zone" résulte de "localtime()" pour obtenir des
  informations sur le fuseau horaire.

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