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.

Ajouté dans la version 3.3.

Deprecated since version 3.12, will be removed in 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, *, strict=True)

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

If strict is true, use a strict parser which rejects malformed inputs.

Modifié dans la version 3.12.6: Add strict optional parameter and reject malformed inputs by default.

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, *, strict=True)

This method returns a list of 2-tuples of the form returned by parseaddr(). fieldvalues is a sequence of header field values as might be returned by Message.get_all.

If strict is true, use a strict parser which rejects malformed inputs.

Here's a simple example that gets all the recipients of a 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)

Modifié dans la version 3.12.6: Add strict optional parameter and reject malformed inputs by default.

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.

Ajouté dans la 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

Optional timeval if given is a floating-point time value as accepted by time.gmtime() and time.localtime(), otherwise the current time is used.

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.

Ajouté dans la 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