# `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`).