"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 ]-

[1] This statement assumes that you use the appropriate setting for
    "unixfrom", and that there are no "email.policy" settings calling
    for automatic adjustments (for example, "refold_source" must be
    "none", which is *not* the default).  It is also not 100% true,
    since if the message does not conform to the RFC standards
    occasionally information about the exact original text is lost
    during parsing error recovery.  It is a goal to fix these latter
    edge cases when possible.
