email.message.Message : représentation d'un message électronique à l'aide de l'API compat32

La classe Message est très similaire à la classe EmailMessage, sans les méthodes ajoutées par cette classe et avec le comportement par défaut légèrement différent pour certaines autres méthodes. Nous documentons également ici certaines méthodes qui, bien que prises en charge par la classe EmailMessage, ne sont pas recommandées, sauf si vous avez affaire à du code hérité.

La philosophie et la structure des deux classes sont par ailleurs les mêmes.

Ce document décrit le comportement avec les règles par défaut (pour Message) Compat32. Si vous envisagez d'utiliser d'autres règles, vous devriez plutôt utiliser la classe EmailMessage.

Un message électronique se compose d'en-têtes et d'une charge utile. Les en-têtes doivent être des noms et des valeurs de style RFC 5322, où le nom et la valeur du champ sont séparés par deux-points. Les deux-points ne font partie ni du nom du champ ni de la valeur du champ. La charge utile peut être un simple message texte, ou un objet binaire, ou une séquence structurée de sous-messages chacun avec son propre ensemble d'en-têtes et sa propre charge utile. Ce dernier type de charge utile est indiqué par le message ayant un type MIME tel que multipart/* ou message/rfc822.

Le modèle conceptuel fourni par un objet Message est celui d'un dictionnaire ordonné d'en-têtes avec des méthodes supplémentaires pour accéder à la fois aux informations spécialisées des en-têtes, pour accéder à la charge utile, pour générer une version sérialisée du message et pour parcourir récursivement l'arbre d'objets. Notez que les en-têtes en double sont pris en charge mais que des méthodes spéciales doivent être utilisées pour y accéder.

