email.charset
: Representing character sets¶
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 vauteuc-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èreseuc-jp
vers le jeu de caractèresiso-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 eniso-8859-1
). Par défaut,us-ascii
7 bits.
- header_encoding¶
If the character set must be encoded before it can be used in an email header, this attribute will be set to
charset.QP
(for quoted-printable),charset.BASE64
(for base64 encoding), orcharset.SHORTEST
for the shortest of QP or BASE64 encoding. Otherwise, it will beNone
.
- body_encoding¶
Same as header_encoding, but describes the encoding for the mail message's body, which indeed may be different than the header encoding.
charset.SHORTEST
is not allowed for 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
oubase64
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 estQP
, renvoie la chaînebase64
si body_encoding estBASE64
et renvoie la chaîne7bit
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__()
.
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.
Optional header_enc and body_enc is either
charset.QP
for quoted-printable,charset.BASE64
for base64 encoding,charset.SHORTEST
for the shortest of quoted-printable or base64 encoding, orNone
for no encoding.SHORTEST
is only valid for header_enc. The default isNone
for no encoding.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 modulecodecs
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()
destr
).