email.charset: 表示字符集

源代码： Lib/email/charset.py

---

此模块是旧式 (Compat32) email API 的一部分。在新的 API 中，仅使用别名表。

本节的其余文本是该模块的原始文档。

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

从 email.charset 模块导入此类。

class email.charset.Charset(input_charset=DEFAULT_CHARSET)

将字符集映射到它们的电子邮件属性。

此类提供了关于特定字符集在电子邮件中强制要求的相关信息。在适用的编解码器可用的情况下，它还提供了在字符集之间进行转换的便捷例程。给定一个字符集，它将尽力提供如何在电子邮件中以符合 RFC 规范的方式使用该字符集的信息。

某些字符集在用于电子邮件标头或正文时，必须使用 quoted-printable 或 base64 进行编码。某些字符集必须被彻底转换，不允许在电子邮件中使用。

可选的 input_charset 如下所述；它总是被强制转换为小写。经过别名规范化后，它还被用作字符集注册表的查找键，以找出该字符集应使用的标头编码、正文编码和输出转换编解码器。例如，如果 input_charset 是 iso-8859-1，那么标头和正文将使用 quoted-printable 进行编码，并且不需要输出转换编解码器。如果 input_charset 是 euc-jp，那么标头将使用 base64 编码，正文不会被编码，但输出文本将从 euc-jp 字符集转换为 iso-2022-jp 字符集。

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

input_charset

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

header_encoding

如果字符集在用于电子邮件标头之前必须进行编码，此属性将被设置为 charset.QP (表示 quoted-printable)、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 标头设置为适当的值。

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

get_output_charset()

返回输出字符集。

如果 output_charset 属性不为 None，则返回该属性，否则返回 input_charset。

header_encode(string)

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

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

header_encode_lines(string, maxlengths)

通过先将 string 转换为字节串，再对其进行标头编码。

这类似于 header_encode()，不同之处在于字符串会被适配到由参数 maxlengths 提供的最大行长中，该参数必须是一个迭代器：此迭代器返回的每个元素将提供下一个最大行长。

body_encode(string)

对字符串 string 进行正文编码。

编码类型 (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=None, body_enc=None, output_charset=None)

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

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

可选的 header_enc 和 body_enc 可以是 charset.QP (表示 quoted-printable)，charset.BASE64 (表示 base64 编码)，charset.SHORTEST (表示 quoted-printable 或 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)

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

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

email.charset.add_codec(charset, codecname)

添加一个编解码器，用于将给定字符集中的字符映射到 Unicode 或从 Unicode 映射回来。

charset 是字符集的规范名称。codecname 是 Python 编解码器的名称，适用于作为 str 的 encode() 方法的第二个参数。