Le pseudo-dictionnaire Message est indicé par les noms d'en-tête, qui doivent être des valeurs ASCII. Les valeurs du dictionnaire sont des chaînes censées contenir uniquement des caractères ASCII ; il existe une gestion spéciale pour les entrées non ASCII, mais cela ne produit pas toujours les résultats corrects. Les en-têtes sont stockés et renvoyés sous une forme respectant la casse, mais les noms de champ sont mis en correspondance sans tenir compte de la casse. Il peut également y avoir un seul en-tête d'enveloppe, également appelé en-tête Unix-From ou en-tête From_. La charge utile est soit une chaîne ou des octets, dans le cas d'objets message simples, soit une liste d'objets Message, pour les documents conteneurs MIME (par exemple multipart/* et message/rfc822).

Voici les méthodes de la classe Message :

class email.message.Message(policy=compat32)

Si policy est spécifié (il doit s'agir d'une instance d'une classe policy), utilise les règles spécifiées pour mettre à jour et sérialiser la représentation du message. Si policy n'est pas défini, utilise les règles compat32, qui maintient la rétrocompatibilité avec la version Python 3.2 du paquet de messagerie. Pour plus d'informations, consultez la documentation policy.

Modifié dans la version 3.3: l'argument nommé policy a été ajouté.

as_string(unixfrom=False, maxheaderlen=0, policy=None)

Renvoie le message entier aplati sous forme de chaîne. Lorsque l'option unixfrom est vraie, l'en-tête de l'enveloppe est inclus dans la chaîne renvoyée. unixfrom par défaut est False. Pour des raisons de compatibilité descendante, maxheaderlen est par défaut à 0, donc si vous voulez une valeur différente, vous devez la remplacer explicitement (la valeur spécifiée pour max_line_length dans la politique sera ignorée par cette méthode). L'argument policy peut être utilisé pour remplacer les règles par défaut obtenues à partir de l'instance de message. Cela peut être utilisé pour contrôler une partie du formatage produit par la méthode, puisque la policy spécifiée est transmise au Generator.

L'aplatissement du message peut déclencher des changements dans Message si les valeurs par défaut doivent être renseignées pour terminer la transformation en chaîne (par exemple, les limites MIME peuvent être générées ou modifiées).

Notez que cette méthode est fournie à titre de commodité et peut ne pas toujours formater le message comme vous le souhaitez. Par exemple, par défaut, elle ne reformate pas les lignes qui commencent par From qui est requis par le format mbox Unix. Pour plus de flexibilité, instanciez une instance Generator et utilisez sa méthode flatten() directement. Par exemple :

from io import StringIO
from email.generator import Generator
fp = StringIO()
g = Generator(fp, mangle_from_=True, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()

Si l'objet message contient des données binaires qui ne sont pas encodées selon les normes RFC, les données non conformes seront remplacées par des points de code Unicode « caractère inconnu » (voir aussi as_bytes() et BytesGenerator).

Modifié dans la version 3.4: l'argument nommé policy a été ajouté.

__str__()

Équivalent à as_string(). Permet à str(msg) de produire une chaîne contenant le message formaté.

as_bytes(unixfrom=False, policy=None)

Renvoie le message entier aplati en tant qu'objet bytes. Lorsque l'option unixfrom est vraie, l'en-tête de l'enveloppe est inclus dans la chaîne renvoyée. unixfrom par défaut est False. L'argument policy peut être utilisé pour remplacer les règles par défaut obtenues à partir de l'instance de message. Cela peut être utilisé pour contrôler une partie du formatage produit par la méthode, puisque la policy spécifiée est passée au BytesGenerator.

L'aplatissement du message peut déclencher des changements dans Message si les valeurs par défaut doivent être renseignées pour terminer la transformation en chaîne (par exemple, les limites MIME peuvent être générées ou modifiées).

Notez que cette méthode est fournie à titre de commodité et peut ne pas toujours formater le message comme vous le souhaitez. Par exemple, par défaut, elle ne reformate pas les lignes qui commencent par From qui est requis par le format mbox Unix. Pour plus de flexibilité, instanciez une instance BytesGenerator et utilisez sa méthode flatten() directement. Par exemple :

from io import BytesIO
from email.generator import BytesGenerator
fp = BytesIO()
g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()

Nouveau dans la version 3.4.

__bytes__()

Équivalent à as_bytes(). Permet à bytes(msg) de produire un objet bytes contenant le message formaté.

Nouveau dans la version 3.4.

is_multipart()

Renvoie True si la charge utile du message est une liste d'objets sous-Message, sinon renvoie False. Lorsque is_multipart() renvoie False, la charge utile doit être un objet chaîne (qui peut être une charge utile binaire encodée CTE). (Notez que is_multipart() renvoyant True ne signifie pas nécessairement que msg.get_content_maintype() == 'multipart' renvoie True. Par exemple, is_multipart renvoie True lorsque le Message est de type message/rfc822.)

set_unixfrom(unixfrom)

Définit l'en-tête de l'enveloppe du message sur unixfrom, qui doit être une chaîne.

get_unixfrom()

Renvoie l'en-tête de l'enveloppe du message. La valeur par défaut est None si l'en-tête de l'enveloppe n'a jamais été défini.

attach(payload)

Ajoute le payload donné à la charge utile actuelle, qui doit être None ou une liste d'objets Message avant l'appel. Après l'appel, la charge utile sera toujours une liste d'objets Message. Si vous souhaitez définir la charge utile sur un objet scalaire (par exemple, une chaîne), utilisez set_payload() à la place.

Il s'agit d'une ancienne méthode. Dans la classe EmailMessage sa fonctionnalité est remplacée par set_content() et les méthodes associées make et add.

get_payload(i=None, decode=False)

Renvoie la charge utile actuelle, qui est une liste d'objets Message lorsque is_multipart() est True, ou une chaîne lorsque is_multipart() est False. Si la charge utile est une liste et que vous modifiez l'objet liste, vous modifiez la charge utile du message « sur place ».

Avec l'argument optionnel i, get_payload() renvoie le i^ème élément de la charge utile, en partant de zéro, si is_multipart() vaut True. Une IndexError est levée si i est inférieur à 0 ou supérieur ou égal au nombre d'éléments dans la charge utile. Si la charge utile est une chaîne (c'est-à-dire que is_multipart() est False) et que i est donné, une TypeError est levée.

decode est un indicateur facultatif indiquant si la charge utile doit être décodée ou non, selon l'en-tête Content-Transfer-Encoding. Lorsqu'il vaut True et que le message n'est pas en plusieurs parties, la charge utile est décodée si la valeur de cet en-tête est quoted-printable ou base64. Si un autre encodage est utilisé, ou si l'en-tête Content-Transfer-Encoding est manquant, la charge utile est renvoyée telle quelle (non décodée). Dans tous les cas, la valeur renvoyée est une donnée binaire. Si le message est en plusieurs parties et que l'indicateur decode est True, alors None est renvoyé. Si la charge utile est en base64 et qu'elle n'a pas été parfaitement formée (remplissage manquant, caractères en dehors de l'alphabet base64), alors un défaut approprié est ajouté à la propriété de défaut du message (InvalidBase64PaddingDefect ou InvalidBase64CharactersDefect, respectivement).

Lorsque decode est False (valeur par défaut), le corps est renvoyé sous forme de chaîne sans décoder le Content-Transfer-Encoding. Cependant, pour un Content-Transfer-Encoding de 8 bits, une tentative est faite pour décoder les octets d'origine en utilisant le charset spécifié par l'en-tête Content-Type, en utilisant le gestionnaire d'erreurs replace. Si aucun charset n'est spécifié, ou si le charset donné n'est pas reconnu par le paquet de messagerie, le corps est décodé en utilisant le jeu de caractères ASCII par défaut.

Il s'agit d'une ancienne méthode. Dans la classe EmailMessage sa fonctionnalité est remplacée par get_content() et iter_parts().

set_payload(payload, charset=None)

Définit la charge utile de l'objet message entier à payload. Il est de la responsabilité du client de s'assurer des invariants de la charge utile. Le charset facultatif définit le jeu de caractères par défaut du message ; voir set_charset() pour plus de détails.

Il s'agit d'une ancienne méthode. Dans la classe EmailMessage sa fonctionnalité est remplacée par set_content().

set_charset(charset)

Définit le jeu de caractères de la charge utile à charset, qui peut être soit une instance de Charset (voir email.charset), une chaîne nommant un jeu de caractères ou None. S'il s'agit d'une chaîne, elle est convertie en une instance Charset. Si charset est None, le paramètre charset est supprimé de l'en-tête Content-Type (le message n'est pas modifié autrement). Tout le reste lève une TypeError.

S'il n'y a pas d'en-tête MIME-Version existant, un en-tête est ajouté. S'il n'y a pas d'en-tête Content-Type, un en-tête est ajouté avec une valeur de text/plain. Que l'en-tête Content-Type existe déjà ou non, son paramètre charset est défini sur charset.output_charset. Si charset.input_charset et charset.output_charset diffèrent, la charge utile est ré-encodée dans le output_charset. S'il n'y a pas d'en-tête Content-Transfer-Encoding existant, alors la charge utile est encodée par transfert, si nécessaire, en utilisant le Charset spécifié et un en-tête avec cette valeur est ajouté. Si un en-tête Content-Transfer-Encoding existe déjà, la charge utile est supposée être déjà correctement encodée à l'aide de cet en-tête Content-Transfer-Encoding et n'est pas modifiée.

Il s'agit d'une ancienne méthode. Dans la classe EmailMessage sa fonctionnalité est remplacée par le paramètre charset de la méthode email.emailmessage.EmailMessage.set_content().

get_charset()

Renvoie l'instance Charset associée à la charge utile du message.

Il s'agit d'une ancienne méthode. Dans la classe EmailMessage, elle renvoie toujours None.

Les méthodes suivantes implémentent une interface de type correspondance pour accéder aux en-têtes RFC 2822 du message. Notez qu'il existe des différences sémantiques entre ces méthodes et une interface de correspondance normale (c'est-à-dire un dictionnaire). Par exemple, dans un dictionnaire, il n'y a pas de clés en double, mais ici, il peut y avoir des en-têtes de message en double. De plus, dans les dictionnaires, il n'y a pas d'ordre garanti pour les clés renvoyées par keys(), mais dans un objet Message, les en-têtes sont toujours renvoyés dans l'ordre dans lequel ils sont apparus dans le message d'origine, ou ont été ajoutés au message plus tard. Tout en-tête supprimé puis rajouté est toujours ajouté à la fin de la liste des en-têtes.

Ces différences sémantiques sont intentionnelles et visent une commodité maximale.

Notez que dans tous les cas, tout en-tête d'enveloppe présent dans le message n'est pas inclus dans l'interface de correspondance.

Dans un modèle généré à partir d'octets, toutes les valeurs d'en-tête qui (en violation des RFC) contiennent des octets non-ASCII sont, lorsqu'elles sont récupérées via cette interface, représentées comme des objets Header avec un charset à unknown-8bit.

__len__()

Renvoie le nombre total d'en-têtes, y compris les doublons.

__contains__(name)

Renvoie True si l'objet message a un champ nommé name. La correspondance est insensible à la casse et name ne doit pas inclure les deux-points à la fin. Utilisé pour l'opérateur in, par exemple :

if 'message-id' in myMessage:
   print('Message-ID:', myMessage['message-id'])

__getitem__(name)

Renvoie la valeur du champ d'en-tête désigné. name ne doit pas inclure le séparateur de champ deux-points. Si l'en-tête est manquant, None est renvoyé ; KeyError n'est jamais levée.

Notez que si le champ désigné apparaît plus d'une fois dans les en-têtes du message, la valeur exacte renvoyée n'est pas définie. Utilisez la méthode get_all() pour obtenir les valeurs de tous les en-têtes existants.

__setitem__(name, val)

Ajoute un en-tête au message avec le nom de champ name et la valeur val. Le champ est ajouté à la fin des champs existants du message.

Notez que cela n'écrase pas ou ne supprime aucun en-tête existant portant le même nom. Si vous voulez vous assurer que le nouvel en-tête est le seul présent dans le message avec le nom de champ name, supprimez d'abord le champ, par exemple :

del msg['subject']
msg['subject'] = 'Python roolz!'

__delitem__(name)

Supprime toutes les occurrences du champ portant le nom name des en-têtes du message. Aucune exception n'est levée si le champ désigné n'est pas présent dans les en-têtes.

keys()

Renvoie une liste de tous les noms de champs d'en-tête du message.

values()

Renvoie une liste de toutes les valeurs de champ du message.

items()

Renvoie une liste de couples contenant tous les en-têtes et valeurs de champs associées du message.

get(name, failobj=None)

Return the value of the named header field. This is identical to __getitem__() except that optional failobj is returned if the named header is missing (defaults to None).

Voici quelques méthodes supplémentaires utiles :

get_all(name, failobj=None)

Renvoie la liste de toutes les valeurs du champ nommé name. S'il n'y a pas d'en-têtes de ce nom dans le message, failobj est renvoyé (la valeur par défaut est None).

add_header(_name, _value, **_params)

Définition de paramètres d'en-têtes étendus. Cette méthode est similaire à __setitem__() sauf que des paramètres d'en-tête supplémentaires peuvent être fournis en tant qu'arguments nommés. _name est le champ d'en-tête à ajouter et _value est la valeur primaire de l'en-tête.

Pour chaque élément du dictionnaire d'arguments nommés _params, la clé est prise comme nom de paramètre, avec des traits de soulignement convertis en tirets (puisque les tirets sont illégaux dans les identifiants Python). Normalement, le paramètre est ajouté en tant que key="value" sauf si la valeur est None, auquel cas seule la clé est ajoutée. Si la valeur contient des caractères non-ASCII, elle peut être spécifiée sous la forme d'un triplet au format (CHARSET, LANGUAGE, VALUE), où CHARSET est une chaîne nommant le jeu de caractères à utiliser pour coder la valeur, LANGUAGE peut généralement être défini sur None ou la chaîne vide (voir la RFC 2231 pour d'autres possibilités), et VALUE est la valeur de chaîne contenant des points de code non-ASCII. Si un triplet n'est pas passé et que la valeur contient des caractères non-ASCII, elle est automatiquement encodée au format RFC 2231 en utilisant un CHARSET à utf-8 et un LANGUAGE à None.

Voici un exemple :

msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')

Cela ajoute un en-tête qui ressemble à :

Content-Disposition: attachment; filename="bud.gif"

Un exemple avec des caractères non-ASCII :

msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '', 'Fußballer.ppt'))

qui produit :

Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"

replace_header(_name, _value)

Remplace un en-tête. Remplace le premier en-tête trouvé dans le message qui correspond à _name, en conservant l'ordre des en-têtes et la casse des noms de champs. Si aucun en-tête correspondant n'a été trouvé, une KeyError est levée.

get_content_type()

Renvoie le type de contenu du message. La chaîne renvoyée est convertie en minuscules sous la forme maintype/subtype. S'il n'y avait pas d'en-tête Content-Type dans le message, le type par défaut tel qu'indiqué par get_default_type() est renvoyé. Puisque selon la RFC 2045, les messages ont toujours un type par défaut, get_content_type() renvoie toujours une valeur.

La RFC 2045 définit le type par défaut d'un message comme étant text/plain sauf s'il apparaît dans un conteneur multipart/digest, auquel cas ce serait message/rfc822. Si l'en-tête Content-Type a une spécification de type invalide, la RFC 2045 exige que le type par défaut soit text/plain.

get_content_maintype()

Renvoie le type de contenu principal du message. C'est la partie maintype de la chaîne renvoyée par get_content_type().

get_content_subtype()

Renvoie le type de sous-contenu du message. C'est la partie subtype de la chaîne renvoyée par get_content_type().

get_default_type()

Renvoie le type de contenu par défaut. La plupart des messages ont un type de contenu par défaut de text/plain, à l'exception des messages qui sont des sous-parties des conteneurs multipart/digest. Ces sous-parties ont un type de contenu par défaut de message/rfc822.

set_default_type(ctype)

Définit le type de contenu par défaut. ctype doit être text/plain ou message/rfc822, bien que cela ne soit pas appliqué. Le type de contenu par défaut n'est pas stocké dans l'en-tête Content-Type.

get_params(failobj=None, header='content-type', unquote=True)

Renvoie les paramètres Content-Type du message, sous forme de liste. Les éléments de la liste renvoyée sont des couples clé-valeur, ayant été séparés sur le signe '='. Le côté gauche du '=' est la clé, tandis que le côté droit est la valeur. S'il n'y a pas de signe '=' dans le paramètre, la valeur est la chaîne vide, sinon la valeur est telle que décrite dans get_param() et n'est pas entre guillemets si l'option unquote est True (la valeur par défaut).

failobj (facultatif) est l'objet à renvoyer s'il n'y a pas d'en-tête Content-Type. header (facultatif) est l'en-tête à rechercher au lieu de Content-Type.

Il s'agit d'une ancienne méthode. Dans la classe EmailMessage, sa fonctionnalité est remplacée par la propriété params des objets d'en-tête individuels renvoyés par les méthodes d'accès aux en-têtes.

get_param(param, failobj=None, header='content-type', unquote=True)

Renvoie la valeur du paramètre param de l'en-tête Content-Type sous forme de chaîne. Si le message n'a pas d'en-tête Content-Type ou s'il n'y a pas un tel paramètre, alors failobj est renvoyé (par défaut à None).

header s'il est fourni, spécifie l'en-tête de message à utiliser à la place de Content-Type.

Les clés en paramètre sont toujours comparées sans tenir compte de la casse. La valeur de retour peut être soit une chaîne, soit un triplet si le paramètre a été encodé selon la RFC 2231. Lorsqu'il s'agit d'un triplet, les éléments de la valeur sont de la forme (CHARSET, LANGUAGE, VALUE). Notez que CHARSET et LANGUAGE peuvent être None, vous devriez alors considérer que VALUE est encodé dans le jeu de caractères us-ascii. Vous pouvez généralement ignorer LANGUAGE.

Si votre application ne se soucie pas de savoir si le paramètre a été encodé conformément à la RFC 2231, vous pouvez réduire la valeur du paramètre en appelant email.utils.collapse_rfc2231_value(), en transmettant la valeur de retour de get_param(). Cela renverra une chaîne Unicode convenablement décodée lorsque la valeur est un n-uplet, ou la chaîne d'origine sans guillemets si ce n'est pas le cas. Par exemple :

rawparam = msg.get_param('foo')
param = email.utils.collapse_rfc2231_value(rawparam)

Dans tous les cas, la valeur du paramètre (soit la chaîne renvoyée, soit l'élément VALUE dans le triplet) est toujours sans guillemets, sauf si unquote est défini sur False.

Il s'agit d'une ancienne méthode. Dans la classe EmailMessage, sa fonctionnalité est remplacée par la propriété params des objets d'en-tête individuels renvoyés par les méthodes d'accès aux en-têtes.

set_param(param, value, header='Content-Type', requote=True, charset=None, language='', replace=False)

Définit un paramètre dans l'en-tête Content-Type. Si le paramètre existe déjà dans l'en-tête, sa valeur est remplacée par value. Si l'en-tête Content-Type n'a pas encore été défini pour ce message, il est défini à text/plain et la nouvelle valeur du paramètre est ajoutée conformément à la RFC 2045.

L'option header spécifie un en-tête alternatif à Content-Type, et tous les paramètres seront entre guillemets si nécessaire sauf si l'option requote est False (la valeur par défaut est True).

Si charset est spécifié, le paramètre est encodé selon la RFC 2231. language (facultatif) spécifie la langue RFC 2231, par défaut c'est la chaîne vide. charset et language doivent être des chaînes.

Si replace est False (valeur par défaut), l'en-tête est déplacé à la fin de la liste des en-têtes. Si replace est True, l'en-tête est mis à jour « sur place ».

Modifié dans la version 3.4: l'argument nommé replace a été ajouté.

del_param(param, header='content-type', requote=True)

Supprime complètement le paramètre donné de l'en-tête Content-Type. L'en-tête est réécrit « sur place » sans le paramètre ou sa valeur. Toutes les valeurs seront entre guillemets si nécessaire sauf si requote est False (la valeur par défaut est True). L'option header spécifie une alternative à Content-Type.

set_type(type, header='Content-Type', requote=True)

Définit le type principal et le sous-type de l'en-tête Content-Type. type doit être une chaîne sous la forme maintype/subtype, sinon une ValueError est levée.

Cette méthode remplace l'en-tête Content-Type, en gardant tous les paramètres en place. Si requote est False, cela laisse les guillemets de l'en-tête existant tels quels, sinon les paramètres sont mis entre guillemets (par défaut).

Un en-tête alternatif peut être spécifié dans l'argument header. Lorsque l'en-tête Content-Type est défini, un en-tête MIME-Version est également ajouté.

Il s'agit d'une ancienne méthode. Dans la classe EmailMessage sa fonctionnalité est remplacée par les méthodes make_ et add_.

get_filename(failobj=None)

Renvoie la valeur du paramètre filename de l'en-tête Content-Disposition du message. Si l'en-tête n'a pas de paramètre filename, cette méthode revient à rechercher le paramètre name dans l'en-tête Content-Type. Si aucun n'est trouvé, ou si l'en-tête est manquant, alors failobj est renvoyé. La chaîne renvoyée est toujours sans guillemets comme indiqué par email.utils.unquote().

get_boundary(failobj=None)

Renvoie la valeur du paramètre boundary de l'en-tête Content-Type du message, ou failobj si l'en-tête est manquant ou n'a pas de paramètre boundary. La chaîne renvoyée est toujours sans guillemets comme indiqué par email.utils.unquote().

set_boundary(boundary)

Définit le paramètre boundary de l'en-tête Content-Type sur boundary. set_boundary() met toujours boundary entre guillemets si nécessaire. Une HeaderParseError est levée si l'objet message n'a pas d'en-tête Content-Type.

Notez que l'utilisation de cette méthode est légèrement différente de la suppression de l'ancien en-tête Content-Type et de l'ajout d'un nouveau avec la nouvelle limite via add_header(), car set_boundary() préserve l'ordre des en-têtes Content-Type dans la liste des en-têtes. Cependant, elle ne conserve pas les lignes de continuation qui auraient pu être présentes dans l'en-tête original Content-Type.

get_content_charset(failobj=None)

Renvoie le paramètre charset de l'en-tête Content-Type, mis en minuscules. S'il n'y a pas d'en-tête Content-Type, ou si cet en-tête n'a pas de paramètre charset, failobj est renvoyé.

Notez que cette méthode diffère de get_charset() qui renvoie l'instance Charset avec l'encodage par défaut du corps du message.

get_charsets(failobj=None)

Renvoie une liste contenant les noms des jeux de caractères dans le message. Si le message est un multipart, alors la liste contient un élément pour chaque sous-partie dans la charge utile, sinon, c'est une liste de longueur 1.

Chaque élément de la liste est une chaîne qui est la valeur du paramètre charset dans l'en-tête Content-Type pour la sous-partie représentée. Cependant, si la sous-partie n'a pas d'en-tête Content-Type, pas de paramètre charset, ou n'est pas du type MIME principal text, alors cet élément dans la liste renvoyée est failobj.

get_content_disposition()

Renvoie la valeur en minuscules (sans paramètres) de l'en-tête Content-Disposition du message s'il en a un, ou None. Les valeurs possibles pour cette méthode sont inline, attachment ou None si le message suit la RFC 2183.

Nouveau dans la version 3.5.

walk()

La méthode walk() est un générateur polyvalent qui peut être utilisé pour itérer sur toutes les parties et sous-parties d'une arborescence d'objets de message, dans l'ordre de parcours en profondeur d'abord. Vous utiliserez généralement walk() comme itérateur dans une boucle for ; chaque itération renvoie la sous-partie suivante.

Voici un exemple qui imprime le type MIME de chaque partie d'une structure de message en plusieurs parties :

>>> for part in msg.walk():
...     print(part.get_content_type())
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
text/plain

walk itère sur les sous-parties de toute partie où is_multipart() renvoie True, même si msg.get_content_maintype() == 'multipart' peut renvoyer False. Nous pouvons le voir dans notre exemple en utilisant la fonction d'aide au débogage _structure :

>>> for part in msg.walk():
...     print(part.get_content_maintype() == 'multipart',
...           part.is_multipart())
True True
False False
False True
False False
False False
False True
False False
>>> _structure(msg)
multipart/report
    text/plain
    message/delivery-status
        text/plain
        text/plain
    message/rfc822
        text/plain

Ici, les parties message ne sont pas des multiparts, mais elles contiennent des sous-parties. is_multipart() renvoie True et walk descend dans les sous-parties.

Les objets Message peuvent aussi éventuellement contenir deux attributs d'instance, qui peuvent être utilisés lors de la génération du texte brut d'un message MIME.

preamble

Le format d'un document MIME permet d'insérer du texte entre la ligne vide suivant les en-têtes et la première chaîne de délimitation en plusieurs parties. Normalement, ce texte n'est jamais visible dans un lecteur de courrier compatible MIME car il ne fait pas partie du cadre MIME standard. Toutefois, lors de l'affichage du texte brut du message ou lors de l'affichage du message dans un lecteur non compatible MIME, ce texte peut devenir visible.

L'attribut preamble contient ce texte hors-cadre de tête pour les documents MIME. Lorsque Parser découvre du texte après les en-têtes mais avant la première chaîne de délimitation, il attribue ce texte à l'attribut preamble du message. Lorsque Generator écrit la représentation en texte brut d'un message MIME, et qu'il trouve que le message a un attribut preamble, il écrit ce texte dans la zone entre les en-têtes et la première frontière. Voir email.parser et email.generator pour plus de détails.

Notez que si l'objet message n'a pas de préambule, l'attribut preamble est None.

epilogue

L'attribut epilogue agit de la même manière que l'attribut preamble, sauf qu'il contient du texte qui apparaît entre la dernière limite et la fin du message.

Vous n'avez pas besoin de définir l'épilogue sur la chaîne vide pour que Generator imprime une nouvelle ligne à la fin du fichier.

defects

L'attribut defects contient une liste de tous les problèmes rencontrés lors de l'analyse de ce message. Voir email.errors pour une description détaillée des défauts d'analyse possibles.