"email.utils": Miscellaneous utilities
**************************************

**Code source :** Lib/email/utils.py

======================================================================

Il y a quelques utilitaires utiles fournis dans le module
"email.utils" :

email.utils.localtime(dt=None)

   Return local time as an aware datetime object.  If called without
   arguments, return current time.  Otherwise *dt* argument should be
   a "datetime" instance, and it is converted to the local time zone
   according to the system time zone database.  If *dt* is naive (that
   is, "dt.tzinfo" is "None"), it is assumed to be in local time.  The
   *isdst* parameter is ignored.

   Added in version 3.3.

   Obsolète depuis la version 3.12, sera supprimé dans la version
   3.14: The *isdst* parameter.

email.utils.make_msgid(idstring=None, domain=None)

   Renvoie une chaîne adaptée à un en-tête  *Message-ID* compatible
   **RFC 2822**. *idstring*, s'il est fourni, est une chaîne utilisée
   pour renforcer l'unicité de l'identifiant du message. Le *domain*
   facultatif, s'il est fourni, fournit la partie du *msgid* après le
   '@'. La valeur par défaut est le nom d'hôte local. Il n'est
   normalement pas nécessaire de remplacer cette valeur par défaut,
   mais cela peut être utile dans certains cas, comme la construction
   d'un système distribué qui utilise un nom de domaine cohérent sur
   plusieurs hôtes.

   Modifié dans la version 3.2: ajout du mot-clé *domaine*.

Les fonctions restantes font partie de l'ancienne API de messagerie
("Compat32"). Il n'est pas nécessaire de les utiliser directement avec
la nouvelle API, car l'analyse et le formatage qu'elles fournissent
sont effectués automatiquement par le mécanisme d'analyse d'en-tête de
la nouvelle API.

email.utils.quote(str)

   Renvoie une nouvelle chaîne avec les barres obliques inverses
   (*backslash*) dans *str* remplacées par deux barres obliques
   inverses et les guillemets doubles remplacés par des guillemets
   doubles échappés par une barre oblique inverse.

email.utils.unquote(str)

   Renvoie une nouvelle chaîne qui est une version *sans guillemets*
   de *str*. Si *str* se termine et commence par des guillemets
   doubles, ils sont supprimés. De même, si *str* est encadrée par des
   chevrons mathématiques, ils sont supprimés.

email.utils.parseaddr(address)

   Analyse l'adresse – qui devrait être la valeur d'un champ contenant
   une adresse tel que *To* ou *Cc* – dans ses parties constituantes
   *realname* et *email address*. Renvoie un *n*-uplet de cette
   information, sauf si l'analyse échoue, alors un couple "('', '')"
   est renvoyé.

email.utils.formataddr(pair, charset='utf-8')

   L'inverse de "parseaddr()", elle prend un couple de la forme
   "(realname, email_address)" et renvoie la valeur de chaîne
   appropriée pour un en-tête *To* ou *Cc*. Si le premier élément de
   *pair* s'évalue à faux, alors le deuxième élément est renvoyé sans
   modification.

   Le *charset* optionnel est le jeu de caractères qui est utilisé
   dans l'encodage **RFC 2047** du "realname" si le "realname"
   contient des caractères non-ASCII. Cela peut être une instance de
   "str" ou un "Charset". La valeur par défaut est "utf-8".

   Modifié dans la version 3.3: ajout de l'option *charset*.

email.utils.getaddresses(fieldvalues)

   Cette méthode renvoie une liste de couples de la forme renvoyée par
   "parseaddr()". *fieldvalues* est une séquence de valeurs de champ d
   'en-tête pouvant être renvoyée par "Message.get_all". Voici un
   exemple simple qui récupère tous les destinataires d'un message :

      from email.utils import getaddresses

      tos = msg.get_all('to', [])
      ccs = msg.get_all('cc', [])
      resent_tos = msg.get_all('resent-to', [])
      resent_ccs = msg.get_all('resent-cc', [])
      all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)

email.utils.parsedate(date)

   Tente d'analyser une date selon les règles de la **RFC 2822**.
   Cependant, certains expéditeurs ne suivent pas ce format comme
   spécifié, donc "parsedate()" fait son possible dans de tels cas.
   *date* est une chaîne contenant une date **RFC 2822**, telle que
   ""Mon, 20 Nov 1995 19:12:08 -0500"". Si elle réussit à analyser la
   date, "parsedate()" renvoie un 9-uplet qui peut être passé
   directement à "time.mktime()" ; sinon "None" est renvoyé. Notez que
   les indices 6, 7 et 8 du *n*-uplet résultat ne sont pas
   utilisables.

email.utils.parsedate_tz(date)

   Effectue la même fonction que "parsedate()", mais renvoie soit
   "None" ou un 10-uplet ; les 9 premiers éléments constituent un
   *n*-uplet qui peut être passé directement à "time.mktime()", et le
   dixième est le décalage du fuseau horaire de la date par rapport à
   UTC (qui est le terme officiel pour *Greenwich Mean Time*) [1]. Si
   la chaîne d'entrée n'a pas de fuseau horaire, le dernier élément du
   *n*-uplet renvoyé est "0", qui représente l'UTC. Notez que les
   indices 6, 7 et 8 du *n*-uplet résultat ne sont pas utilisables.

