"email.header": Internationalized headers
*****************************************

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

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

Ce module fait partie de l'ancienne API de messagerie ("Compat32").
Dans l'API actuelle, l'encodage et le décodage des en-têtes sont gérés
de manière transparente par l'API de type dictionnaire de la classe
"EmailMessage". En plus des utilisations dans de l'ancien code, ce
module peut être utile dans les applications qui doivent contrôler
complètement les jeux de caractères utilisés lors de l'encodage des
en-têtes.

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

La **RFC 2822** est la norme de base qui décrit le format des messages
électroniques. Elle dérive de l'ancienne norme **RFC 822** qui s'est
généralisée à une époque où la plupart des e-mails étaient composés
uniquement de caractères ASCII. La **RFC 2822** est une spécification
écrite en supposant que le courrier électronique ne contient que des
caractères ASCII 7 bits.

Bien sûr, à mesure que le courrier électronique a été déployé dans le
monde, il s'est internationalisé, de sorte que des jeux de caractères
spécifiques à une langue peuvent désormais être utilisés dans les
messages électroniques. La norme de base exige toujours que les
messages électroniques soient transférés en utilisant uniquement des
caractères ASCII 7 bits, de sorte qu'un grand nombre de RFC décrivent
comment encoder les e-mails contenant des caractères non ASCII dans le
format conforme à la **RFC 2822**. Ces RFC incluent la **RFC 2045**,
la **RFC 2046**, la **RFC 2047** et la **RFC 2231**. Le paquet "email"
gère ces normes dans ses modules "email.header" et "email.charset".

Si vous souhaitez inclure des caractères non-ASCII dans les en-têtes
de vos e-mails, par exemple dans les champs *Subject* ou *To*, vous
devez utiliser la classe "Header" et affecter le champ dans le
"Message" à une instance de "Header" au lieu d'utiliser une chaîne
pour la valeur de l'en-tête. Importez la classe "Header" du module
"email.header". Par exemple :

   >>> from email.message import Message
   >>> from email.header import Header
   >>> msg = Message()
   >>> h = Header('p\xf6stal', 'iso-8859-1')
   >>> msg['Subject'] = h
   >>> msg.as_string()
   'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'

Remarquez ici comment nous voulions que le champ *Subject* contienne
un caractère non-ASCII : nous avons créé une instance "Header" et
transmis le jeu de caractères dans lequel la chaîne d'octets était
encodée. Lorsque l'instance suivante "Message" a été aplatie, le champ
*Subject* était correctement encodé selon la **RFC 2047**. Les
lecteurs de courrier compatibles MIME afficheraient cet en-tête en
utilisant le caractère ISO-8859-1 intégré.

Voici la description de la classe "Header" :

