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.