19.1.12. email.charset: 表示字符集

    此模块是旧版 () email API 的组成部分。 在新版 API 中只会使用其中的别名表。

    本段落中的剩余文本是该模块的原始文档。

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

    请从 email.charset 模块导入这个类。

    class email.charset.Charset(input_charset=DEFAULT_CHARSET)

    将字符集映射到其 email 特征属性。

    这个类提供了特定字符集对于电子邮件的要求的相关信息。 考虑到适用编解码器的可用性，它还为字符集之间的转换提供了一些便捷例程。 在给定字符集的情况下，它将尽可能地以符合 RFC 的方式在电子邮件消息中提供有关如何使用该字符集的信息。

    特定字符集当在电子邮件标头或消息体中使用时必须以 quoted-printable 或 base64 来编码。 某些字符集则必须被立即转换，不允许在电子邮件中使用。

    可选的 input_charset 说明如下；它总是会被强制转为小写。 在进行别名正规化后它还会被用来查询字符集注册表以找出用于该字符集的标头编码格式、消息体编码格式和输出转换编解码器。 举例来说，如果 input_charset 为 iso-8859-1，则标头和消息体将会使用 quoted-printable 来编码并且不需要输出转换编解码器。 如果 input_charset 为 euc-jp，则标头将使用 base64 来编码，消息体将不会被编码，但输出文本将从 euc-jp 字符集转换为 iso-2022-jp 字符集。

    实例具有下列数据属性:

    • 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。

    • 某些字符集在用于电子邮件标头或消息体之前必须被转换。 如果 input_charset 是这些字符集之一，该属性将包含输出将要转换的字符集名称。 在其他情况下，该属性将为 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 则返回该属性，否则返回 input_charset。

    • header_encode(string)

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

      编码格式的类型 (base64 或 quoted-printable) 将取决于 header_encoding 属性。

    • (string)

      对字符串 string 执行消息体编码。

      编码格式的类型 (base64 或 quoted-printable) 将取决于 body_encoding 属性。

    • __str__()

      将 input_charset 以强制转为小写的字符串形式返回。 是 __str__() 的别名。

    • __eq__(other)

      这个方法允许你对两个 实例进行相等比较。

    • __ne__(other)

      这个方法允许你对两个 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() 方法被调用时将会执行从输入字符集到输出字符集的转换。 默认情况下输出字符集将与输入字符集相同。

    input_charset 和 output_charset 都必须在模块的字符集-编解码器映射中具有 Unicode 编解码器条目；使用 add_codec() 可添加本模块还不知道的编解码器。 请参阅 模块的文档来了解更多信息。

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

    email.charset.add_alias(alias, canonical)

    添加一个字符集别名。 alias 为特定的别名，例如 latin-1。 canonical 是字符集的正规名称，例如 iso-8859-1。

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

    (charset, codecname)

    添加在给定字符集的字符和 Unicode 之间建立映射的编解码器。