email
--- An email and MIME handling package¶
Code source: Lib/email/__init__.py
The email
package is a library for managing email messages. It is
specifically not designed to do any sending of email messages to SMTP
(RFC 2821), NNTP, or other servers; those are functions of modules such as
smtplib
. The email
package attempts to be as
RFC-compliant as possible, supporting RFC 5322 and RFC 6532, as well as
such MIME-related RFCs as RFC 2045, RFC 2046, RFC 2047, RFC 2183,
and RFC 2231.
Ce paquet peut être divisé entre trois composants majeurs, et un quatrième composant qui contrôle le comportement des trois autres.
Le composant central du paquet est un "modèle d'objet" qui représente les messages. Une application interagit avec le paquet, dans un premier temps, à travers l'interface de modèle d'objet définie dans le sous-module message
. L'application peut utiliser cette API pour poser des questions à propos d'un mail existant, pour créer un nouvel e-mail, ou ajouter ou retirer des sous-composants d'e-mail qui utilisent la même interface de modèle d'objet. Suivant la nature des messages et leurs sous-composants MIME, le modèle d'objet d'e-mail est une structure arborescente d'objets qui fournit tout à l'API de EmailMessage
.
Les deux autres composants majeurs de ce paquet sont l'analyseur (parser
) et le générateur (generator
). L'analyseur prend la version sérialisée d'un e-mail (un flux d'octets) et le convertit en une arborescence d'objets EmailMessage
. Le générateur prend un objet EmailMessage
et le retransforme en un flux d'octets sérialisé (l'analyseur et le générateur gèrent aussi des suites de caractères textuels, mais cette utilisation est déconseillée car il est très facile de finir avec des messages invalides d'une manière ou d'une autre).
Le composant de contrôle est le module policy
. Chaque EmailMessage
, chaque generator
et chaque parser
possède un objet associé policy
qui contrôle son comportement. Habituellement une application n'a besoin de spécifier la politique que quand un EmailMessage
est créé, soit en instanciant directement un EmailMessage
pour créer un nouvel e-mail, soit lors de l'analyse d'un flux entrant en utilisant un parser
. Mais la politique peut être changée quand le message est sérialisé en utilisant un generator
. Cela permet, par exemple, d'analyser un message e-mail générique du disque, puis de le sérialiser en utilisant une configuration SMTP standard quand on l'envoie vers un serveur d'e-mail.
Le paquet email fait son maximum pour cacher les détails des différentes RFCs de référence à l'application. Conceptuellement, l'application doit être capable de traiter l'e-mail comme une arborescence structurée de texte Unicode et de pièces jointes binaires, sans avoir à se préoccuper de leur représentation sérialisée. Dans la pratique, cependant, il est souvent nécessaire d'être conscient d'au moins quelques règles relatives aux messages MIME et à leur structure, en particulier les noms et natures des "types de contenus" et comment ils identifient les documents à plusieurs parties. Pour la plupart, cette connaissance devrait seulement être nécessaire pour des applications plus complexes, et même là, il devrait être question des structures de haut niveau et non des détails sur la manière dont elles sont représentées. Comme les types de contenus MIME sont couramment utilisés dans les logiciels internet modernes (et non uniquement les e-mails), les développeurs sont généralement familiers de ce concept.
La section suivante décrit les fonctionnalités du paquet email
. Nous commençons avec le modèle d'objet message
, qui est la principale interface qu'une application utilise, et continuons avec les composants parser
et generator
. Ensuite, nous couvrons les contrôles policy
, qui complètent le traitement des principaux composants de la bibliothèque.
Les trois prochaines sections couvrent les exceptions que le paquet peut rencontrer et les imperfections (non-respect des RFCs) que le module parser
peut détecter. Ensuite nous couvrons les sous-composants headerregistry
et contentmanager
, qui fournissent des outils pour faire des manipulations plus détaillées des en-têtes et du contenu, respectivement. Les deux composants contiennent des fonctionnalités adaptées pour traiter et produire des messages qui sortent de l'ordinaire, et elles documentent aussi leurs API pour pouvoir les étendre, ce qui ne manquera pas d'intéresser les applications avancées.
Ci-dessous se trouve un ensemble d'exemples d'utilisations des éléments fondamentaux des API couvertes dans les sections précédentes.
Ce que nous venons d'aborder constitue l'API moderne (compatible Unicode) du paquet email. Les sections restantes, commençant par la classe Message
, couvrent l'API héritée compat32
qui traite beaucoup plus directement des détails sur la manière dont les e-mails sont représentés. L'API compat32
ne cache pas les détails des RFCs à l'application, mais pour les applications qui requièrent d'opérer à ce niveau, elle peut être un outil pratique. Cette documentation est aussi pertinente pour les applications qui utilisent toujours l'API compat32
pour des raisons de rétrocompatibilité.
Modifié dans la version 3.6: Documents réorganisés et réécrits pour promouvoir la nouvelle API EmailMessage
/EmailPolicy
.
Contenus de la documentation du paquet email
:
email.message
: Representing an email messageemail.parser
: Parsing email messagesemail.generator
: Generating MIME documentsemail.policy
: Policy Objectsemail.errors
: Exception and Defect classesemail.headerregistry
: Custom Header Objectsemail.contentmanager
: Managing MIME Contentemail
: Exemples
API héritée :
email.message.Message
: représentation d'un message électronique à l'aide de l'APIcompat32
email.mime
: Creating email and MIME objects from scratchemail.header
: Internationalized headersemail.charset
: Representing character setsemail.encoders
: Encodersemail.utils
: Miscellaneous utilitiesemail.iterators
: Iterators
Voir aussi