email.generator : génération de documents MIME

Code source : Lib/email/igenerator.py

L'une des tâches les plus courantes consiste à générer la version plate (sérialisée) du message électronique représenté par une structure d'objet message. Vous devez le faire si vous voulez envoyer votre message via smtplib.SMTP.sendmail() ou le module nntplib, ou afficher le message sur la console. Prendre une structure d'objet message et produire une représentation sérialisée est le travail des classes génératrices.

Comme avec le module email.parser, vous n'êtes pas limité aux fonctionnalités du générateur fourni ; vous pourriez en écrire un à partir de zéro vous-même. Cependant, le générateur fourni sait comment générer la plupart des e-mails d'une manière conforme aux normes, est conçu pour gérer correctement les e-mails MIME et non MIME, et pour que les opérations (sur des suites d'octets) d'analyse et de génération soient inverses, en supposant que la même policy est utilisée pour les deux. Autrement dit, l'analyse du flux d'octets sérialisé via la classe BytesParser puis la régénération du flux d'octets sérialisé à l'aide de BytesGenerator devrait produire une sortie identique à l'entrée [1] (d'un autre côté, l'utilisation du générateur sur un EmailMessage construit par programme peut entraîner des modifications de l'objet EmailMessage car les valeurs par défaut sont renseignées).

La classe Generator peut être utilisée pour aplatir un message dans une représentation sérialisée textuelle (par opposition à binaire), mais comme Unicode ne peut pas représenter directement des données binaires, le message est nécessairement transformé en quelque chose qui ne contient que des caractères ASCII, en utilisant les techniques standard de codage de transfert de contenu RFC pour le codage des messages électroniques pour le transport sur des canaux qui ne sont pas « complétement 8 bits ».

Pour s'adapter au traitement reproductible des messages signés SMIME Generator ne raccourcit pas les en-têtes pour les parties de message de type multipart/signed et toutes les sous-parties.

class email.generator.BytesGenerator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Renvoie un objet BytesGenerator qui écrit tout message fourni à la méthode flatten(), ou tout texte encodé par surrogateescape fourni à la méthode write(), dans le objet simili-fichier outfp. outfp doit disposer d'une méthode write qui accepte les données binaires.

Si l'option mangle_from_ est True, place un caractère > devant toute ligne du corps commençant par la chaîne exacte "From ", c'est-à-dire une ligne commençant par From suivi par une espace. mangle_from_ prend par défaut la valeur du paramètre mangle_from_ de la policy (qui est True pour la politique compat32 et False pour tous les autres). mangle_from_ est destiné à être utilisé lorsque les messages sont stockés au format Unix mbox (voir mailbox et WHY THE CONTENT-LENGTH FORMAT IS BAD).

Si maxheaderlen n'est pas None, raccourcit toutes les lignes d'en-tête qui sont plus longues que maxheaderlen, ou si 0, ne raccourcit aucun en-tête. Si manheaderlen est None (valeur par défaut), formate les en-têtes et autres lignes de message en fonction des paramètres de policy.

Si policy est spécifiée, utilise cette politique pour contrôler la génération des messages. Si policy est None (par défaut), utilise la politique associée à l'objet Message ou EmailMessage passée à flatten pour contrôler la génération des messages. Voir email.policy pour plus de détails sur ce que policy contrôle.

Nouveau dans la version 3.2.

Modifié dans la version 3.3: ajout du mot-clé policy.

Modifié dans la version 3.6: le comportement par défaut des paramètres mangle_from_ et maxheaderlen est de suivre la politique.

flatten(msg, unixfrom=False, linesep=None)

Affiche la représentation textuelle de la structure de l'objet message dont la racine est msg dans le fichier de sortie spécifié lors de la création de l'instance BytesGenerator.

Si l'option cte_type de policy est 8bit (valeur par défaut), copie tous les en-têtes du message analysé d'origine qui n'ont pas été modifiés en sortie avec tous les octets dont le bit de poids fort identique à l'original, et conserve le Content-Transfer-Encoding non-ASCII de toutes les parties du corps qui en ont. Si cte_type est 7bit, convertit les octets avec le bit de poids fort défini selon les besoins en utilisant un Content-Transfer-Encoding compatible ASCII. Autrement dit, transforme les parties non ASCII Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit) en un Content-Transfer-Encoding compatible ASCII, et encode les octets non ASCII non valides de la RFC dans les en-têtes utilisant le jeu de caractères MIME unknown-8bit, les rendant ainsi conformes à la RFC.

Si unixfrom est True, affiche le délimiteur d'en-tête d'enveloppe utilisé par le format de boîte aux lettres Unix (voir mailbox) avant le premier des en-têtes RFC 5322 de l'objet message racine. Si l'objet racine n'a pas d'en-tête d'enveloppe, en crée un standard. La valeur par défaut est False. Notez que pour les sous-parties, aucun en-tête d'enveloppe n'est jamais imprimé.

Si linesep n'est pas None, l'utilise comme caractère de séparation entre toutes les lignes du message aplati. Si linesep est None (valeur par défaut), utilise la valeur spécifiée dans la policy.

clone(fp)

Renvoie un clone indépendant de cette instance BytesGenerator avec exactement les mêmes paramètres d'option, et fp comme nouveau outfp.

write(s)

Encode s en utilisant le codec ASCII et le gestionnaire d'erreurs surrogateescape, et le passe à la méthode write du outfp passé au constructeur de BytesGenerator.

Par commodité, EmailMessage fournit les méthodes as_bytes() et bytes(aMessage) (alias __bytes__()), qui simplifient la génération d'une représentation binaire sérialisée d'un objet message. Pour plus de détails, voir email.message.

