18.1.6. email.charset：表示字符集

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

从email.charset模块导入此类。

版本 2.2.2 中的新Function。

• • class * email.charset. Charset([* input_charset *])
  • 将字符集 Map 到其电子邮件属性。

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

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

可选的* input_charset 如下所述；它总是被强制为小写。别名标准化后，它还用作对字符集注册表的查找，以查找要用于字符集的 Headers 编码，主体编码和输出转换编解码器。例如，如果 input_charset 为iso-8859-1，则标题和正文将使用 quoted-printable 进行编码，并且不需要输出转换编解码器。如果 input_charset *为euc-jp，则 Headers 将使用 base64 进行编码，不对正文进行编码，但是输出文本将从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 *相同，但描述了邮件正文的编码，实际上可能与 Headers 编码不同。 * 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-printable或base64，也可以是函数，在这种情况下，应使用单个参数(已编码的 Message 对象)调用该函数。然后，该函数应将* Content-Transfer-Encoding *Headers 本身设置为适当的值。

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

• convert(* s *)

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

• to_splittable(* s *)

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

使用* input_codec *try将字符串转换为 Unicode，因此可以在字符边界上安全分割(即使对于多字节字符也是如此)。

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

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

• from_splittable(* ustr * [，* to_output *])
  • 将可拆分字符串转换回编码字符串。 * ustr *是“未拆分”的 Unicode 字符串。

此方法使用适当的编解码器try将字符串从 Unicode 转换回编码格式。如果不是 Unicode，或者无法从 Unicode 转换，则原样返回字符串。

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

如果* to_output 为True(默认值)，则使用 output_codec 转换为编码格式。如果 to_output 为False，则使用 input_codec *。

• get_output_charset ( )
  • 返回输出字符集。

如果不是None，则为* output_charset 属性；否则为 input_charset *。

• encoded_header_len ( )

  • 返回编码的 Headers 字符串的长度，正确计算为 quoted-printable 或 base64 编码。

• header_encode(* s * [，* convert *])

  • Headers 编码字符串* s *。

如果* convert *为True，则字符串将自动从 Importing 字符集转换为输出字符集。这对于行长度有问题的多字节字符集没有用(多字节字符必须在一个字符上分割，而不是在字节边界上分割)。使用更高级别的Header类来处理这些问题(请参见email.header)。 * convert *默认为False。

编码类型(base64 或带引号的可打印格式)将基于* header_encoding *属性。

• body_encode(* s * [，* convert *])
  • 对字符串* s *进行身体编码。

如果* convert *为True(默认值)，则字符串将自动从 Importing 字符集转换为输出字符集。与header_encode()不同，电子邮件正文中的字节边界和多字节字符集没有问题，因此通常很安全。

编码类型(base64 或带引号的可打印格式)将基于* body_encoding *属性。

Charset类还提供了许多支持标准操作和内置函数的方法。

• __str__ ( )

  • 返回* input_charset *作为强制转换为小写的字符串。 repr()是str()的别名。

• __eq__(其他)

  • 此方法使您可以比较两个Charset实例的相等性。

• __ne__(其他)

  • 此方法使您可以比较两个Charset实例的不平等性。

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

• email.charset. add_charset(* charset * [，* header_enc * [，* body_enc * [，* output_charset *]]])
  • 将字符属性添加到全局注册表。

• charset *是 Importing 字符集，并且必须是字符集的规范名称。

可选的* header_enc 和 body_enc 要么是_表示带引号的可打印字符，_表示 base64 编码，否则是Charset.SHORTEST表示最短的带引号的可打印字符或 base64 编码，或者是None表示无编码。 SHORTEST仅对 header_enc *有效。默认为None(不编码)。

可选的* output_charset *是输出应位于的字符集。调用方法Charset.convert()时，转换将从 Importing 字符集到 Unicode，再到输出字符集。默认设置是输出与 Importing 相同的字符集。

• input_charset 和 output_charset *在模块的字符集到编解码器 Map 中都必须具有 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 *)
  • 添加一个编解码器，该编解码器将给定字符集中的字符与 UnicodeMap。

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