email.charset: Representing character sets

该模块提供了一个Charset用于表示电子邮件中的字符集和字符集转换的类，以及用于操作此注册表的字符集注册表和一些便利方法。实例Charset在email包中的其他几个模块中使用。

从email.charset模块中导入此类。

2.2.2版中的新功能。

class email.charset.Charset([input_charset])

将字符集映射到其电子邮件属性。

该课程提供有关特定字符集对电子邮件的要求的信息。考虑到可用的编解码器的可用性，它还提供了在字符集之间转换的便利例程。鉴于字符集，它将尽最大努力提供有关如何以符合RFC的方式在电子邮件中使用该字符集的信息。

在电子邮件标题或正文中使用时，某些字符集必须用quoted-printable或base64编码。某些字符集必须完全转换，并且不允许在电子邮件中使用。

可选的input_charset如下所述; 它总是被强制为小写。在被别名标准化之后，它也被用作查找字符集的注册表以找出用于字符集的标题编码，主体编码和输出转换编解码器。例如，如果input_charset是iso-8859-1，则标题和正文将使用quoted-printable进行编码，并且不需要输出转换编解码器。如果input_charset是euc-jp，那么标题将用base64进行编码，不会对body进行编码，但输出文本将从euc-jp字符集转换为iso-2022-jp字符集。

Charset 实例具有以下数据属性：

input_charset

指定的初始字符集。常用的别名被转换为他们的官方电子邮件名称（例如latin_1转换为iso-8859-1）。默认为7位us-ascii。

header_encoding

如果字符集必须在电子邮件头中使用之前进行编码，则此属性将设置为Charset.QP（对于引用可打印）Charset.BASE64（对于base64编码），或Charset.SHORTEST对于最短的QP或BASE64编码。否则，它会None。

body_encoding

与header_encoding相同，但描述了邮件消息正文的编码，确实可能与标题编码不同。Charset.SHORTEST不允许body_encoding。

output_charset

一些字符集必须先转换后才能用于电子邮件标题或正文。如果input_charset是其中的一个，则此属性将包含将要转换为的字符集输出的名称。否则，它会None。

input_codec

用于将input_charset转换为Unicode 的Python编解码器的名称。如果不需要转换编解码器，则此属性为None。

output_codec

用于将Unicode转换为output_charset的Python编解码器的名称。如果不需要转换编解码器，则该属性将具有与input_codec相同的值。

Charset 实例还有以下方法：

get_body_encoding()

返回用于正文编码的内容传输编码。

这要么是字符串，quoted-printable要么base64取决于所使用的编码，或者它是一个函数，在这种情况下，您应该使用一个参数调用函数，Message对象将被编码。然后该函数应该将Content-Transfer-Encoding头本身设置为适当的。

返回字符串quoted-printable，如果body_encoding是QP，返回字符串base64如果body_encoding是BASE64，并返回字符串7bit，否则。

convert(s)

将字符串s从input_codec转换为output_codec。

to_splittable(s)

将可能的多字节字符串转换为安全可拆分的格式。s是要拆分的字符串。

使用input_codec尝试将字符串转换为Unicode，因此可以安全地在字符边界上进行拆分（即使对于多字节字符）。

如果不知道如何使用input_charset将s转换为Unicode，则按原样返回字符串。

无法转换为Unicode的字符将被替换为Unicode替换字符'U+FFFD'。

from_splittable(ustr[, to_output])

将可拆分字符串转换回编码字符串。ustr是一个Unicode字符串，用于“ unsplit ”。

此方法使用正确的编解码器尝试将Unicode字符串转换为编码格式。如果它不是Unicode，或者它不能从Unicode转换，则按原样返回字符串。

无法从Unicode转换的字符将被替换为适当的字符（通常'?'）。

如果to_output是True（默认），则使用output_codec转换为编码格式。如果to_output是False，它使用input_codec。

get_output_charset()

返回输出字符集。

这是output_charset属性（如果不是）None，否则它是input_charset。

encoded_header_len()

返回已编码标题字符串的长度，正确计算quoted-printable或base64编码。

header_encode(s[, convert])

对字符串s进行标头编码。

如果convert是True，则字符串将自动从输入字符集转换为输出字符集。这对多字节字符集没有用处，多行字符集具有行长度问题（多字节字符必须在字符上分割，而不是字节边界）; 使用更高级别的Header类来处理这些问题（请参阅参考资料email.header）。将默认值转换为False。

编码类型（base64或quoted-printable）将基于header_encoding属性。

body_encode(s[, convert])

对字符串s进行身体编码。

如果convert为True（默认），则字符串将从输入字符集转换为自动输出字符集。header_encode()与之不同的是，电子邮件正文中没有字节边界和多字节字符集的问题，所以这通常很安全。

编码类型（base64或quoted-printable）将基于body_encoding属性。

本Charset类还提供了一些方法来支持标准操作和内置功能。

__str__()

将input_charset作为强制转换为小写字符串的形式返回。__repr__()是一个别名__str__()。

__eq__(other)

该方法允许您比较两个Charset实例是否相等。

__ne__(other)

该方法允许您比较两个Charset不平等的实例。

该email.charset模块还提供了以下功能，用于向全局字符集，别名和编解码器注册表中添加新条目：

email.charset.add_charset(charset[, header_enc[, body_enc[, output_charset]]])

将字符属性添加到全局注册表。

字符集是输入字符集，并且必须是字符集的规范名称。

可选header_enc和body_enc或者是Charset.QP带引号的可打印，Charset.BASE64为base64编码，Charset.SHORTEST争取在最短的引用可打印或base64编码的，或者None因为没有编码。SHORTEST仅对header_enc有效。默认值是None无编码。

可选的output_charset是输出应该在其中的字符集。当Charset.convert()调用方法时，转换将从输入字符集继续到Unicode，再到输出字符集。默认是以与输入相同的字符集输出。

无论input_charset和output_charset必须在模块的字符的Unicode编码解码器条目设置到编解码器的映射; 用于add_codec()添加模块不知道的编解码器。有关codecs更多信息，请参阅模块的文档。

全局字符集注册表保存在模块全局字典中CHARSETS。

email.charset.add_alias(alias, canonical)

添加一个字符集别名。别名是别名，例如latin-1。canonical是字符集的规范名称，例如iso-8859-1。

全局字符集别名注册表保存在模块全局字典中ALIASES。

email.charset.add_codec(charset, codecname)

添加一个将给定字符集中的字符映射到Unicode的编解码器。

字符集是字符集的规范名称。codecname是Python编解码器的名称，适用于unicode()内置的第二个参数或encode()Unicode字符串的方法。