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_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 位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
,具体取决于使用的编码,或者它是一个函数,在这种情况下,您应该使用单个参数(正在编码的消息对象)调用该函数。然后,该函数应将 Content-Transfer-Encoding 标题本身设置为任何适当的值。如果 body_encoding 是
QP
,则返回字符串quoted-printable
,如果 body_encoding 是BASE64
,则返回字符串base64
,否则返回字符串7bit
。
- get_output_charset()¶
返回输出字符集。
如果 output_charset 属性不为
None
,则为 output_charset 属性,否则为 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__()
的别名。
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
中。