"email.charset" : représentation des jeux de caractères
*******************************************************

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

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

Ce module fait partie de l'ancienne API de messagerie ("Compat32").
Dans la nouvelle API, seule la table des alias est utilisée.

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

Ce module fournit une classe "Charset" pour représenter les jeux de
caractères et les conversions de jeux de caractères dans les messages
électroniques, ainsi qu'un registre de jeux de caractères et plusieurs
méthodes pratiques pour manipuler ce registre. Les instances de
"Charset" sont utilisées dans plusieurs autres modules du paquet
"email".

Importez cette classe depuis le module "email.charset".

class email.charset.Charset(input_charset=DEFAULT_CHARSET)

   Associe les jeux de caractères à leurs propriétés d'e-mail.

   Cette classe fournit des informations sur les exigences imposées
   aux e-mails pour un jeu de caractères spécifique. Elle fournit
   également des routines pratiques pour la conversion entre les jeux
   de caractères, compte tenu de la disponibilité des codecs
   applicables. Étant donné un jeu de caractères, elle fait de son
   mieux pour fournir des informations sur la façon d'utiliser ce jeu
   de caractères dans un message électronique d'une manière conforme à
   la RFC.

   Certains jeux de caractères doivent être encodés avec *quoted-
   printable* ou en *base64* lorsqu'ils sont utilisés dans les en-
   têtes ou les corps des e-mails. Certains jeux de caractères doivent
   être convertis directement et ne sont pas autorisés dans les
   e-mails.

   Le *input_charset* facultatif est tel que décrit ci-dessous ; il
   est toujours contraint en minuscules. Après avoir été normalisé par
   alias, il est également utilisé comme recherche dans le registre
   des jeux de caractères pour trouver le codage d'en-tête, le codage
   de corps et le codec de conversion de sortie à utiliser pour le jeu
   de caractères. Par exemple, si *input_charset* vaut "iso-8859-1",
   alors les en-têtes et les corps seront encodés en utilisant
   *quoted-printable* et aucun codec de conversion de sortie n'est
   nécessaire. Si *input_charset* vaut "euc-jp", alors les en-têtes
   seront encodés en *base64*, les corps ne seront pas encodés, mais
   le texte de sortie sera converti du jeu de caractères "euc-jp" vers
   le jeu de caractères "iso-2022-jp".

   Les instances de "Charset" ont les attributs de données suivants :

   input_charset

      Jeu de caractères initial spécifié. Les alias communs sont
      convertis en leurs noms de messagerie *officiels* (par exemple,
      "latin_1" est converti en "iso-8859-1"). Par défaut, "us-ascii"
      7 bits.

   header_encoding

      Si le jeu de caractères doit être encodé avant de pouvoir être
      utilisé dans un en-tête d'e-mail, cet attribut est défini sur
      "Charset.QP" (pour *quoted-printable*), "Charset.BASE64" (pour
      l'encodage en *base64*), ou "Charset.SHORTEST" pour le plus
      court des encodages QP ou BASE64. Sinon, c'est "None".

   body_encoding

      Identique à *header_encoding*, mais décrit l'encodage du corps
      du message électronique, qui peut effectivement être différent
      de l'encodage de l'en-tête. "Charset.SHORTEST" n'est pas
      autorisé pour *body_encoding*.

   output_charset

      Certains jeux de caractères doivent être convertis avant de
      pouvoir être utilisés dans les en-têtes ou le corps des e-mails.
      Si le *input_charset* est un jeu de ce type, alors cet attribut
      contient le nom du jeu de caractères vers lequel la sortie sera
      convertie. Sinon, il vaut "None".

   input_codec

      Nom du codec Python utilisé pour convertir le *input_charset* en
      Unicode. Si aucun codec de conversion n'est nécessaire, cet
      attribut vaut "None".

   output_codec

      Nom du codec Python utilisé pour convertir Unicode en
      *output_charset*. Si aucun codec de conversion n'est nécessaire,
      cet attribut a la même valeur que le *input_codec*.

   Les instances de "Charset" ont également les méthodes suivantes :

   get_body_encoding()

      Renvoie l'encodage de transfert de contenu utilisé pour
      l'encodage du corps.

      Il s'agit soit de la chaîne "quoted-printable" ou "base64" selon
      l'encodage utilisé, soit d'une fonction, vous devez alors
      appeler la fonction avec un seul argument, l'objet Message étant
      encodé. La fonction doit ensuite définir l'en-tête *Content-
      Transfer-Encoding* à la valeur appropriée.

      Renvoie la chaîne "quoted-printable" si *body_encoding* est
      "QP", renvoie la chaîne "base64" si *body_encoding* est "BASE64"
      et renvoie la chaîne "7bit" sinon.

   get_output_charset()

      Renvoie le jeu de caractères de sortie.

      C'est l'attribut *output_charset* si ce n'est pas "None", sinon
      c'est *input_charset*.

   header_encode(string)

      Encode la chaîne *string* pour un en-tête.

      Le type d'encodage (*base64* ou *quoted-printable*) est basé sur
      l'attribut *header_encoding*.

   header_encode_lines(string, maxlengths)

      Encode *string* en la convertissant d'abord en octets, pour un
      en-tête.

      C'est similaire à "header_encode()" sauf que la chaîne est
      adaptée aux longueurs de ligne maximales indiquées par
      l'argument *maxlengths*, qui doit être un itérateur : chaque
      élément renvoyé par cet itérateur fournit la prochaine longueur
      de ligne maximale.

   body_encode(string)

      Encode la chaîne *string* pour un usage en corps de message.

      Le type d'encodage (*base64* ou *quoted-printable*) est basé sur
      l'attribut *body_encoding*.

   La classe "Charset" fournit également un certain nombre de méthodes
   pour prendre en charge les opérations standard et les fonctions
   intégrées.

   __str__()

      Returns *input_charset* as a string coerced to lower case.
      "__repr__()" is an alias for "__str__()".

   __eq__(other)

      Cette méthode vous permet de tester l'égalité de deux instances
      de "Charset".

   __ne__(other)

      Cette méthode vous permet de tester l'inégalité de deux
      instances de "Charset".

Le module "email.charset" fournit également les fonctions suivantes
pour ajouter de nouvelles entrées à l'ensemble des jeux de caractères
globaux, aux registres d'alias et de codec :

email.charset.add_charset(charset, header_enc=None, body_enc=None, output_charset=None)

   Ajoute des propriétés relatives d'un jeu de caractères dans le
   registre global.

   *charset* est le jeu de caractères d'entrée et doit être le nom
   canonique d'un jeu de caractères.

   *header_enc* et *body_enc* (facultatifs) sont soit "Charset.QP"
   pour *quoted-printable*, "Charset.BASE64" pour l'encodage *base64*,
   "Charset.SHORTEST" pour le plus court entre *quoted-printable* et
   *base64*, ou "None" pour aucun encodage. "SHORTEST" n'est valide
   que pour *header_enc*. La valeur par défaut est "None" pour aucun
   encodage.

   *output_charset* (facultatif) est le jeu de caractères dans lequel
   doit être la sortie. Les conversions se poursuivent du jeu de
   caractères d'entrée, vers Unicode, vers le jeu de caractères de
   sortie lorsque la méthode "Charset.convert()" est appelée. La
   valeur par défaut est de sortir dans le même jeu de caractères que
   l'entrée.

   *input_charset* et *output_charset* doivent avoir des entrées de
   codec Unicode dans la table de correspondances du jeu de caractères
   au codec du module ; utilisez "add_codec()" pour ajouter des codecs
   que le module ne connaît pas. Voir la documentation du module
   "codecs" pour plus d'informations.

   Le registre de jeux de caractères global est conservé dans le
   dictionnaire global du module "CHARSETS".

email.charset.add_alias(alias, canonical)

   Ajoute un alias de jeu de caractères. *alias* est le nom d'alias,
   par ex. "latin-1". *canonical* est le nom canonique du jeu de
   caractères, par ex. "iso-8859-1".

   Le registre global des alias du jeu de caractères est conservé dans
   le dictionnaire global du module "ALIASES".

email.charset.add_codec(charset, codecname)

   Ajoute un codec qui fait correspondre les caractères du jeu de
   caractères donné vers et depuis Unicode.

   *charset* est le nom canonique d'un jeu de caractères. *codecname*
   est le nom d'un codec Python (c.-à-d. une valeur valable comme
   second argument de la méthode "encode()" de "str").
