"email.mime" : création d'objets e-mail et MIME à partir de zéro
****************************************************************

**Code source :** Lib/email/mime/

======================================================================

Ce module fait partie de l'ancienne API de messagerie ("Compat32"). Sa
fonctionnalité est partiellement remplacée par le "contentmanager"
dans la nouvelle API mais, dans certaines applications, ces classes
peuvent toujours être utiles, même dans du code pas si ancien.

Habituellement, vous obtenez une structure d'objet message en passant
un fichier ou du texte à un analyseur, qui analyse le texte et renvoie
l'objet message racine. Cependant, vous pouvez également créer une
structure de message complète à partir de zéro, ou même des objets
individuels "Message" à la main. En fait, vous pouvez également
prendre une structure existante et ajouter de nouveaux objets
"Message", les déplacer, etc. Cela crée une interface très pratique
pour découper et manipuler chaque morceau de messages MIME.

Vous pouvez créer une nouvelle structure d'objet en créant des
instances "Message", en ajoutant manuellement les pièces jointes et
tous les en-têtes appropriés. Pour les messages MIME cependant, le
paquet "email" fournit quelques sous-classes pratiques pour faciliter
les choses.

Voici les classes :

class email.mime.base.MIMEBase(_maintype, _subtype, *, policy=compat32, **_params)

   Module : "email.mime.base"

   C'est la classe mère pour toutes les sous-classes spécifiques à
   MIME de "Message". Normalement, vous ne créerez pas d'instances
   spécifiques de "MIMEBase", bien que cela soit possible. "MIMEBase"
   est fourni principalement comme une classe mère pratique pour des
   sous-classes plus spécifiques compatibles MIME.

   *_maintype* est le type majeur du *Content-Type* (par exemple
   *text* ou *image*) et *_subtype* est le type mineur du *Content-
   Type* (par exemple, *plain* ou *gif*). *_params* est un paramètre
   dictionnaire clé-valeur et est transmis directement à
   "Message.add_header".

   Si *policy* est spécifiée, (par défaut la politique "compat32")
   elle est passée à "Message".

   La classe "MIMEBase" ajoute toujours un en-tête *Content-Type*
   (basé sur *_maintype*, *_subtype* et *_params*) et un en-tête
   *MIME-Version* (toujours défini à "1.0").

   Modifié dans la version 3.6: ajout du paramètre nommé *policy*.

class email.mime.nonmultipart.MIMENonMultipart

   Module : "email.mime.nonmultipart"

   Sous-classe de "MIMEBase", c'est une classe mère intermédiaire pour
   les messages MIME qui ne sont pas *multipart*. Le but principal de
   cette classe est d'empêcher l'utilisation de la méthode "attach()",
   qui n'a de sens que pour les messages *multipart*. Si "attach()"
   est appelée, une exception "MultipartConversionError" est levée.

class email.mime.multipart.MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, *, policy=compat32, **_params)

   Module : "email.mime.multipart"

   Sous-classe de "MIMEBase", c'est une classe mère intermédiaire pour
   les messages MIME qui sont *multipart*. *_subtype* (facultatif) est
   par défaut *mixed*, mais peut être utilisé pour spécifier le sous-
   type du message. Un en-tête *Content-Type* de *multipart/_subtype*
   sera ajouté à l'objet message. Un en-tête *MIME-Version* sera
   également ajouté.

   *boundary* (facultatif) est la chaîne de délimitation en plusieurs
   parties. Si elle vaut "None" (la valeur par défaut), la
   délimitation est calculée au besoin (par exemple, lorsque le
   message est sérialisé).

   *_subparts* est une séquence de sous-parties initiales pour la
   charge utile. Il doit être possible de convertir cette séquence en
   une liste. Vous pouvez toujours joindre de nouvelles sous-parties
   au message en utilisant la méthode "Message.attach".

   L'argument facultatif *policy* est par défaut "compat32".

   Des paramètres supplémentaires pour l'en-tête *Content-Type* sont
   extraits des arguments nommés ou passés à l'argument *_params*, qui
   est un dictionnaire de mots-clés.

   Modifié dans la version 3.6: ajout du paramètre nommé *policy*.

class email.mime.application.MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

   Module : "email.mime.application"

   Sous-classe de "MIMENonMultipart", la classe "MIMEApplication" est
   utilisée pour représenter les objets de message MIME de type
   principal *application*. *_data* contient les octets pour les
   données d'application brutes. L'option *_subtype* spécifie le sous-
   type MIME et la valeur par défaut est *octet-stream*.

   *_encoder* (facultatif) est un appelable (c'est-à-dire une
   fonction) qui effectue le codage réel des données pour le
   transport. Cet appelable prend un argument, qui est l'instance
   "MIMEApplication". Il doit utiliser "get_payload()" et
   "set_payload()" pour modifier la charge utile sous forme codée. Il
   doit également ajouter n'importe quel *Content-Transfer-Encoding*
   ou d'autres en-têtes à l'objet message si nécessaire. L'encodage
   par défaut est base64. Voir le module "email.encoders" pour une
   liste des encodeurs intégrés.

   L'argument facultatif *policy* est par défaut "compat32".

   Les *_params* sont transmis directement au constructeur de la
   classe mère.

   Modifié dans la version 3.6: ajout du paramètre nommé *policy*.