class email.header.Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')

   Crée un en-tête compatible MIME pouvant contenir des chaînes dans
   différents jeux de caractères.

   *s* (facultatif) est la valeur d'en-tête initiale. S'il vaut "None"
   (valeur par défaut), la valeur d'en-tête initiale n'est pas
   définie. Vous pouvez ensuite ajouter des choses à l'en-tête avec
   des appels de méthode "append()". *s* peut être une instance de
   "bytes" ou "str", mais consultez la documentation "append()" pour
   la sémantique.

   L'option *charset* sert à deux fins : elle a la même signification
   que l'argument *charset* de la méthode "append()". Elle définit
   également le jeu de caractères par défaut pour tous les appels
   suivants "append()" qui omettent l'argument *charset*. Si *charset*
   n'est pas fourni dans le constructeur (par défaut), le jeu de
   caractères "us-ascii" est utilisé à la fois comme jeu de caractères
   initial de *s* et comme jeu par défaut pour les appels suivants à
   "append()".

   The maximum line length can be specified explicitly via
   *maxlinelen*.  For splitting the first line to a shorter value (to
   account for the field header which isn't included in *s*, e.g.
   *Subject*) pass in the name of the field in *header_name*.  The
   default *maxlinelen* is 78, and the default value for *header_name*
   is "None", meaning it is not taken into account for the first line
   of a long, split header.

   *continuation_ws* (facultatif) doit être conforme aux caractères de
   reformatage **RFC 2822** ; c'est généralement soit une espace, soit
   un caractère de tabulation fixe. Ce caractère est ajouté aux lignes
   de continuation. *continuation_ws* utilise par défaut une seule
   espace.

   *errors* (facultatif) est transmis directement à la méthode
   "append()".

   append(s, charset=None, errors='strict')

      Ajoute la chaîne *s* à l'en-tête MIME.

      Le *charset* facultatif, s'il est fourni, doit être une instance
      de "Charset" (voir "email.charset") ou le nom d'un jeu de
      caractères, qui est converti en une instance "Charset". Une
      valeur "None" (la valeur par défaut) signifie que le *charset*
      donné dans le constructeur est utilisé.

      *s* peut être une instance de "bytes" ou "str". S'il s'agit
      d'une instance de "bytes", alors *charset* est l'encodage de
      cette chaîne d'octets et une "UnicodeError" est levée si la
      chaîne ne peut pas être décodée avec ce jeu de caractères.

      Si *s* est une instance de "str", alors *charset* est une
      indication spécifiant le jeu de caractères des caractères de la
      chaîne.

      Dans les deux cas, lors de la production d'un en-tête conforme à
      la **RFC 2822** à l'aide des règles **RFC 2047**, la chaîne est
      encodée à l'aide du codec de sortie du jeu de caractères. Si la
      chaîne ne peut pas être encodée à l'aide du codec de sortie, une
      erreur *UnicodeError* est levée.

      L'option *errors* est transmise comme argument d'erreurs à
      l'appel de décodage si *s* est une chaîne d'octets.

   encode(splitchars=';, \t', maxlinelen=None, linesep='\n')

      Encode un en-tête de message dans un format conforme à la RFC,
      en reformatant éventuellement de longues lignes et en
      encapsulant des parties non ASCII dans des encodages base64 ou
      dits *quoted-printable* (c.-à-d. que, par exemple, les
      caractères non ASCII sont représentés par un signe égal, suivi
      de son numéro, exprimé en hexadécimal).

      *splitchars* (facultatif) est une chaîne contenant des
      caractères auxquels l'algorithme de fractionnement doit donner
      un poids supplémentaire lors du reformatage normal de l'en-tête.
      Il s'agit d'une prise en charge très approximative des «
      ruptures syntaxiques de niveau supérieur » de la **RFC 2822** :
      les points de séparation précédés d'un caractère de séparation
      sont préférés lors de la séparation des lignes, les caractères
      étant préférés dans l'ordre dans lequel ils apparaissent dans la
      chaîne. Une espace et une tabulation peuvent être incluses dans
      la chaîne pour indiquer si la préférence doit être donnée à
      l'une plutôt qu'à l'autre comme point de partage lorsque
      d'autres caractères fractionnés n'apparaissent pas dans la ligne
      fractionnée. *splitchars* n'affecte pas les lignes encodées
      selon la **RFC 2047**.

      *maxlinelen*, s'il est fourni, remplace la valeur de l'instance
      pour la longueur de ligne maximale.

      *linesep* spécifie les caractères utilisés pour séparer les
      lignes de l'en-tête plié. Il prend par défaut la valeur la plus
      utile pour le code d'application Python ("\n"), mais "\r\n" peut
      être spécifié afin de produire des en-têtes avec des séparateurs
      de ligne conformes à la RFC.

      Modifié dans la version 3.2: ajout de l'argument *linesep*.

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

   __str__()

      Renvoie une approximation de "Header" sous forme de chaîne, en
      utilisant une longueur de ligne illimitée. Toutes les parties
      sont converties en Unicode en utilisant l'encodage spécifié et
      réunies de manière appropriée. Tous les morceaux avec un
      *charset* à "'unknown-8bit'" sont décodés en ASCII en utilisant
      le gestionnaire d'erreurs "'replace'".

      Modifié dans la version 3.2: ajout de la gestion du jeu de
      caractères "'unknown-8bit'".

   __eq__(other)

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

   __ne__(other)

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

Le module "email.header" fournit également les fonctions pratiques
suivantes.

email.header.decode_header(header)

   Décode une valeur d'en-tête de message sans convertir le jeu de
   caractères. La valeur de l'en-tête est dans *header*.

   For historical reasons, this function may return either:

   1. A list of pairs containing each of the decoded parts of the
      header, "(decoded_bytes, charset)", where *decoded_bytes* is
      always an instance of "bytes", and *charset* is either:

         * A lower case string containing the name of the character
           set specified.

         * "None" for non-encoded parts of the header.

   2. A list of length 1 containing a pair "(string, None)", where
      *string* is always an instance of "str".

   An "email.errors.HeaderParseError" may be raised when certain
   decoding errors occur (e.g. a base64 decoding exception).

   Here are examples:

   >>> from email.header import decode_header
   >>> decode_header('=?iso-8859-1?q?p=F6stal?=')
   [(b'p\xf6stal', 'iso-8859-1')]
   >>> decode_header('unencoded_string')
   [('unencoded_string', None)]
   >>> decode_header('bar =?utf-8?B?ZsOzbw==?=')
   [(b'bar ', None), (b'f\xc3\xb3o', 'utf-8')]

   Note:

     This function exists for backwards compatibility only. For new
     code, we recommend using "email.headerregistry.HeaderRegistry".

email.header.make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')

   Crée une instance "Header" à partir d'une séquence de paires
   renvoyées par "decode_header()".

   "decode_header()" prend une chaîne de valeur d'en-tête et renvoie
   une séquence de paires au format "(decoded_string, charset)" où
   *charset* est le nom du jeu de caractères.

   Cette fonction prend l'une de ces séquences de paires et renvoie
   une instance "Header". *maxlinelen*, *header_name* et
   *continuation_ws* (facultatifs) s'utilisent comme dans le
   constructeur "Header".

   Note:

     This function exists for backwards compatibility only, and is not
     recommended for use in new code.
