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
isNone
), 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.13: 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 lerealname
contient des caractères non-ASCII. Cela peut être une instance destr
ou unCharset
. La valeur par défaut estutf-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 byMessage.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.13: 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()
; sinonNone
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 soitNone
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é est0
, 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 queparsedate()
mais, en cas de succès, renvoie undatetime
; sinon uneValueError
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
, ledatetime
sera undatetime
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, ledatetime
sera undatetime
avisé avec letimezone
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 estNone
, 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()
andtime.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 estFalse
, 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 ASCIIGMT
, plutôt qu'un-0000
numérique. C'est nécessaire pour certains protocoles (tels que HTTP). Cela ne s'applique que lorsque localtime estFalse
. La valeur par défaut estFalse
.
- email.utils.format_datetime(dt, usegmt=False)¶
Comme
formatdate
, mais l'entrée est une instancedatetime
. 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'undatetime
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 surTrue
, la chaîneGMT
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.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éthodeencode()
destr
; 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