class email.mime.audio.MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

   Module : "email.mime.audio"

   Sous-classe de "MIMENonMultipart", la classe "MIMEAudio" est
   utilisée pour créer des objets de message MIME de type majeur
   *audio*. *_audiodata* contient les octets pour les données audio
   brutes. Si ces données peuvent être décodées au format *au*, *wav*,
   *aiff* ou *aifc*, alors le sous-type est automatiquement inclus
   dans l'en-tête *Content-Type*. Sinon, vous pouvez spécifier
   explicitement le sous-type audio via l'argument *_subtype*. Si le
   type mineur n'a pas pu être deviné et que *_subtype* n'a pas été
   donné, alors une "TypeError" est levée.

   *_encoder* (facultatif) est un appelable (c'est-à-dire une
   fonction) qui effectue le codage réel des données audio pour le
   transport. Cet appelable prend un argument, qui est l'instance
   "MIMEAudio". Il doit utiliser "get_payload()" et "set_payload()"
   pour modifier la charge utile sous forme codée. Il doit également
   ajouter n'importe quel *Content-Transfer-Encoding* ou d'autres en-
   têtes à l'objet message si nécessaire. L'encodage par défaut est
   base64. Voir le module "email.encoders" pour une liste des
   encodeurs intégrés.

   L'argument facultatif *policy* est par défaut "compat32".

   Les *_params* sont transmis directement au constructeur de la
   classe mère.

   Modifié dans la version 3.6: ajout du paramètre nommé *policy*.

class email.mime.image.MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

   Module : "email.mime.image"

   Sous-classe de "MIMENonMultipart", la classe "MIMEImage" est
   utilisée pour créer des objets de message MIME de type principal
   *image*. *_imagedata* contient les octets pour les données d'image
   brutes. Si ce type de données peut être détecté (*jpeg*, *png*,
   *gif*, *tiff*, *rgb*, *pbm*, *pgm*, *ppm*, *rast*, *xbm*, *bmp*,
   *webp* et *exr* sont essayés), alors le sous-type est
   automatiquement inclus dans l'en-tête *Content-Type*. Sinon, vous
   pouvez spécifier explicitement le sous-type d'image via l'argument
   *_subtype*. Si le type mineur n'a pas pu être deviné et que
   *_subtype* n'a pas été donné, alors une "TypeError" est levée.

   *_encoder* (facultatif) est un appelable (c'est-à-dire une
   fonction) qui effectue le codage réel des données d'image pour le
   transport. Cet appelable prend un argument, qui est l'instance
   "MIMEImage". Il doit utiliser "get_payload()" et "set_payload()"
   pour modifier la charge utile sous forme codée. Il doit également
   ajouter n'importe quel *Content-Transfer-Encoding* ou d'autres en-
   têtes à l'objet message si nécessaire. L'encodage par défaut est
   base64. Voir le module "email.encoders" pour une liste des
   encodeurs intégrés.

   L'argument facultatif *policy* est par défaut "compat32".

   Les *_params* sont transmis directement au constructeur "MIMEBase".

   Modifié dans la version 3.6: ajout du paramètre nommé *policy*.

class email.mime.message.MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32)

   Module : "email.mime.message"

   Sous-classe de "MIMENonMultipart", la classe "MIMEMessage" est
   utilisée pour créer des objets MIME de type principal *message*.
   *_msg* est utilisé comme charge utile et doit être une instance de
   la classe "Message" (ou une sous-classe de celle-ci), sinon une
   "TypeError" est levée.

   L'option *_subtype* définit le sous-type du message ; par défaut
   c'est *rfc822*.

   L'argument facultatif *policy* est par défaut "compat32".

   Modifié dans la version 3.6: ajout du paramètre nommé *policy*.

class email.mime.text.MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32)

   Module : "email.mime.text"

   Sous-classe de "MIMENonMultipart", la classe "MIMEText" est
   utilisée pour créer des objets MIME de type principal *text*.
   *_text* est la chaîne de la charge utile. *_subtype* est le type
   mineur et par défaut est *plain*. *_charset* est le jeu de
   caractères du texte et est passé en argument au constructeur
   "MIMENonMultipart" ; sa valeur par défaut est "us-ascii" si la
   chaîne ne contient que des points de code "ascii", et "utf-8"
   sinon. Le paramètre *_charset* accepte soit une chaîne soit une
   instance "Charset".

   À moins que l'argument *_charset* ne soit explicitement défini sur
   "None", l'objet *MIMEText* créé possède à la fois un en-tête
   *Content-Type* avec un paramètre "charset" et un en-tête *Content-
   Transfer-Encoding*. Cela signifie qu'un appel ultérieur à
   "set_payload" n'entraîne pas l'encodage de la charge utile, même si
   un jeu de caractères est passé dans la commande "set_payload". Vous
   pouvez « réinitialiser » ce comportement en supprimant l'en-tête
   "Content-Transfer-Encoding", après quoi un appel "set_payload"
   encodera automatiquement la nouvelle charge utile (et ajoutera un
   nouvel en-tête *Content-Transfer-Encoding*).

   L'argument facultatif *policy* est par défaut "compat32".

   Modifié dans la version 3.5: *_charset* accepte également les
   instances "Charset".

   Modifié dans la version 3.6: ajout du paramètre nommé *policy*.
