19.1.13. "email.encoders": 编码器
*********************************

**源代码:** Lib/email/encoders.py

======================================================================

此模块是旧版 ("Compat32") email API 的组成部分。 在新版 API 中将由
"set_content()" 方法的 *cte* 形参提供该功能。

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

当创建全新的 "Message" 对象时，你经常需要对载荷编码以便通过兼容的邮件
服务器进行传输。 对于包含二进制数据的 *image/** 和 *text/** 类型的消息
来说尤其如此。

"email" 包在其 "encoders" 模块中提供了一些方便的编码。 这些编码器实际
上由 "MIMEAudio" 和 "MIMEImage" 类构造函数使用，以提供默认编码。 所有
编码器函数只接受一个参数，即要编码的消息对象。 它们通常提取有效数据，
对其进行编码，并将有效数据重置为此新编码的值。 他们还应该根据需要设置
*Content-Transfer-Encoding* 标头。

请注意，这些函数对于多段消息没有意义。 它们必须应用到各个单独的段上面
，而不是整体。如果直接传递一个多段类型的消息，会产生一个 "TypeError"
错误。

下面是提供的编码函数：

email.encoders.encode_quopri(msg)

   将有效数据编码为quoted-printable形式，并将:mailheader:*Content-
   Transfer-Encoding`标头设置为``quoted-printable`* [1]. 。当大多数实
   际的数据是普通的可打印数据但包含少量不可打印的字符时，这是一个很好
   的编码。

email.encoders.encode_base64(msg)

   将有效载荷编码为 base64 形式，并将 *Content-Transfer-Encoding* 标头
   设为 "base64"。 当你的载荷主要包含不可打印数据时这是一种很好用的编
   码格式，因为它比 quoted-printable 更紧凑。 base64 编码格式的缺点是
   它会使文本变成人类不可读的形式。

email.encoders.encode_7or8bit(msg)

   这并不实际改变消息的有效载荷，但它会基于载荷数据将 *Content-
   Transfer-Encoding* 标头相应地设为 "7bit" 或 "8bit"。

email.encoders.encode_noop(msg)

   这样什么都不会做；它甚至不会设置 *Content-Transfer-Encoding* 标头。

-[ 註解 ]-

[1] 请注意使用 "encode_quopri()" 编码格式还会对数据中的所有制表符和空
    格符进行编码。