Comme les chaînes ne peuvent pas représenter des données binaires, la classe Generator doit convertir toutes les données binaires de tout message qu'elle aplatit en un format compatible ASCII, en les convertissant en un Content-Transfer_Encoding compatible ASCII. En utilisant la terminologie des RFC des e-mails, vous pouvez considérer cela comme un Generator sérialisant vers un flux d'entrées-sorties qui n'est pas « complètement 8 bits ». En d'autres termes, la plupart des applications voudront utiliser BytesGenerator et pas Generator.

class email.generator.Generator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Renvoie un objet Generator qui écrit tout message fourni à la méthode flatten(), ou tout texte fourni à la méthode write(), dans l'objet simili-fichier outfp. outfp doit prendre en charge une méthode write qui accepte les données de type chaîne.

Si l'option mangle_from_ est True, place un caractère > devant toute ligne du corps commençant par la chaîne exacte "From ", c'est-à-dire une ligne commençant par From suivi par une espace. mangle_from_ prend par défaut la valeur du paramètre mangle_from_ de la policy (qui est True pour la politique compat32 et False pour tous les autres). mangle_from_ est destiné à être utilisé lorsque les messages sont stockés au format Unix mbox (voir mailbox et WHY THE CONTENT-LENGTH FORMAT IS BAD).

Si maxheaderlen n'est pas None, raccourcit toutes les lignes d'en-tête qui sont plus longues que maxheaderlen, ou si 0, ne raccourcit aucun en-tête. Si manheaderlen est None (valeur par défaut), formate les en-têtes et autres lignes de message en fonction des paramètres de policy.

Si policy est spécifiée, utilise cette politique pour contrôler la génération des messages. Si policy est None (par défaut), utilise la politique associée à l'objet Message ou EmailMessage passée à flatten pour contrôler la génération des messages. Voir email.policy pour plus de détails sur ce que policy contrôle.

Modifié dans la version 3.3: ajout du mot-clé policy.

Modifié dans la version 3.6: le comportement par défaut des paramètres mangle_from_ et maxheaderlen est de suivre la politique.

flatten(msg, unixfrom=False, linesep=None)

Affiche la représentation textuelle de la structure de l'objet message dont la racine est msg dans le fichier de sortie spécifié lors de la création de l'instance Generator.

Si l'option policy cte_type est 8bit, génère le message comme si l'option était définie sur 7bit (c'est nécessaire car les chaînes ne peuvent pas représenter des octets non ASCII). Convertit tous les octets avec le bit de poids fort défini selon les besoins à l'aide d'un Content-Transfer-Encoding compatible ASCII. Autrement dit, transforme les parties non ASCII Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit) en un Content-Transfer-Encoding compatible ASCII, et encode les octets non ASCII non valides RFC dans les en-têtes utilisant le jeu de caractères MIME unknown-8bit, les rendant ainsi conformes à la RFC.

Si unixfrom est True, affiche le délimiteur d'en-tête d'enveloppe utilisé par le format de boîte aux lettres Unix (voir mailbox) avant le premier des en-têtes RFC 5322 de l'objet message racine. Si l'objet racine n'a pas d'en-tête d'enveloppe, en crée un standard. La valeur par défaut est False. Notez que pour les sous-parties, aucun en-tête d'enveloppe n'est jamais imprimé.

Si linesep n'est pas None, l'utilise comme caractère de séparation entre toutes les lignes du message aplati. Si linesep est None (valeur par défaut), utilise la valeur spécifiée dans la policy.

Modifié dans la version 3.2: ajout de la prise en charge du ré-encodage des corps de message 8bit et de l'argument linesep.

clone(fp)

Renvoie un clone indépendant de cette instance Generator avec exactement les mêmes options, et avec fp comme nouveau outfp.

write(s)

Écrit s dans la méthode write de outfp passé au constructeur de Generator. Cela fournit une API ressemblant suffisamment au type fichier pour les instances de Generator utilisées dans la fonction print().

Par commodité, EmailMessage fournit les méthodes as_string() et str(aMessage) (alias __str__()), qui simplifient la génération d'une représentation sous forme de chaîne formatée d'un objet message. Pour plus de détails, voir email.message.

Le module email.generator fournit également une classe dérivée, DecodedGenerator, qui ressemble à la classe de base Generator, sauf que les parties non-text ne sont pas sérialisées, mais sont plutôt représentées dans le flux de sortie par une chaîne dérivée d'un modèle rempli d'informations sur la partie concernée.

class email.generator.DecodedGenerator(outfp, mangle_from_=None, maxheaderlen=None, fmt=None, *, policy=None)

Agit comme Generator, sauf que pour toute sous-partie du message transmise à Generator.flatten(), si la sous-partie est de type principal text, affiche la charge utile décodée de la sous-partie, et si le type principal n'est pas text, au lieu de l'afficher, remplit la chaîne fmt en utilisant les informations de la partie et affiche la chaîne remplie résultante.

Pour remplir fmt, exécute fmt % part_info, où part_info est un dictionnaire composé des clés et valeurs suivantes :

  • type – Type MIME complet de la partie non-text

  • maintype – Type MIME principal de la partie non-text

  • subtype – Sous-type MIME de la partie non-text

  • filename – Nom de fichier de la partie non-text

  • description – Description associée à la partie non-text

  • encoding – Encodage du contenu de la partie non-text

Si fmt est None, utilise le fmt par défaut suivant :

"[Non-text (%(type)s) part of message omitted, filename %(filename)s]"

_mangle_from_ et maxheaderlen sont optionnels et fonctionnent comme avec la classe mère Generator.

Notes