Skip to main content

19.1.12. email.charset:表示字符集

源代码: Lib/email/charset.py


此模块是旧版(Compat32)电子邮件API的一部分。在新的API中,仅使用别名表。

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

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

email.charset 模块导入此类。

class email.charset.Charset(input_charset=DEFAULT_CHARSET)

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

此类提供有关特定字符集对电子邮件的要求的信息。它还提供了用于在字符集之间转换的方便例程,给定可用的编解码器的可用性。给定一个字符集,它将尽力提供有关如何以符合RFC的方式在电子邮件中使用该字符集的信息。

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

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

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

input_charset

指定的初始字符集。通用别名将转换为其 official 电子邮件名称(例如,latin_1 转换为 iso-8859-1)。默认为7位 us-ascii

header_encoding

如果字符集必须在可以在电子邮件头中使用之前进行编码,则此属性将设置为 Charset.QP (用于quoted-printable),Charset.BASE64 (用于base64编码)或 Charset.SHORTEST 用于QP或BASE64编码中最短的。否则,它将是 None

body_encoding

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

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-printablebase64,或者它是一个函数,在这种情况下,您应该使用单个参数调用该函数,Message对象正在被编码。然后函数应该将 Content-Transfer-Encoding 头本身设置为适当的。

如果 body_encodingQP,则返回字符串 quoted-printable,如果 body_encodingBASE64,则返回字符串 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 转换为字节来对 string 进行头编码。

这与 header_encode() 类似,除了字符串适合由参数 maxlengths 给出的最大行长度,参数 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_encbody_encCharset.QP 用于引用打印,Charset.BASE64 用于base64编码,Charset.SHORTEST 用于最短的引用打印或base64编码,或 None 用于无编码。 SHORTEST 仅对 header_enc 有效。默认值为 None,表示无编码。

可选 output_charset 是输出应该在的字符集。当调用方法 Charset.convert() 时,转换将从输入字符集,Unicode转换为输出字符集。默认值是以与输入相同的字符集输出。

input_charsetoutput_charset 都必须在模块的字符集到编解码器映射中具有Unicode编解码器条目;使用 add_codec() 添加模块不知道的编解码器。有关详细信息,请参阅 codecs 模块的文档。

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

email.charset.add_alias(alias, canonical)

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

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

email.charset.add_codec(charset, codecname)

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

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