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

Of course, as email has been deployed worldwide, it has become
internationalized, such that language specific character sets can now
be used in email messages.  The base standard still requires email
messages to be transferred using only 7-bit ASCII characters, so a
slew of RFCs have been written describing how to encode email
containing non-ASCII characters into **RFC 2822**-compliant format.
These RFCs include **RFC 2045**, **RFC 2046**, **RFC 2047**, and **RFC
2231**. The "email" package supports these standards in its
"email.header" and "email.charset" modules.

If you want to include non-ASCII characters in your email headers, say
in the *Subject* or *To* fields, you should use the "Header" class and
assign the field in the "Message" object to an instance of "Header"
instead of using a string for the header value.  Import the "Header"
class from the "email.header" module. For example:

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

The "email.header" module also provides the following convenient
functions.

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.
