"email.encoders" : Encodeurs
****************************

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

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

Ce module fait partie du code patrimonial ("Compat32") de l'API mail.
Dans la nouvelle API la fonctionnalité est fournie par le paramètre
*cte* de la méthode "set_content()".

Ce module est obsolète en Python 3. Il n'est pas de besoin d'appeler
explicitement les fonctions définies ici puisque la classe "MIMEText"
ajuste le type de contenu et l'entête CTE à l'aide des paramètres
*_subtype* et *_charset* de son constructeur.

Le texte restant de cette section est la documentation originale de ce
module.

Au moment de la création d'objets "Message" à la main, il est souvent
nécessaire d'encoder les charges utiles pour le transport à travers
des serveurs mail conformes. C'est particulièrement vrai pour les
messages de type *image/** et *text/** contenant des données binaires.

Le paquet "email" fournit quelques encodeurs pratiques dans son module
"encoders". Ces encodeurs sont d'ailleurs utilisés par les
constructeurs des classes "MIMEAudio" et "MIMEImage" afin de fournir
des encodages par défaut. Toutes les fonctions d'encodage prennent
exactement un argument, l'objet message à encoder. Généralement, elles
extraient la charge utile, l'encode, puis change la charge utile pour
la nouvelle valeur encodée. Elles devraient également assigner l'en-
tête  *Content-Transfer-Encoding* si besoin.

À noter que ces fonctions n'ont pas de sens dans le cadre d'un message
en plusieurs parties. Elles doivent à la place être appliquées aux
sous-parties individuelles, et lèvent "TypeError" si on leur passe un
message en plusieurs parties.

Voici les fonctions d'encodages fournies :

email.encoders.encode_quopri(msg)

   Encode la charge utile au format Quoted-Printable, et assigne
   "quoted-printable" [1] à l'en-tête *Content-Transfer-Encoding*.
   C'est un bon encodage à utiliser quand la majorité de la charge
   utile contient essentiellement des données imprimables, à
   l'exceptions de quelques caractères.

email.encoders.encode_base64(msg)

   Encode la charge utile au format *base64*, et assigne "base64" à l
   'en-tête *Content-Transfer-Encoding*. C'est un bon encodage à
   utiliser quand la majorité de la charge utile est non imprimable
   puisque c'est une forme plus compacte que *quoted-printable*.

email.encoders.encode_7or8bit(msg)

   Ceci ne modifie pas effectivement la charge utile du message, mais
   va bien en revanche assigner la valeur "7bit" ou "8bit" à l'en-tête
   *Content-Transfer-Encoding* selon la nature de la charge utile.

email.encoders.encode_noop(msg)

   Ceci ne fait rien; et ne va même pas changer la valeur de l'en-tête
   *Content-Transfer-Encoding*.

-[ Notes ]-

[1] À noter que l'encodage avec "encode_quopri()" encode également
    tous les caractères tabulation et espace.
