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