# `email.mime`: Creating email and MIME objects from scratch

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.