"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.

The email package does its best to hide the details of the various
governing RFCs from the application.  Conceptually the application
should be able to treat the email message as a structured tree of
Unicode text and binary attachments, without having to worry about how
these are represented when serialized.  In practice, however, it is
often necessary to be aware of at least some of the rules governing
MIME messages and their structure, specifically the names and nature
of the MIME "content types" and how they identify multipart documents.
For the most part this knowledge should only be required for more
complex applications, and even then it should only be the high level
structure in question, and not the details of how those structures are
represented.  Since MIME content types are used widely in modern
internet software (not just email), this will be a familiar concept to
many programmers.

The following sections describe the functionality of the "email"
package. We start with the "message" object model, which is the
primary interface an application will use, and follow that with the
"parser" and "generator" components.  Then we cover the "policy"
controls, which completes the treatment of the main components of the
library.

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.

The foregoing represent the modern (Unicode friendly) API of the email
package. The remaining sections, starting with the "Message" class,
cover the legacy "compat32" API that deals much more directly with the
details of how email messages are represented.  The "compat32" API
does *not* hide the details of the RFCs from the application, but for
applications that need to operate at that level, they can be useful
tools.  This documentation is also relevant for applications that are
still using the "compat32" API for backward compatibility reasons.

Modifié dans la version 3.6: Documents réorganisés et réécrits pour
promouvoir la nouvelle API "EmailMessage"/"EmailPolicy".

Contents of the "email" package documentation:

* "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 "mailbox"
     Outils pour créer, lire et gérer des messages regroupés sur
     disque en utilisant des formats standards variés.