email.utils.parsedate_to_datetime(date)

   L'inverse de "format_datetime()". Effectue la même fonction que
   "parsedate()" mais, en cas de succès, renvoie un "datetime" ; sinon
   une "ValueError" est levée si *date* contient une valeur invalide
   telle qu'une heure supérieure à 23 ou un décalage de fuseau horaire
   non compris entre −24 et 24 heures. Si la date d'entrée a un fuseau
   horaire de "-0000", le "datetime" sera un "datetime" naïf, et si la
   date est conforme aux RFC, elle représentera une heure en UTC mais
   sans indication du fuseau horaire source réel du message d'où
   provient la date. Si la date d'entrée a un autre décalage de fuseau
   horaire valide, le "datetime" sera un "datetime" avisé avec le
   "timezone" "tzinfo" adéquat.

   Added in version 3.3.

email.utils.mktime_tz(tuple)

   Transforme un 10-uplet renvoyé par "parsedate_tz()" en un
   horodatage UTC (en secondes depuis *Epoch*). Si l'élément de fuseau
   horaire dans le *n*-uplet est "None", elle considère que l'heure
   est locale.

email.utils.formatdate(timeval=None, localtime=False, usegmt=False)

   Renvoie une chaîne de date conforme à la **RFC 2822**, par exemple
   :

      Fri, 09 Nov 2001 01:08:47 -0000

   *timeval*, s'il est fourni, est une valeur de temps à virgule
   flottante telle qu'acceptée par "time.gmtime()" et
   "time.localtime()", sinon l'heure actuelle est utilisée.

   L'option *localtime* est un indicateur qui, lorsqu'il est "True",
   interprète *timeval* et renvoie une date relative au fuseau horaire
   local au lieu de UTC, en tenant correctement compte de l'heure
   d'été. La valeur par défaut est "False", ce qui signifie que l'UTC
   est utilisée.

   L'option *usegmt* est un indicateur qui, lorsqu'il est "True",
   affiche une chaîne de date avec le fuseau horaire sous la forme de
   la chaîne ASCII "GMT", plutôt qu'un "-0000" numérique. C'est
   nécessaire pour certains protocoles (tels que HTTP). Cela ne
   s'applique que lorsque *localtime* est "False". La valeur par
   défaut est "False".

email.utils.format_datetime(dt, usegmt=False)

   Comme "formatdate", mais l'entrée est une instance "datetime". S'il
   s'agit d'un groupe date-heure naïf, il est considéré être « UTC
   sans information sur le fuseau horaire source », et le "-0000"
   conventionnel est utilisé pour le fuseau horaire. S'il s'agit d'un
   "datetime" avisé, alors le décalage numérique du fuseau horaire est
   utilisé. S'il s'agit d'un groupe date-heure avisé avec un décalage
   de fuseau horaire de zéro, alors *usegmt* peut être défini sur
   "True", la chaîne "GMT" est alors utilisée à la place du décalage
   numérique du fuseau horaire. Cela fournit un moyen de générer des
   en-têtes de date HTTP conformes aux normes.

   Added in version 3.3.

email.utils.decode_rfc2231(s)

   Décode la chaîne *s* selon la **RFC 2231**.

email.utils.encode_rfc2231(s, charset=None, language=None)

   Encode la chaîne *s* selon la **RFC 2231**. *charset* et
   *language*, s'ils sont fournis, indiquent le jeu de caractères et
   le nom de la langue à utiliser. Si aucun n'est donné, *s* est
   renvoyé telle quelle. Si *charset* est donné mais que *language* ne
   l'est pas, la chaîne est encodée en utilisant la chaîne vide pour
   *language*.

email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')

   Lorsqu'un paramètre d'en-tête est encodé au format **RFC 2231**,
   "Message.get_param" peut renvoyer un triplet contenant le jeu de
   caractères, la langue et la valeur. "collapse_rfc2231_value()"
   transforme cela en une chaîne Unicode. *errors* (facultatif) est
   passé à l'argument *errors* de la méthode "encode()" de "str" ; sa
   valeur par défaut est "'replace'". *fallback_charset* (facultatif)
   spécifie le jeu de caractères à utiliser si celui de l'en-tête
   **RFC 2231** n'est pas connu de Python ; sa valeur par défaut est
   "'us-ascii'".

   Pour plus de commodité, si la *valeur* transmise à
   "collapse_rfc2231_value()" n'est pas un *n*-uplet, ce doit être une
   chaîne et elle est renvoyée sans guillemets.

email.utils.decode_params(params)

   Décode la liste des paramètres selon la **RFC 2231**. *params* est
   une séquence de couples contenant des éléments de la forme
   "(content-type, string-value)".

-[ Notes ]-

[1] Notez que le signe du décalage horaire est l'opposé du signe de la
    variable "time.timezone" pour le même fuseau horaire ; cette
    dernière variable suit la norme POSIX tandis que ce module suit la
    **RFC 2822**.
