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