"email" --- An email and MIME handling package
**********************************************

**Code source:** Lib/email/__init__.py

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

Le paquet "email" est une bibliothèque pour gérer les e-mails. Il est
spécifiquement conçu pour ne pas gérer les envois d'e-mails vers SMTP
(**RFC 2821**), NNTP, ou autres serveurs ; ces fonctions sont du
ressort des modules comme "smtplib" et "nntplib". Le paquet "email"
tente de respecter les RFC autant que possible, il gère **RFC 5322**
et **RFC 6532**, ainsi que les RFCs en rapport avec les MIME comme
**RFC 2045**, **RFC 2046**, **RFC 2047**, **RFC 2183**, et **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 message

* "email.parser": Parsing email messages

  * API *FeedParser*

  * API de *Parser*

  * Notes complémentaires

* "email.generator": Generating MIME documents

* "email.policy": Policy Objects

* "email.errors": Exception and Defect classes

* "email.headerregistry": Custom Header Objects

* "email.contentmanager": Managing MIME Content

  * Instances de gestionnaires de contenus

* "email": Exemples

API héritée :

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

* "email.mime": Creating email and MIME objects from scratch

* "email.header": Internationalized headers

* "email.charset": Representing character sets

* "email.encoders": Encoders

* "email.utils": Miscellaneous utilities

* "email.iterators": Iterators

Voir aussi:

  Module "smtplib"
     Client SMTP (*Simple Mail Transport Protocol*)

  Module "poplib"
     Client POP (*Post Office Protocol*)

  Module "imaplib"
     Client IMAP (*Internet Message Access Protocol*)

  Module "nntplib"
     Client NNTP (*Net News Transport Protocol*)

  Module "mailbox"
     Outils pour créer, lire et gérer des messages regroupés sur
     disque en utilisant des formats standards variés.
